Tutorial 00 Your First Change

Tutorial 00 — Your first change

Make: the Pallet Town sign say HELLO FROM MY MOD!. For: a first-time programmer. Game: Red, local single-player. Before you start: launch Red successfully once and have a plain-text editor. You need no art files or command-line tools for the manual route.

1. Create the mod folder

Follow Getting Started → Where mods live to find your desktop mod location. In mods, create my_first_mod. If you already made that folder in Getting Started, use it again.

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

This main.lua belongs inside your mod folder. Do not replace the engine's own main.lua. Modding Basics shows the difference.

2. Describe the mod

Replace all of my_first_mod/manifest.json with this complete file:

{
  "id": "my_first_mod",
  "name": "My First Mod",
  "version": "1.0.0",
  "entry": "main.lua",
  "api": 2,
  "games": ["red"]
}

The displayed name is My First Mod. entry tells the loader to open main.lua. games limits this exercise to Red. JSON fields have commas between them; the last one has no trailing comma.

Save the file as plain text, keeping .json as its extension.

3. Write the change

Replace all of my_first_mod/main.lua with this complete file:

return function(mod)
  mod.content.text:override("_PalletTownSignText", "HELLO FROM MY MOD!")
end

The first and last lines tell the loader where your instructions begin and end. The middle line replaces one piece of text. The first quoted string is its ID; keep it exactly as written. The second is the new message.

Save the file. Check that neither file has an extra .txt extension. The complete main.lua example is also stored with the wiki under examples/tutorial-00/; the two full files above are everything this mod needs. The starting state is no my_first_mod folder; the finished state is exactly the tree shown above.

4. Enable the mod

Close and reopen the app. In the launcher, open MODS, find My First Mod, and enable it for Red. Launch Red. If you have other text-changing mods, turn them off for this check so you can see which mod caused the result.

If the row is missing or has an error, use Troubleshooting before continuing.

5. Read the sign

Start or continue a Red save in Pallet Town. From the starting bedroom, go downstairs and leave the house. Find the freestanding town sign outside, near the town's center. Stand next to it, face it, and press A (Z, Enter, or Space on the default desktop bindings). Do not read a house's door plaque instead: this example changes the town sign.

Expected result: the dialogue box reads HELLO FROM MY MOD!. You do not need to find a rare Pokemon or compare battle damage to see this change.

Now replace only that message in the file with I MADE THIS!. Save, restart Red, and read the sign again. You have completed the basic edit loop.

Checkpoint

• My First Mod is listed and enabled for Red without a load error.
• The town sign shows the text you saved in main.lua.
• Disabling My First Mod and restarting restores the original sign text.

No save data is added by this mod. You can delete its folder after disabling it if you no longer want it. That does not generalize to mods that add saved creatures or quests; those have their own removal instructions.

If it does not work

What you see	What to check
No mod row	Correct mods/my_first_mod folder; manifest directly inside; no .txt suffix.
JSON parse error	Compare the entire manifest, including quotes, commas, and braces.
Lua syntax error	Compare all three lines of main.lua; keep straight quotes and the closing end.
Listed but inactive	Select Red; enable the mod for Red; restart.
Original text	Save the file, restart, check the town sign rather than a house plaque, and disable competing text mods.

Optional source-checkout validation

From the engine root containing tools/, with Python 3, LuaJIT, and the Red data imported, run this if the mod is in that checkout's mods folder:

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

For a different mod location, replace my_first_mod with its quoted path. A validation pass checks the loader/data rules; the sign check verifies the actual outcome. See Modkit for output and errors.

Next

Read Modding Basics for a line-by-line explanation, or try Tutorial 01 to change art as well as text. The tutorial index lists other goals.