Scripting and Extensions Instructions

From Melvor Idle
This page is out of date (v1.0.3).
This article is about installing scripts and extensions. For a list of scripts and extensions, see Scripting and Extensions.
Disclaimer: It is highly recommended to BACKUP YOUR SAVE before running any scripts or extensions.

Disclaimer: Do not run code you cannot understand or do not trust. Malicious code could be included in any script and extension. If you are unsure whether a script is safe to use, please ask in the Scripting and Extensions channel on the Melvor Idle Discord before installing.

This page covers the steps required to install mods on both the Steam and web browser (PC) versions of Melvor Idle.

Before You Begin

It's highly recommended before doing anything to

  1. Back up your save by exporting or downloading the save file.
  2. Read all instructions before following them.
  3. Verify the code is not malicious.

Steam

For ease of installation, Melvor Mod Manager (M3) is highly recommended. However, if you know what you are doing then a manual installation is also possible.

Notes from the SEMI Dev

Unless you know what you are doing, M3 is absolutely the recommended method of installing scripts. I (TheAlpacalypse) personally use M3 and can attest to it working perfectly with SEMI. If you are unclear what any of the below instructions say, simply follow the M3 installation instructions.

Melvor Mod Manager (M3)

Melvor Mod Manager (M3) is an open-source tool that allows for the easy installation and management of mods (scripts and extensions) for the Steam edition of Melvor Idle.

DISCLAIMER: It is very important to use discretion when installing mods through M3 to ensure a mod does not execute malicious code! If you are unsure, ask in the Scripting and Extensions Discord channel.

  1. Download and install the latest version of M3:
    • For Windows, an installer may be downloaded from here.
    • For MacOS or Linux, you can compile your own executable by following these instructions.
  2. Launch M3 and click Browse at the top and locate the installation directory for Melvor Idle.
    • Not sure where it's installed? Go to Melvor Idle in your Steam library, right click, and go to ManageBrowse local files.
  3. You can now install mods in three different ways:
    • The Discover tab enables one-click installation of popular mods.
    • From File: You can add mods from either a script (.js) file or extension manifest (manifest.json) file.
    • From URL: Add scripts using their GreasyFork URL, e.g. https://greasyfork.org/en/scripts/434472-keybindings
  4. Click Launch and start using your mods!

Manual Installation

To use console commands, scripts, and extensions on Steam without M3, follow the instructions in Setup and Loading Scripts. There is an alternate variation that may result in a cleaner Melvor Idle folder, but requires additional setup steps.

Setup

You only have to do this once.

  1. Download Melvor Idle on Steam, and find the installation folder. e.g. [...]/steamapps/common/Melvor Idle
    • Not sure where it's installed? Go to Melvor Idle in your Steam library, right click, and go to ManageBrowse local files.
  2. Download the NW.js SDK (Windows: v0.54.0; other OS: v0.49.2). The version might change in the future, but you need the specific one listed.
  3. Download the scripts and extensions you want to use, a list is available on the Scripting and Extensions page
  4. Extract all zipped files.
  5. Place the contents of the nwjs-sdk* folder in the Melvor Idle installation folder.
    • The current contents of the nwjs-sdk-v0.54.0-win-x64 folder has 22 total items. Moving this to the Melvor Idle folder will overwrite over 100 existing files.
    • If it didn't ask you to overwrite any files then you did something wrong.
  6. Place the icons, styles, and source directories (i.e. scripts or sources) of the extracted extensions in the Melvor Idle installation folder.

Option 1: Loading Scripts

