Cookbook Items And Balls

Cookbook — items and balls

Mechanism: Concepts: Registries; worked path: Tutorial 04.

R08 — Add a Mart item

mod.content.items:register("MODBERRY", {
  id = "MODBERRY", name = "MODBERRY", price = 250, tossable = true,
})
mod.content.text_pointers:patch("ViridianMart", {
  TEXT_VIRIDIANMART_CLERK = { mart = { __append = { "MODBERRY" } } },
})

Checkpoint: the Viridian clerk sells MODBERRY. Marts are mart lists on clerk TEXT entries in the text_pointers deep registry; __append extends the shelf, a bare list replaces it.

R09 — Define an item use effect

mod.content.item_effects:register("MODBERRY_EFFECT", {
  use = function(...) ... end,
  field = true, battle = true, needsTarget = true,
})
mod.content.items:patch("MODBERRY", { effect = "MODBERRY_EFFECT" })

Checkpoint: modkit validate accepts both records and the effect merges to Data.item_effects with the item's effect reference resolved. Vanilla use behavior lives in src/inventory/ItemEffects.lua; its result-verb contract — "consumed", "kept", "failed", "ball", "learn" — is the shape a use handler speaks.

R10 — Add a new Poke Ball

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,
})

Checkpoint: thrown in battle, MODBALL catches better than an Ultra Ball (randMax 150). The fields are the real Gen 1 math (src/battle/Catching.lua); autoCatch = true is the Master Ball behavior, and attempt = fn replaces the roll outright.