Cookbook UI And Infrastructure

Cookbook — UI and infrastructure

The mod object surface: Reference: The Mod Object; worked path: Tutorial 11.

R31 — Add a Start-menu entry

mod.hooks:wrap("ui.start_menu.items", function(next, game, items)
  mod.ui.insertBefore(items, "OPTION", {
    label = "QUESTS",
    onSelect = function() mod.ui.push(game, "QuestLog") end,
  })
  return next(game, items)
end)

Checkpoint: the row appears with the mod on, is gone with it off. Anchor on stable labels; a missing anchor appends. The same pattern serves ui.party.submenu, ui.options.rows, and ui.pc.items.

R32 — Register a custom screen

mod.content.screens:register("QuestLog", {
  new = function(game)
    local self = { isOpaque = true }
    function self:update(dt)
      if game.input:wasPressed("b") then game.stack:pop() end
    end
    function self:draw()
      mod.ui.Font.drawBox(0, 0, 20, 18)
      mod.ui.Font.draw("QUEST LOG", 16, 16)
    end
    return self
  end,
})

Checkpoint: mod.ui.push(game, "QuestLog") opens it, and the push_screen script command reaches it from any script row. A factory that throws is logged against the mod, never a dead end.

R33 — Persist mod state

mod.save:set("visits", (mod.save:get("visits", 0)) + 1)

Checkpoint: the value survives save/load under save.modData[<id>] — your namespace alone, quarantine-proof and removed cleanly when the mod is gone (Save Model).

R34 — Define a mod option

mod.options:define({
  { key = "hard_mode", type = "toggle", label = "HARD MODE", default = false },
})
if mod.options:get("hard_mode") then
  mod.content.moves:patch("TACKLE", { power = 50 })
end

Checkpoint: the toggle renders in the manager under your mod; changes persist in options.lua and fire mod.options_changed. Row types: toggle, choice, number, text.

R35 — Export an inter-mod API

-- in colorlib/main.lua
mod.exports.tint = function(hex) ... end

-- in a dependent mod (manifest: "dependencies": ["colorlib@^1.0"])
local color = mod.find("colorlib")
if color then color.exports.tint("#ff0044") end

Checkpoint: the dependent loads after colorlib and calls its export; with colorlib absent, find returns nil and the branch skips. Range-check color.version with require("src.mods.Semver") (a supported require) before relying on a shape.