Loading scripts must be run every time the game is opened on Steam.

  1. Open the game and load a character.
  2. Open the dev tools console by either:
    • Pressing F12.
    • Right clicking in the game and selecting Inspect. You may need to switch from Element to Console.
  3. Set the context of the console to game.
    • The top left of the console has a dropdown: change it from top to game (steam.melvoridle.com). After doing this, you can use the console.
  4. Load the scripts and extensions you placed in the installation folder before.
    • You can load SEMI like this:
      require('fs').readFile('scripts/SEMI.js', 'utf8', (err, data) => {
          if (err) console.error(err);
          else eval(data);
      });
      $(document.head).append(`<link rel="stylesheet" href="${chrome.runtime.getURL('styles/semi.css')}">`);
    • You can load the Combat Simulator like this:
      require('fs').readFile('sources/contentScript.js', 'utf8', (err, data) => {
          if (err) console.error(err);
          else eval(data);
      });
      $(document.head).append(`<link rel="stylesheet" href="${chrome.runtime.getURL('styles/mainStyle.css')}">`);
    • You can load user scripts like this, by changing the file name:
      require('fs').readFile('relativePathToMyReallyCoolScript.js', 'utf8', (err, data) => {
          if (err) console.error(err);
          else eval(data);
      });

Option 2: Alternate Variation

The following variant results in a cleaner directory without potential file name clashes. Note that the above does not clash for Combat Simulator + SEMI at the moment.

Additional Setup

Do all the normal steps 1-5 of the Setup section then follow the below instructions.

  1. Create a folder Extensions in the Melvor Idle installation folder.
  2. Make new directories for the extensions and scripts. e.g.
  3. Extensions/
      Greasy Fork/
        Melvor Completion Log Helper.js
        Melvor Idle - Timestamped Saves.js
      Melvor-ETA/
        time-remaining.js
      MICS-steam/
        icons/
        sources/
        styles/
      scripts/
        nameOfMyReallyCoolScript.js
      SEMI-steam/
        icons/
        scripts/
        styles/
    
  4. Place the icons, styles, and source (i.e. scripts or sources) directories of the extracted extensions in the Melvor Idle installation folder.
  5. If you are using extensions, edit the main extension script so all source files and icons can be found.
    • e.g. edit the paths in contentScript.js for Combat Simulator and SEMI.js for SEMI
    • Combat Simulator:
       -icons/ -> Extensions/MICS-steam/icons/
       -sources/ -> Extensions/MICS-steam/sources/
      SEMI:
       -icons/ -> Extensions/SEMI-steam/icons/
       -scripts/ -> Extensions/SEMI-steam/scripts/
      

Alternate Variation Loading Scripts

If you followed the alternate variation setup steps, you will have to load scripts slightly differently.

  1. Open the game and load a character.
  2. Open the dev tools console by pressing F12.
    • You can also open the console by right clicking in the game and selecting Inspect. You may need to switch from Element to Console.
  3. Set the context of the console to game.
    • The top left of the console has a dropdown: change it from top to game (steam.melvoridle.com). After doing this, you can use the console.
  4. Load the scripts and extensions you placed in the installation folder before.
  5. [
        // own
        'Extensions/scripts/nameOfMyReallyCoolScript.js',
        'Extensions/Melvor-ETA/time-remaining.js',
    
        // extensions
        // other than the main script, extensions typically also require the insertion of a css file
        'Extensions/MICS-steam/sources/contentScript.js',
        //'Extensions/SEMI-steam/scripts/SEMI.js',
    
        // Greasy Fork user scripts
        'Extensions/Greasy Fork/Melvor Completion Log Helper.js',
        'Extensions/Greasy Fork/Melvor Idle - Timestamped Saves.js',
    ].forEach(pts => require('fs').readFile(pts, 'utf8', (err, data) => {eval(data);}));
    
    // Extension css
    [
        'Extensions/MICS-steam/styles/mainStyle.css',
        //'Extensions/SEMI-steam/styles/semi.css',
    ].forEach(cssFile => $(document.head).append(`<link rel="stylesheet" href="${chrome.runtime.getURL(cssFile)}">`));
    

Auto-loading Scripts in Steam

  1. Follow the setup instructions.
  2. Create a autorun.js file in the Melvor Idle folder.
  3. Edit autorun.js using a text editor:
    • The 15000 is just to give the game 15 seconds to get up and running, it doesn't seem to matter if it fires on the character screen or once you load a character.
    setTimeout(function(){ 
         /*insert all of the commands you would normally put in the console to load your scripts*/
    }, 15000);
  4. Add "inject_js_end": "autorun.js" to the parameters of package.json, which should look like this:
  5. "node-remote":["*://*"], "inject_js_end": "autorun.js"}

