This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Tutorial 03: New species

Make: Add Emberkit, an original Fire-type species with battle pictures and a party icon, to Route 1.

Before you start: Intermediate. Complete Tutorial 02; know how to create folders and preserve filenames. This lesson supplies the art, so drawing is optional.

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_03 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_03/
  assets/emberkit_back.png
  assets/emberkit_front.png
  assets/emberkit_icon.png
  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
assets/emberkit_back.png	Download emberkit_back.png
assets/emberkit_front.png	Download emberkit_front.png
assets/emberkit_icon.png	Download emberkit_icon.png
main.lua	Download main.lua
manifest.json	Download manifest.json

Original sample front sprite (40×40 pixels):

The back image is 32×32; the party icon is 16×32 with two stacked frames. Save the PNG files as images, keeping their exact names.

2. Describe the mod

Complete file: replace tutorial_03/manifest.json:

{
  "id": "tutorial_03",
  "name": "Tutorial 03",
  "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_03/main.lua:

return function(mod)
  mod.content.pokemon:register("TUTORIAL_EMBERKIT", {
    id = "TUTORIAL_EMBERKIT", name = "EMBERKIT", dex = 152, types = { "FIRE" },
    baseStats = { hp = 45, attack = 60, defense = 40, speed = 65, special = 50 },
    catchRate = 190, baseExp = 64, growthRate = "MEDIUM_FAST",
    level1Moves = { "TACKLE" }, learnset = { { level = 7, move = "GROWL" } },
    evolutions = {}, frontSize = 5,
    spriteFront = mod.assets:path("assets/emberkit_front.png"),
    spriteBack = mod.assets:path("assets/emberkit_back.png"),
    dexEntry = {
      kind = "TUTORIAL", heightFt = 1, heightIn = 4, weight = 12,
      text = "A friendly original\nexample species.",
    },
  })
  mod.content.icons:register("TUTORIAL_EMBERKIT", {
    image = mod.assets:path("assets/emberkit_icon.png"), frames = 2,
  })
  mod.content.encounters:patch("ROUTE_1", {
    grass = { slots = { __prepend = { { species = "TUTORIAL_EMBERKIT", level = 3 } } } },
  })
end

Understand what you wrote

register creates a new record. TUTORIAL_EMBERKIT is the internal ID used by encounters and icons; EMBERKIT is the display name. Keep the ID consistent in every registration.

The species needs more than stats: its type, starting moves, growth rule, pictures, and Pokédex text all describe how the game presents it. level1Moves supplies starting moves, while learnset lists moves learned at particular levels. The empty {} for evolutions means this example has no evolution.

mod.assets:path resolves a path inside this mod. The provided front image is 40×40 pixels (frontSize = 5, measured in 8-pixel tiles); the back image is 32×32. The 16×32 icon contains two stacked 16×16 frames. Keep these dimensions while first replacing the drawing.

The encounter patch prepends one slot to Route 1's grass list. Adding a species alone does not make it appear anywhere; this separate step gives you a place to find it. Encounters are random, so a single battle does not establish whether the slot is present.

These PNGs are original project sample art from mods/examples/example_mini_conversion, generated by that example's tools/make_assets.py. They are not extracted ROM pictures. No cry file is required or registered here; custom cries are an optional later task in Audio Authoring.

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_03 --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. With a starter Pokémon and Poké Balls on a practice save, walk through Route 1 grass until Emberkit appears. Its front picture and name should display in battle.
2. Catch one. Open the party menu to see its icon, then send it into a wild battle to check its back picture.
3. For a quicker art check, use the Save Editor with this mod enabled to add TUTORIAL_EMBERKIT to a practice party. This checks presentation; it does not check the random encounter patch.
4. Replace one supplied PNG with your own original drawing at the same size and path. Restart and inspect the same screen again.

Common pitfalls

What you see	What to check
Unknown species or missing art	Compare TUTORIAL_EMBERKIT in all three registrations and confirm all three PNGs are in assets beside the entry file.
No Emberkit in the first battle	The route still has other encounter slots. Keep testing or use the editor for a controlled art preview.

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

Undo and continue

Keep the practice save and its matching mod files together. Saves can contain this example's custom content or progress. To compare with vanilla Red, disable the mod, restart, and open a separate unmodified practice slot. Do not overwrite the only copy of a modded save while its content is disabled. Save recovery explains backups.

The sample deliberately uses one starting move and no evolution. Add one feature at a time using Data Model, Art Pipeline, and the species recipes.

Return to the tutorial index to choose the next lesson.