Tutorial 04: New item and ball

Make: Put MODBERRY and a working MODBALL on the Viridian Mart shelf.

Before you start: Intermediate. Complete Tutorial 02. Use a practice save that can shop at Viridian Mart and has enough money.

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_04 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_04/
  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_04/manifest.json:

{
  "id": "tutorial_04",
  "name": "Tutorial 04",
  "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_04/main.lua:

return function(mod)
  mod.content.items:register("MODBERRY", {
    id = "MODBERRY", name = "MODBERRY", price = 250, tossable = true,
  })
  mod.content.items:register("MODBALL", {
    id = "MODBALL", name = "MODBALL", price = 500, ball = "MODBALL",
  })
  mod.content.balls:register("MODBALL", {
    randMax = 120, hpFactor = 10, wobbleFactor = 120,
    tossAnim = "ULTRATOSS_ANIM", flicker = true,
  })
  mod.content.text_pointers:patch("ViridianMart", {
    TEXT_VIRIDIANMART_CLERK = {
      mart = { __append = { "MODBERRY", "MODBALL" } },
    },
  })
end

Understand what you wrote

The items registry gives each item its identity, displayed name, and price. MODBERRY is a purchasable placeholder: this first file does not give it a healing effect. You can buy or toss it, but it is not yet a usable healing berry.

MODBALL has a ball field pointing to its matching balls record. That second record supplies capture parameters and reuses an existing toss animation. Registering the bag item and registering the ball behavior are separate steps.

The final patch targets Viridian Mart's clerk. Its mart value is the stock list. __append means “keep the current stock and add these entries.” Both item IDs must be in that list to make both available for purchase.

The ball's numeric fields are engine capture parameters, not displayed percentages. Keep them unchanged for this lesson; use Items and Balls when you want to study capture behavior.

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_04 --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. Visit Viridian Mart after completing the early parcel delivery so the clerk opens the ordinary shop. Speak to the clerk and choose the purchase option.
2. Confirm both MODBERRY and MODBALL appear. Buy one of each; they should appear in your bag. The existing stock should still be present.
3. Enter a wild encounter and use MODBALL from the bag. It should perform a capture attempt; a failed catch is still a working attempt and is not proof of a broken ball.
4. Confirm MODBERRY does not heal yet. To add a complete field healing effect, continue with R09, or use that page's complete berry example as a separate exercise.

Common pitfalls

What you see	What to check
Clerk gives a parcel instead of opening the shop	Finish the early parcel event on your practice save, then return.
Only one new item appears	Check that the mart __append list contains both MODBERRY and MODBALL.
Berry will not heal	That is expected in this lesson. Item behavior needs an item_effects record and an item effect field; see R09.

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.

Return to the tutorial index to choose the next lesson.