FAQ

Common issues and solutions with installation.

Q: I can't get the console to work!
A: You must download the specific version in the instructions. Newer versions will not work or help.

Make sure to move the contents of nwjs-sdk*, not the entire folder.

Q: The console won't open when I hit F12.
A: If you followed the proper nwjs installation instructions and the console still does not open when you press F12, you may have to change your Steam screenshot button. Alternatively, you can open the console by right-clicking the game and clicking Inspect.

Q: I installed nwjs but nothing works.
A: When you move the contents of nwjs-sdk*, you will be asked to overwrite over 100 files to your Melvor Idle folder. If you don't get this prompt, you didn't select the right files/folders.

Web Browser (PC)

Extensions

Extensions are independent add-ons that run in the browser. The installation method varies depending on the browser:

Some extensions might require you to edit specific files or set specific variables before they can run. The page with the download link will usually have a more detailed explanation on how to install.

Remember to refresh the game for the extension to take effect.

User Scripts

User scripts are scripts that run with the help of user script manager browser extensions such as Greasemonkey or Tampermonkey.

If the source of your user script is a user script repository, such as Greasyfork, simply Install by clicking the button on the page.

If the user script is shared through a plain text sharing site, such as Pastebin, copy the code into a new user script in your user script manager browser extension.

Remember to refresh the game for the user script to take effect.

Console Scripts

The simplest form of scripts are JavaScript code that are pasted directly into the console of of your browser.

To access the console open Developer Tools (usually by pressing F12) in your browser and navigate to the console. Then, simply paste the code in the input field and press enter. Most console scripts will require you to fill out variables in the code before executing them.

Do note that unlike extensions and user scripts, console scripts will run without refreshing the game, but will in turn not be saved when the game is closed.

Add Dev/Non-Main Branch Extensions to Chrome

Why do this?

Allows you to get the bleeding edge updates whilst the devs are working on a new patch. If you are a patron and want to use SEMI on the test builds, this is how.

This method is not recommended if you do not understand what a command line is.

Simple Installation

Disclaimer: This installation method will never automatically update. It now requires you to understand how to use a terminal, node, and npm. DO NOT MESSAGE THE DEV IF YOU CANNOT FIGURE THIS OUT. Wait for the extensions to release.

  1. Download and install Node.js if you do not already have it.
  2. Download and install npm if you do not already have it.
  3. Navigate to https://gitlab.com/aldousWatts/SEMI or whichever repo you want.
  4. On the left hand of the header, you should see a drop-down containing the word main. Click the dropdown, then select dev.
  5. You should see a button in the header with a download icon. Click download, then .zip.
  6. After the download completes, put the folder wherever you like. Extract the zip.
  7. Open the folder in a terminal.
  8. Run the command npm install && npm run build. You might see several hundred errors. This is fine.
  9. Run the command node build.js
  10. Open the link chrome://extensions/, enable Developer Mode in the top right.
  11. Click the button Load unpacked in the header.
  12. Navigate to the dist folder. This should contain a manifest.json. Afterwards, click Select Folder.
  13. After the extension loads, click update.
  14. If you have the Chrome extension from the web store, ensure that you remove it.
  15. Refresh the game.

Managing Dev/Non-Main Branch Extensions With git

This installation method will automatically fetch updates from dev/non-main branches.

  1. Open your terminal to the location you want the folder to go.
  2. Type the command git clone [email protected]:aldousWatts/SEMI.git into your terminal.
  3. After it finishes cloning into the folder, cd into the folder then run git fetch && git checkout <branchname>.
  4. Open the link chrome://extensions/, enable Developer Mode in the top right.
  5. Click the button Load unpacked in the header.
  6. Navigate to the top-level directory of the unpacked extension. For SEMI, this is the one that contains the manifest, README, etc. Afterwards, click Select Folder.
  7. After the extension loads, click update.
  8. If you have the Chrome extension from the web store, ensure that you remove it.
  9. Refresh the game.