Add support for a new hero

This guide is targeted at novices who have never touched OverPy, Node.js, or JSON data before.

1. Download DataTool. Unzip it. Place its folder somewhere you remember.

   • Recommended: %USERPROFILE%\toolchain-release\DataTool.exe, so you don't have to specify its location when running the script later.

2. Find the location of your Overwatch install folder (much better results when it is installed via Battle.net).

3. Install Node.js if not already installed. Latest LTS or v18+ should do the trick.

4. Open a command line/terminal window, navigate to the overpy folder (usually via cd /path/to/overpy-folder). Keep this open, as you'll use it a couple times throughout this guide

5. Install overpy's Node.js dependencies by running the following command: npm install

6. Open src/data/heroes.ts in your favorite text editor. Scroll to the very bottom, and add an entry for the new hero right below the previous one (all lowercase).

7. Add a en-US field with the exact name of the hero as shown in-game with the default english locale. Also add subfields for primaryFire (left click), secondaryFire (right click), ability1 (Shift), ability2 (E), ability3 (F, if the hero has one), and ultimate (Q), also with their respective en-US field set to the name of the button in-game. See example below:

   const heroKw = {
     // ...
     "previousHero": {
       // ...
     },
     "newHero": {
       "en-US": "New Hero Name as it shows in-game",
       "primaryFire": {
         "en-US": "Name of gun shot with Primary Fire"
       },
       "secondaryFire": {
         "en-US": "Name of gun shot with Secondary Fire"
       },
       "ability1": {
         "en-US": "Name of ability triggered with Shift on PC"
       },
       "ability2": {
         "en-US": "Name of ability triggered with E on PC"
       },
       "ultimate": {
         "en-US": "Name of ultimate ability"
       }
     }
   }
   //end-json

   • These have to be as they appear in game, accentuation included! For example, Lucio should be searched as "Lúcio", not "Lucio".

   • You can use the Overwatch wiki to quickly copy these https://antifandom.com/overwatch/wiki/Heroes#Hero_roster.

8. Open Overwatch, create a custom lobby, open Settings → Heroes → (new hero), and keep this screen open.

9. In src/data/customGameSettings.ts, scroll to where it says "heroes": {, then scroll to "values": {.

10. Under __generalAndEachHero__, go through each entry.

    • If the entry has an include field: add the hero's name to that list if and only if in the custom lobby settings you see that setting.

    • If the entry has an exclude field: add the hero's name to that list if and only if in the custom lobby settings you don't see that setting.

    • Entry has neither field: by default, the new hero will have this setting on. If in the custom lobby settings you don't see the setting, then create an exclude field and add the hero's name to it.

    • For example, Mercy has enablePassive (shown as "Angelic Descent" in game), so we add her to the list enablePassive.include. On the other hand, Lúcio doesn't have projectileGravity% (shown as "Projectile Gravity" in game), so we add him to the list projectileGravity%.exclude.

    • ❗The hero's name you add must match exactly with the name of the entry you added for the new hero in src/data/heroes.ts.

11. Do the same for __eachHero__.

12. Ok, now for the somewhat complex part: in case there were any settings in the custom lobby page for the hero that you haven't covered yet, or are too custom for the hero in question (for example: ability durations, enabled weapons, etc.), you will need to add an entry for your hero on the same level as the __generalAndEachHero__ and __eachHero__ entries you were modifying before. Here, create a new subentry called values, and inside add entries for the missing abilities.

    • To make this easier, you can check for other heroes who may have similar settings, and copy their setting. For example, a lot of heroes have an ability1/ability2Duration%, which is added manually in their own entry (outside of __generalAndEachHero__/__eachHero__).

    • Other heroes, like Mercy and Torbjörn, have a weaponsEnabled setting, with a dropdown menu to select which weapons the hero could use. If the new hero has a setting like that, in the entries for Mercy and Torbjörn you may find how that should be configured.

    • If your new hero has a setting that doesn't really align with a setting another hero already has, let @netux or @CactusPuppy know, and we should be able to help :).

    • Each setting you add should also have translations. Just setting the en-US translation like we did before should work for now.

    • Below is an example of how this entry would look for a new hero with an "(Ability 1) Duration Scalar" and "Weapons Enabled" setting.

    const customGameSettingsSchema = {
      // ...
      "heroes": {
        "values": {
          // ...
          "__eachHero__": { /* ... */ },
          // ...
          "otherHero": {
            "values": {
              // ...
            }
          },
          "newHero": {
            "values": {
              "ability1Duration%": {
                "values": "__percent__",
                "min": 10,
                "max": 500,
                "default": 100,
                "en-US": "(Name of Ability 1) Duration Scalar"
              },
              "weaponsEnabled": {
                "values": {
                  "all": {
                    "en-US": "All (or something like that)"
                  },
                  "weapon1": {
                    "en-US": "Name of main weapon"
                  },
                  "weapon2": {
                    "en-US": "Name of secondary weapon"
                  }
                }
              }
            }
          }
        }
      }
    }

13. By now NPM should have finished installing all modules. Next and final step is to regenerate the strings/strings.json file and add the rest of the translations to all the stuff you added in src/data/heroes.ts and src/data/customGameSettings.ts.

    To do so, run the following command (making sure you replace the value for DATATOOL_PATH and OVERWATCH_PATH): DATATOOL_PATH="/path/to/DataTool.exe" OVERWATCH_PATH="/path/to/Overwatch-install-folder" node generate-the-other-languages-doc.js --regenerateStringsFile.

    • ❗If running the script through WSL, make sure the DataTool path is using a Linux-like path (i.e. /mnt/c/blablabla), while the Overwatch path is using Windows-like path (i.e. C:/blablabla).

    • This should (re)generate the strings/strings.json file with the newest translations from the game. If not (or it made the file empty, then contact @netux or @CactusPuppy for further assistance).