gen1recomp/docs/modding.md

Native modding

The game has a built-in Lua mod runtime. Mods are installed under the LÖVE save directory in mods/<id>/ and are loaded after the verified ROM data has been imported but before the title screen is created.

Minimal mod

mods/example_mod/
├── manifest.json
└── main.lua

manifest.json:

{
  "id": "example_mod",
  "name": "Example Mod",
  "version": "1.0.0",
  "entry": "main.lua",
  "priority": 0,
  "dependencies": [],
  "optional_dependencies": [],
  "conflicts": []
}

main.lua:

return function(mod)
  mod.log:info("hello from a native mod")

  mod.content.pokemon:override("PIKACHU", {
    name = "PIKACHU",
    types = { "ELECTRIC" },
    base_stats = { hp = 35, attack = 55, defense = 40, speed = 90, special = 50 },
  })

  mod.events:on("battle.start", function(context)
    context.mod_message = "A native mod changed this battle."
  end)
end

Mods should use registries and events instead of requiring private engine modules. Registries currently cover Pokémon, moves, items, maps, tilesets, encounters, trainers, sprites, music, audio, text, scripts, and UI.

Enablement is stored in the normal persistent options.lua file alongside audio, display, and battle settings, so starting a new game does not disable the selected mods. Changes take effect after restarting the game.

The loader deliberately does not import or execute arbitrary ROM-hack patches. The supported content source remains the verified base Pokémon Red ROM plus native mods.