Tutorial 06 NPC And Dialogue

Tutorial 06 — NPC and dialogue

Make: Add a stationary character in Pallet Town who greets you when you talk to them.

Before you start: Intermediate. Complete Tutorial 00 and read tables and IDs. NPC means non-player character: a character controlled by the game.

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

Tutorials 06, 07, 08, and 11 are versions of one mod, tutorial_world. Install exactly one snapshot. Begin with an empty tutorial_world folder. Copy your current files somewhere outside the mods directory before replacing them. Keep the same mod ID and save slot as you progress.

For a fresh start, these complete starting files match this lesson's prerequisite: manifest.json, main.lua. Replace them with the finished files below as you complete the lesson.

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_world/
  main.lua
  manifest.json

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

2. Describe the mod

Complete file — replace tutorial_world/manifest.json:

{
  "id": "tutorial_world",
  "name": "Tutorial World",
  "version": "1.0.0",
  "entry": "main.lua",
  "api": 2,
  "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_world/main.lua:

return function(mod)
  mod.content.maps:patch("PALLET_TOWN", {
    objects = {
      __append = {
        {
          index = 90, x = 8, y = 7, sprite = "SPRITE_BEAUTY",
          movement = "STAY", range = "NONE", text = "TEXT_TUTORIAL_WORLD",
          name = "TUTORIAL_WORLD_NPC",
        },
      },
    },
  })

  mod.content.map_scripts:register("PALLET_TOWN", {
    talk = {
      TEXT_TUTORIAL_WORLD = {
        { "face_player" },
        { "show_text", "Welcome to the\nTutorial World!" },
      },
    },
  })
end

Understand what you wrote

The map's objects list describes characters and interactive objects. __append preserves Pallet Town's existing objects and adds one. The new object has a unique index, a sprite ID, a position, and a text ID.

x and y use player cells, each 16×16 pixels. Coordinates start at zero at the map's top-left: x increases to the right, y increases downward. The new character is at (8, 7); stand in a neighboring cell and face them. This is different from the 32×32 blocks used to build maps in Tutorial 07.

The object's text field and the key under talk must match exactly. That match connects the visible character to a list of script commands. face_player turns the character toward you; show_text opens the greeting. Commands run in order.

The map script belongs to tutorial_world, the stable mod ID used through Tutorials 06, 07, 08, and 11. You will replace this mod's files as you progress; you will not enable four competing versions.

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_world --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. Launch Red and go outside in Pallet Town. Find the new stationary character at player cell (8, 7), toward the central outdoor area.
2. Stand next to the character, face them, and press A. They should turn toward you and say Welcome to the / Tutorial World!.
3. Change just the greeting string, save, restart, and talk again. Keep the TEXT_TUTORIAL_WORLD ID unchanged so the object still finds its script.
4. Talk to an original Pallet Town character too: appending the new object should preserve the old ones.

Common pitfalls

What you see	What to check
Character appears but has no greeting	Match TEXT_TUTORIAL_WORLD in the map object and talk table, including capitalization.
Two tutorial characters overlap	Disable duplicate tutorial_world snapshots. Only one version belongs in the mods folder.

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 choices, branches, and item rewards, see Script Commands. Keep object indexes stable when saves may refer to them; changing the displayed name is different from changing an object's identity.

Return to the tutorial index to choose the next lesson.