Tutorial 01: Sprite and text tweak

Make: Change the Pallet Town sign, then recolor Mew using the player's imported art.

Before you start: Beginner. Complete Tutorial 00 first. The sign is the immediate result; the art check also uses the Save Editor on a practice save.

Game: Red, local single-player. Use a practice save for experiments. If file creation is new to you, start with Tutorial 00; unfamiliar words are in the Glossary.

1. Set up the files

Create a new tutorial_01 folder in your mod location. Disable earlier tutorial mods for this exercise. The starting state is this empty folder; the finished state is all the files below.

This is a mod folder, not the engine root. Do not replace the engine's own main.lua. Preserve filenames and avoid an extra .txt extension.

Finished folder layout:

mods/tutorial_01/
  main.lua
  manifest.json
  transforms.lua

Each link opens a complete file you can save at the matching path. The JSON and Lua are also printed in full below; do not append them to another lesson's entry function.

File in this mod	Complete example
main.lua	Download main.lua
manifest.json	Download manifest.json
transforms.lua	Download transforms.lua

2. Describe the mod

Complete file: replace tutorial_01/manifest.json:

{
  "id": "tutorial_01",
  "name": "Tutorial 01",
  "version": "1.0.0",
  "entry": "main.lua",
  "api": 2,
  "assets_transforms": "transforms.lua",
  "games": [
    "red"
  ]
}

id is the stable internal name, name is the label in MODS, and entry tells the loader which Lua file to open. games limits these examples to Red. Keep commas between JSON fields and no comma after the last field.

3. Write the change

Complete file: replace tutorial_01/main.lua:

return function(mod)
  mod.content.text:override("_PalletTownSignText", "MODDED SIGN.\nHello from a mod!")
end

Complete file: replace tutorial_01/transforms.lua:

return function(ctx)
  local front = ctx.readImage("battle/front/mew.png")
  ctx.writeImage(ctx.recolor(front, {{255,255,255},{255,170,200},{180,60,120},{40,0,20}}), "battle/front/mew.png")
end

Understand what you wrote

main.lua replaces one text entry. \n inside the quoted message starts a new line; it is not two separate pieces of dialogue.

assets_transforms in the manifest names a second file. The loader runs that file with ctx, a small set of image tools. readImage opens Mew's front sprite from the player's imported cache. recolor maps its four shades to four colors, and writeImage stores the result at the same relative path.

This is a transform: the mod distributes instructions, and each player's machine supplies its own imported pixels. The PNG is not part of this example's downloads. The game's palette settings can affect the final displayed colors; test the rendered result as well as the file loading.

The two files return different functions: mod changes content, while ctx processes images. Keep the recolor code in transforms.lua, not inside main.lua.

4. Load and check it

Save every file, restart the app, enable the mod for Red in the launcher's MODS panel, and launch. Resolve any load error before checking gameplay. Troubleshooting shows where errors appear. With default desktop bindings, A is Z/Enter/Space, B is X/Backspace, and Start is Escape/keypad Enter; use your configured controls if different.

Optional source-checkout validation

If you have Python 3, LuaJIT, and the engine source with Red imported, open a terminal in the engine root containing tools/. For a mod installed in that checkout's mods directory, run:

python3 tools/modkit.py validate tutorial_01 --base imported

If you saved it elsewhere, replace the mod ID with the quoted full path to its folder. A validation error identifies a file or content rule to fix; a pass means you can continue to the in-game checks. It does not prove rendering, sound, or the entire playthrough works. Packaged-app users can use MODS errors and the checkpoints without setting up these command-line tools.

Checkpoint

1. Read the freestanding town sign in Pallet Town. It should say MODDED SIGN. followed by Hello from a mod!.
2. For the art check, save and close a practice Red game. Open that slot with the launcher's Edit control, add Mew to the party, save, and close the editor. Follow the Save Editor guide if this is your first edit.
3. Launch that slot with this mod enabled. Open Mew's party summary to inspect its front sprite. Compare with the same screen after disabling the mod and restarting. Mew has no ordinary early-game encounter, so do not search Route 1 for it.
4. Change the sign message first; then change one color triple. Restart after each edit so you can tell which change caused the result.

Common pitfalls

What you see	What to check
Sign changes but art does not	Check the manifest's assets_transforms filename, the imported Red assets, and transform errors in MODS.
Colors look different from the RGB numbers	Check the active palette or color pack; compare the same screen and palette with the mod on and off.

For syntax, missing-file, and restart problems, use Troubleshooting. Compare the whole finished file before changing several things at once.

Undo and continue

Disable the mod and restart to compare with the original Red behavior. Keep a copy of your finished files if you want to return to them.

For original replacement art that can be included directly in a mod, follow Art Pipeline. The transform API and override precedence are explained there.

Return to the tutorial index to choose the next lesson.