From 96ed862b50b6c8ad0f751f6a6a47e26a276be14d Mon Sep 17 00:00:00 2001 From: MaxTomahawk Date: Mon, 24 Aug 2026 10:51:09 +0200 Subject: [PATCH] docs(mod-api): clarify developer mode sources --- docs/mod-api-gen2-compat.md | 3 ++- docs/modding.md | 24 ++++++++++++++---------- docs/rfcs/0017-mod-developer-mode.md | 21 ++++++++++++--------- 3 files changed, 28 insertions(+), 20 deletions(-) diff --git a/docs/mod-api-gen2-compat.md b/docs/mod-api-gen2-compat.md index 9bda0c10..999eb583 100644 --- a/docs/mod-api-gen2-compat.md +++ b/docs/mod-api-gen2-compat.md @@ -472,7 +472,8 @@ find no runner on it, so `data.commands` under Gen 2 is the mod verbs alone. **`mod.save`, `mod.options`, `mod.log`, `mod.assets`, `mod.find`, `mod.developer`, exports.** Generation-agnostic; nothing to adapt. `mod.developer` is the same fixed boot-time boolean on both generations and is -available while the entry chunk runs. +available while the entry chunk runs. Gold does not gain Gen 1's developer +console or F5 hot-reload hotkey; the field reports the loader's mode only. **`mod.world`.** Same method set, resolved against Gold's world (`src/world/gen2/WorldAPI.lua`). Two differences show through and are diff --git a/docs/modding.md b/docs/modding.md index 45577b62..3b14d17a 100644 --- a/docs/modding.md +++ b/docs/modding.md @@ -687,17 +687,18 @@ the hook context. ## Developer console -Boot with developer mode on to unlock the in-game console and hot-reload -hotkeys. Either set `POKEPORT_DEV=1` in the environment or pass -`--developer` on the command line: +On a Gen 1 boot, developer mode unlocks the in-game console and hot-reload +hotkeys. Either set `POKEPORT_DEV=1` in the environment or pass `--developer` +on the command line: ```sh love . --developer ``` -Every sandboxed entry chunk receives the same boot decision as the boolean -`mod.developer`. It is available while the entry file is loading, so a mod can -keep diagnostic commands, screens, and verbose tracing out of player builds: +The mod loader independently derives a matching boolean for every sandboxed +entry chunk as `mod.developer`. It is available while the entry file is +loading, so a mod can keep diagnostic commands, screens, and verbose tracing +out of player builds: ```lua if mod.developer then @@ -710,11 +711,14 @@ end `mod.developer` is a plain boolean snapshot for this boot. It grants no permission and exposes neither the process environment nor the loader. In a normal player boot it is `false`; `POKEPORT_DEV=1` and `--developer` make it -`true` through the same engine-owned decision that enables the console and hot -reload. Use a mod option for player-facing feature toggles rather than treating -developer mode as configuration. +`true`. On Gen 1 those inputs separately enable the console and hot-reload +hotkeys. The headless loader's `opts.dev` test seam changes only the loader +signal and diagnostics; it does not enable the game's console or hot reload. +Gold exposes the same `mod.developer` boolean but does not implement the Gen 1 +console or hotkeys. Use a mod option for player-facing feature toggles rather +than treating developer mode as configuration. -While developer mode is active: +While developer mode is active on Gen 1: - `` ` `` (backtick) opens the console overlay — a Lua REPL with `game`, `data` and `mods` in scope. Press `` ` `` again to close it. diff --git a/docs/rfcs/0017-mod-developer-mode.md b/docs/rfcs/0017-mod-developer-mode.md index a717f8db..7d564648 100644 --- a/docs/rfcs/0017-mod-developer-mode.md +++ b/docs/rfcs/0017-mod-developer-mode.md @@ -6,10 +6,11 @@ Proposed. ## Motivation -The loader already has one boot-time developer-mode decision. It enables the -console and hot reload and can be forced in headless tests, but a sandboxed mod -cannot read it. `mod.commands` can register a diagnostic command but cannot say -whether the current boot is a developer boot. `mod.exports` only publishes +The loader already derives a boot-time developer-mode flag for its permission +diagnostics and headless test seam. Gen 1's `Game` independently derives a +similarly sourced flag for its console and hot reload. A sandboxed mod cannot +read either one. `mod.commands` can register a diagnostic command but cannot +say whether the current boot is a developer boot. `mod.exports` only publishes values to other mods. `game.ready` fires after entry registration and carries only the game. `mod.options` is player configuration, not engine mode, and `mod.log` logs unconditionally. The pre-sandbox compatibility @@ -50,15 +51,17 @@ end ``` The value is a plain boolean snapshot, not a loader reference or environment -facade. `false` is the normal player-build answer. `POKEPORT_DEV=1`, the -`--developer` command-line path, and the loader's existing injected `opts.dev` -test seam produce `true` through the same decision that already controls the -developer console, hot reload, and loader diagnostics. It grants no permission +facade. `false` is the normal player-build answer. `POKEPORT_DEV=1` and the +`--developer` command-line path make the loader flag true; on Gen 1 those inputs +separately make `Game`'s own developer flag true for its console and hot +reload. The loader's existing injected `opts.dev` test seam changes only the +loader flag and diagnostics, not `Game` or its hotkeys. It grants no permission and does not expose environment variables. The answer is fixed for the life of that loader; changing a field on a mod's own table cannot change engine mode. The field is generation-independent and has identical semantics on Red, Blue, -Yellow, Gold, and Silver. +Yellow, Gold, and Silver. Gold and Silver do not gain Gen 1's developer console +or hot-reload hotkeys from this field. ## Migration and compatibility