Modding With an AI Assistant

The Windows version of the game ships with written instructions that let an AI assistant build mods for you: characters, enemies, items, reskins, levels, cutscenes, palettes, audio and Lua scripts.

Any assistant that can read and write files in a folder on your computer will do. That means a coding agent you run on your machine or in an editor, not a plain chat window in a browser, which cannot reach the game folder. The instructions are plain text, so they work the same whichever one you use.

What ships with the game

Next to SOR2 New Era.exe:

AGENTS.md                      the entry point: points the assistant at the instructions below
.claude/skills/
  sor2-new-era-modding/        shared rules, file-format reference, JSON schemas, mod validator
  sor2-mod-setup-and-sharing/  start a mod, game rules, difficulty, export and share
  sor2-create-character/       new playable characters, enemies and bosses
  sor2-reskin-classic/         new looks for Classic characters, stages and screens; palettes
  sor2-create-level/           levels, enemy waves, cutscenes, title and ending screens
  sor2-items-and-weapons/      pick-ups, weapons and breakable containers
  sor2-audio/                  sounds, music and Classic audio replacement
  sor2-lua-scripting/          behaviour, AI, HUD and stage logic in Lua

The folder is named .claude because some assistants look there on their own, but the files inside are ordinary Markdown that any assistant can read. The folder is hidden on some systems; keep it next to the executable either way.

Using it

  1. Point the assistant at the game folder, the one containing SOR2 New Era.exe and Editor.
  2. Tell it to read AGENTS.md first. Some assistants find the instructions by themselves, but saying so costs nothing and makes sure it starts in the right place.
  3. Ask for what you want in your own words, for example "add a new enemy to my mod Street Justice that throws knives", and name the mod.
  4. Close the Character, Level and Audio editors before the assistant edits a mod: they rewrite whole files on save and would discard its changes.
  5. Test the result in game, then export it as usual. See Testing and Exporting.

Results vary with the assistant you use, and it may get things wrong. Keep a backup of a mod you care about, and check its work in game.

The assistant checks its work with the bundled validator, which needs Python. To run it yourself:

python .claude/skills/sor2-new-era-modding/scripts/validate_mod.py "Editor/<Mod Name>"

For the full schema checks, install jsonschema (and Pillow for palette checks) with pip install jsonschema Pillow.

Mod editing, with or without an assistant, is only available on Windows.