Mod Creation/Getting Started

From Melvor Idle

A mod in Melvor Idle, much like other games with mods, is a game modification created by the player community. The modification to the game can range from a minor balance change to introducing new skills and items, or a simple quality of life improvement to a full suite of automation tools. There are various programming APIs within Melvor Idle to help you create mods, regardless of how simple or complex it is.

Prerequisites

Mods for Melvor Idle are created using JavaScript, and at least a beginner level understanding of the language, or programming languages in general, is recommended before jumping into the guides.

In addition, you should install your preference of code editor for writing JavaScript code. Some popular choices are Visual Studio Code or Notepad++.

Quick Start

Want to dive right into creating your first mod with a (mostly) blank canvas? Follow along to get started.

Project Setup

Start by creating a new empty folder for your mod. You'll want to create two files in this new folder:

  • manifest.json
  • setup.mjs

The manifest.json file is used to define metadata for your mod, or important information for Melvor Idle to know how to load your mod. Put the following code within manifest.json:

{
  "setup": "setup.mjs"
}

This tells Melvor Idle to look for a setup.mjs file and run its exported setup function. Next we'll create that function within setup.mjs:

export function setup() {
  console.log('Hello From My Mod!');
}

The export word is important here as it will let the Mod Manager access the setup function to load the mod.

Making it Do Something

You'd already have a working "mod" at this point but it's not really modifying anything yet. Let's let the setup function know we want to accept a context object (ctx for short) when setup is executed, and then patch the Skill class to double all XP gains.

export function setup(ctx) {
  ctx.patch(Skill, 'addXP').before(function(amount, masteryAction) {
    return [amount * 2, masteryAction];
  });
}

The context object will be the bread-and-butter for your mod performing game modifications. Find more information on the patch method and details on everything else possible with the context object in the Essentials guide.

Feel free to skip ahead to the Packaging and Adding Your Mod section if you want to test your mod at this point.

Using Player Input

Doubling XP is okay, but the mod would be even more useful if the player could customize the amount that the XP was being multiplied by. Luckily, that's easy with another part of the context object: mod settings.

You can define a setting for the player to change using the settings object within the context object, and modify the patch code from above to use this value instead of a value of 2:

export function setup(ctx) {
  ctx.settings.section('General').add({
    type: 'number',
    name: 'xp-multiplier',
    label: 'XP Multiplier',
    hint: 'Multiply all XP gains by this amount',
    default: 1
  });

  ctx.patch(Skill, 'addXP').before(function(amount, masteryAction) {
    const xpMultiplier = ctx.settings.section('General').get('xp-multiplier');
    return [amount * xpMultiplier, masteryAction];
  });
}

The player will then be able to open up your mod's settings from the sidebar and change the multiplier to any number they'd like.

Packaging and Adding Your Mod

Once you're ready to test your mod or make it available in the Mod Manager, you'll want to package it and upload it to mod.io.

Packaging your mod is as simple as zipping the contents in their entirety. So for the above example, you should have .zip file with a manifest.json and setup.mjs at its root.

Next you should navigate to the Mods page for Melvor Idle on mod.io and click "Add mod" next to the game's name. You'll need to enter some basic information for your mod, such as a name and summary (this is what is displayed in-game in the Mod Manager's when a mod is selected). Be sure to add relevant tags, paying special attention to the Platforms (the mod will only be downloaded and installed on the checked platforms) and Supported Game Version tags.

If you're just trying to test out your mod and don't want it available to everyone, you should uncheck "Public" under the Visibility section. This will prevent the mod from appearing in the Browse tab of the Mod Manager in-game but you can still subscribe to the mod through the mod.io website and it will still be downloaded in-game.

When using the mod.io website, you will have to use the same method for signing into the site as you used for mod.io when you first signed up for it through Melvor. The login method/email needs to match what is saved in your in-game Melvor mod section with what you use to log in to the site.

Once you've saved the current details you'll be able to add media (images, video) for the mod and, more importantly, the actual mod files themselves. In the File Manager section, click "Select zip file" and upload your packaged mod. Give it a version number in the field below, and click "Upload".

Using Your Mod

You'll now be able to subscribe, download, install, and use your mod. If you've made the mod public try searching for it in the in-game Mod Manager and subscribing to it there. Once installed, you'll need to restart the game for the mod to take effect.

If you've kept the mod private you can either go to the mod's profile URL that's on the edit page for the mod, or if you click on your profile icon on mod.io (top-right of the page) and click on "My library" you'll be able to find your mod under My Mods. Once on the mod's page click the "Subscribe" button and next time you load the game it'll be downloaded and installed.

Once installed and reloaded, you should be able to select a character and see your mod in action!

Next Steps

From here the Mod Creation/Essentials guide is strongly recommended to learn about the different modding concepts and APIs available to you.