diff --git a/docs/modding.md b/docs/modding.md index 18955af2..a9d0d38d 100644 --- a/docs/modding.md +++ b/docs/modding.md @@ -150,5 +150,19 @@ The console understands these verbs (anything else is evaluated as Lua): - `trace PAT | trace off` — trace events/hooks matching a glob pattern. - `help` — list the verbs. +## Tool input and title-menu hooks + +Tool mods that need to act once per game logic tick can wrap `input.step`. +It runs immediately before queued button edges are promoted, so input added by +the wrapper is visible during that same fixed step. The callback receives +`(next, game, dt)` and must call `next(game, dt)`. + +`ui.title_menu.items` receives `(next, game, items)` and follows the same +decorate-after-`next` convention as `ui.start_menu.items`. It is the safe place +for a tool to offer a fresh-session action before gameplay begins. + +Ephemeral tools can wrap `save.write(next, game)` and return `false` to veto a +progress write before world state is captured or any bytes reach disk. + Developer mode also arms the mod loader's dev tripwire, which flags mods that reach outside their permission set. diff --git a/src/core/Game.lua b/src/core/Game.lua index 1bad3b9f..a2709bb6 100644 --- a/src/core/Game.lua +++ b/src/core/Game.lua @@ -169,6 +169,11 @@ function Game:returnToTitle() end function Game:step(dt) + -- Tool mods (autoplay, accessibility drivers, input visualizers) act on + -- the same fixed-step boundary as a physical controller. Run them before + -- Input:step promotes queued edges so a button chosen here is visible to + -- this logic tick, not one tick later. With no wrapper this is a no-op. + ModRuntime.call("input.step", function() end, self, dt) self.input:step() -- serviced unconditionally: a link battle's ENet transport must not -- stall just because PartyMenu/ChoiceBox/NamingScreen is temporarily @@ -476,6 +481,11 @@ end -- Capture the live world state into the save table and persist it. -- Options are flushed to options.lua as part of SaveData.save. function Game:writeSave() + -- Tool sessions can be deliberately ephemeral. Give them one narrow veto + -- before captureSave mutates the snapshot or any progress bytes reach disk. + if ModRuntime.call("save.write", function() return true end, self) == false then + return false + end if self.overworld and self.overworld.captureSave then self.overworld:captureSave(self.save) end @@ -486,7 +496,7 @@ function Game:writeSave() if ModRuntime.wants("save.writing") then ModRuntime.emit("save.writing", { save = self.save, meta = self.save.meta }) end - SaveData.save(self.save) + return SaveData.save(self.save) end -- Persist options.lua only (Options menu / hotkeys 2-5). Keeps settings diff --git a/src/script/Commands.lua b/src/script/Commands.lua index 25022d57..1be48be4 100644 --- a/src/script/Commands.lua +++ b/src/script/Commands.lua @@ -676,11 +676,15 @@ function Commands.record_hall_of_fame(ctx) if game.overworld then game.overworld.lastOutdoor = ctx.save.lastOutdoor end - if game.writeSave then game:writeSave() end + local saveAllowed = true + if game.writeSave then saveAllowed = game:writeSave() ~= false end -- writeSave's captureSave re-stamps the live HALL_OF_FAME coords; -- re-apply home and persist so CONTINUE resumes in the bedroom. SaveData.applyPostGameHome(ctx.save, boot) - SaveData.save(ctx.save) + -- A tool session may veto Game:writeSave to keep its in-memory run + -- isolated from the player's real save. The relocation write is part + -- of that same save operation and must honor the same decision. + if saveAllowed then SaveData.save(ctx.save) end end) end) runner:yield() diff --git a/src/ui/TitleState.lua b/src/ui/TitleState.lua index 979d24d7..9564516f 100644 --- a/src/ui/TitleState.lua +++ b/src/ui/TitleState.lua @@ -7,6 +7,8 @@ local Font = require("src.render.Font") local Music = require("src.core.Music") local GameVersion = require("src.core.GameVersion") local Strings = require("src.core.Strings") +local Runtime = require("src.mods.Runtime") +local Logger = require("src.core.Logger") local TitleState = {} TitleState.__index = TitleState @@ -136,6 +138,8 @@ local function hasSave() return ok and info ~= nil end +local function sameItems(_, items) return items end + -- The CONTINUE info window (main_menu.asm DisplayContinueGameInfo): -- PLAYER / BADGES / POKéDEX / TIME over the title, shown after choosing -- CONTINUE. A confirms and loads the game, B returns to the main menu. @@ -211,6 +215,13 @@ function TitleState:openMenu() love.event.quit() end end }) + local hooked = Runtime.call("ui.title_menu.items", sameItems, game, items) + if type(hooked) == "table" then + items = hooked + else + Logger.error("ui.title_menu.items returned %s; keeping the vanilla items", + type(hooked)) + end local th = #items * 2 + 2 local menu = Menu.new(game, items, { tx = 0, ty = 0, tw = 13, th = th }) -- full-width title LOGO zones would recolor this box; see sgbPalettes diff --git a/tests/engine/tool_mod_hooks.lua b/tests/engine/tool_mod_hooks.lua new file mode 100644 index 00000000..d53ffb2e --- /dev/null +++ b/tests/engine/tool_mod_hooks.lua @@ -0,0 +1,92 @@ +-- Public seams a tool mod needs: a fixed-step input hook and a +-- title-menu entry point. Both are no-ops without a mod (gate_hooks.lua +-- covers that parity); this case proves a real public wrapper can act at the +-- correct point and decorate the real title menu. + +package.path = "./?.lua;./?/init.lua;" .. package.path + +local T = require("tests.modkit") +local Hooks = require("src.mods.Hooks") +local Runtime = require("src.mods.Runtime") + +local savedEvents, savedHooks, savedErrors = + Runtime.events, Runtime.hooks, Runtime.errors +local hooks = Hooks.new() +Runtime.hooks = hooks + +-- If input.step disappears, or moves after Input:step, a bot's buttons land +-- one logic tick late. Exercise Game:step itself and pin the observable +-- ordering rather than merely checking that a hook was registered. +do + local order = {} + local fake = { + input = { step = function() order[#order + 1] = "input" end }, + stack = { update = function(_, dt) + order[#order + 1] = "world" + T.eq(dt, 1 / 60, "the world receives the fixed-step dt") + end }, + save = {}, + } + hooks:wrap("input.step", function(nextFn, game, dt) + T.check(game == fake, "input.step receives the live Game object") + T.eq(dt, 1 / 60, "input.step receives the fixed-step dt") + order[#order + 1] = "hook" + return nextFn(game, dt) + end, 0, "tool_fixture") + + require("src.core.Game").step(fake, 1 / 60) + T.eq(table.concat(order, ","), "hook,input,world", + "input.step runs before input edges are promoted and before gameplay") + hooks:removeOwner("tool_fixture") +end + +-- If ui.title_menu.items disappears, a tool mod can load but has no +-- safe user-facing way to begin a fresh, non-destructive run. +do + local TitleState = require("src.ui.TitleState") + local stack = { states = {} } + function stack:push(state) self.states[#self.states + 1] = state end + function stack:top() return self.states[#self.states] end + local game = { + data = { field = { title = { cycleSpecies = { "MEW" } } }, + pokemon = { MEW = {} } }, + stack = stack, + } + + hooks:wrap("ui.title_menu.items", function(nextFn, liveGame, items) + T.check(liveGame == game, "ui.title_menu.items receives the live Game") + table.insert(items, #items, { label = "AUTOPLAY" }) + return nextFn(liveGame, items) + end, 0, "tool_fixture") + + TitleState.new(game, {}):openMenu() + local menu = stack:top() + T.eq(menu.items[#menu.items - 1].label, "AUTOPLAY", + "ui.title_menu.items can insert AUTOPLAY before EXIT GAME") + hooks:removeOwner("tool_fixture") +end + +-- A viewer/AI session must be able to veto every normal progress-save path, +-- including the in-game SAVE menu and autosaves, before captureSave mutates +-- the live snapshot in preparation for disk IO. +do + local captured = false + local fake = { + save = {}, + overworld = { captureSave = function() captured = true end }, + } + hooks:wrap("save.write", function(nextFn, game) + T.check(game == fake, "save.write receives the live Game object") + return false + end, 0, "tool_fixture") + + local saved = require("src.core.Game").writeSave(fake) + T.eq(saved, false, "save.write can veto progress persistence") + T.eq(captured, false, "a veto happens before save-state capture") + hooks:removeOwner("tool_fixture") +end + +Runtime.events, Runtime.hooks, Runtime.errors = + savedEvents, savedHooks, savedErrors + +T.finish("tool_mod_hooks") diff --git a/tests/engine/tool_save_safety.lua b/tests/engine/tool_save_safety.lua new file mode 100644 index 00000000..31ae39a7 --- /dev/null +++ b/tests/engine/tool_save_safety.lua @@ -0,0 +1,46 @@ +-- End-game persistence must honor a Game:writeSave veto so an ephemeral tool +-- session cannot overwrite the player's real save while THE END is on screen. + +package.path = "./?.lua;./?/init.lua;" .. package.path +if not _G.love then _G.love = require("tests.love_stub") end + +local T = require("tests.modkit") +local Commands = require("src.script.Commands") +local SaveData = require("src.core.SaveData") +local Screens = require("src.ui.Screens") + +local originalPush, originalSave = Screens.push, SaveData.save +local screens = {} +local directWrites = 0 + +Screens.push = function(_, id, onDone, onTheEnd) + screens[id] = { onDone = onDone, onTheEnd = onTheEnd } + return screens[id] +end +SaveData.save = function() + directWrites = directWrites + 1 + return true +end + +local save = SaveData.newGame() +save.party = {} +local game = { + data = { field = { boot = {} } }, + save = save, + writeSave = function() return false end, +} +local runner = { yield = function() coroutine.yield() end } +local ctx = { game = game, save = save, runner = runner } +local co = coroutine.create(function() Commands.record_hall_of_fame(ctx) end) +local ok, err = coroutine.resume(co) +T.check(ok, "Hall of Fame command reaches its UI yield: " .. tostring(err)) +T.check(screens.HallOfFame ~= nil, "Hall of Fame induction was requested") + +screens.HallOfFame.onDone() +T.check(screens.Credits ~= nil, "credits were requested after induction") +screens.Credits.onTheEnd() +T.eq(directWrites, 0, + "a vetoed Hall of Fame autosave performs no fallback disk write") + +Screens.push, SaveData.save = originalPush, originalSave +T.finish("tool_save_safety")