Custom game options

A mod can add toggles (on / off) and value lists (a dropdown) to the RULES list in the lobby, next to "Fog of war" or "Lock diplomacy". The host picks them, everyone sees them, and your scripts read the choice with Mod_GetOption("id") (toggle) or Mod_GetOptionValue("id") (list). Both are script API 6.

Example: examples/options-example (the "Héroes veloces" toggle and the "Velocidad de héroes" list).

Quick way

create-option.js writes the JSON and, if you want, a script skeleton. It doesn't need the DATA folder.

node tools/create-option.js mods/mi-mod heroes-veloces --name "Héroes veloces" --name-en "Fast heroes" --description "Todos los héroes se mueven un 50 % más rápido."
node tools/create-option.js mods/mi-mod velocidad-heroes --name "Velocidad de héroes" --values "Normal,Rápida,Muy rápida" --default Normal --script

The first makes a toggle; with --values (2 to 16, comma-separated) it makes a list.

It generates options\<id>.json and, with --script, data\mod\<id>.vs. It tells you how many of the 8 bits it uses and how many the mod already has. It never overwrites anything: if the mod already has that id, it stops without writing.

Doing it by hand

1. An options\<id>.json file in your mod.

   A toggle:

   {
     "id": "heroes-veloces",
     "name": { "spanish": "Héroes veloces", "english": "Fast heroes" },
     "description": { "spanish": "Todos los héroes se mueven un 50 % más rápido.", "english": "All heroes move 50% faster." },
     "default": false
   }
   

   A list (2 to 16 values):

   {
     "id": "velocidad-heroes",
     "name": { "spanish": "Velocidad de héroes", "english": "Hero speed" },
     "values": [
       { "id": "normal", "name": { "spanish": "Normal", "english": "Normal" } },
       { "id": "rapida", "name": { "spanish": "Rápida (+25 %)", "english": "Fast (+25%)" } },
       "Muy rápida"
     ],
     "default": "normal"
   }
   

   • id: letters, numbers, _ and -, up to 32. Scripts use it; it's case-insensitive. If missing, the file name is used.
   • name and description: one text, or one per language (the game's language, falling back to English).
   • values: each one is a text or an object with id and name. The first is 0.
   • default: for a toggle, true or false; for a list, the value's number (from 0) or its id. An id that doesn't exist silently falls back to 0; validate-mod.js catches it.

2. A script that reads it (a class behavior, an event or a victory script):

   if (Mod_GetOption("heroes-veloces")) {
       This.AsUnit().SetSpeedFactor(150);
   }
   if (Mod_GetOptionValue("velocidad-heroes") == 1) {
       This.AsUnit().SetSpeedFactor(125);
   }
   

   Mod_GetOption returns true if the value isn't 0 (lists too). Mod_GetOptionValue returns the number of the chosen value.

Limits

• There are 8 bits for all the options of all active mods. A toggle uses 1; a list uses 1 for 2 values, 2 for 3 or 4, 3 for 5 to 8, and 4 for 9 to 16. They're taken in alphabetical order of id; whatever doesn't fit is ignored and the log says so. If two options share an id, the game uses the first one it finds when it assembles the mods.
• They only work with a lobby. Options are fixed when a game starts from the lobby (or when you rejoin an online one). Adventures, campaigns and tutorials have no lobby: Mod_GetOption always returns 0 and a list is 0, even with "default": true.
• The lobby presets (Classic, Competitive) don't touch mod options.

Online

This is gameplay: every player must have the same mod. The option travels with the other lobby rules and is saved with the game.