gen1recomp/docs/rfcs/0019-pokemon-level-visible.md

RFC 0019: pokemon.level_visible — a level a mode can take off the screen

Status

Proposed.

Motivation

A Pokémon's level is printed on four Gen 1 surfaces — both battle healthboxes, the party rows, and page 1 and page 2 of the status screen — and every one of them prints it unconditionally. There is no seam. A mode that wants the number gone has exactly two options today, and both are bad.

It can paint over the text from render.hud, which means knowing four pixel rectangles, matching the background shade, and surviving the palette flashes and the healthbox slide-in. Or it can monkey-patch the drawing modules from inside its sandbox, which works — require hands a mod the engine's own table — and is precisely what CONTRIBUTING-mods.md tells mods not to do. A mod that took the second road already deleted its patching layer once, for the reasons that document gives.

The motivating case is a battle royale where every party is scaled to a shared rung that rises with the fog. The number on the healthbox is therefore never news — it is the same for everyone, it changes on a clock, and a player reading :L37 on an opponent learns nothing except that they are playing the same match. Worse, it reads as a threat it is not: a Lv37 opponent looks dangerous to a player who has not worked out that their own team is Lv37 too. The mode wants the level off the HUD and out of the party list, and the announcement it replaces it with is one line about everyone getting stronger at once.

Nothing about that is specific to a battle royale. A randomizer that hides levels to keep an encounter unreadable, a challenge run that forbids level-checking, a hard mode that withholds an opponent's level, and a "blind" Nuzlocke all want the same switch, and none of them should have to learn where the <LV> glyph lives.

The decision it extends

This extends the additive, guarded seam convention Route B in CONTRIBUTING-mods.md documents, and is gated by the parity guarantee tests/engine/gate_meta_coverage.lua enforces.

It sits with the presentation predicates already on the battle screen — battle.status_hud_visible, battle.bottom_ui_visible and battle.caught_marker_visible — and takes the same shape: a hook consulted behind Runtime.wantsHook, defaulting to visible, where only an explicit false suppresses. The difference is that a level is not a battle-only readout, so this one is not named battle.* and carries the surface that asked.

There is no in-repo D-number registry to amend.

Exact API delta

New hook: pokemon.level_visible

mod.hooks:wrap("pokemon.level_visible", function(next, mon, ctx)
  -- ctx = { where = "battle.enemy" | "battle.player" | "party" | "summary",
  --         game = <Game> }
  if myMode.active and ctx.where ~= "party" then
    return false      -- the level is not printed on that surface
  end
  return next(mon, ctx)   -- true: printed, as today
end)

Default true. Only an explicit false suppresses; nil and every other value print, so a wrapper that forgets a branch cannot blank a screen by accident.

ctx.where names the surface rather than the widget, because the number means different things on different screens: on a battle HUD an opponent's level is information about them, on the party and status screens your own level is information about you. A mode that wants to hide the first and keep the second can, and the motivating mode does exactly that.

New module: src/ui/LevelDisplay.lua

One function, LevelDisplay.visible(mon, where, game), wrapping the wantsHook/call pair. It exists so the four call sites are a one-line guard each instead of four copies of the same five lines, and so the hook has one definition of "visible" rather than four that can drift.

Call sites

Surface	File	where
Enemy healthbox	src/battle/BattleState.lua	battle.enemy
Player healthbox	src/battle/BattleState.lua	battle.player
Party rows	src/ui/PartyMenu.lua	party
Status page 1 and 2	src/ui/SummaryMenu.lua	summary

No layout moves. Each site keeps its own hand-rolled PrintLevel rule (home/pokemon.asm:335-345 — the <LV> tile, then the digits, with a level of 100 writing its third digit back over the tile); it just asks first.

Two details are deliberate:

• A status condition still replaces the level on a healthbox, exactly as it does in the cart, so hiding the level never hides PSN or BRN. The guard is an elseif on the existing status branch, not a wrapper around it.
• On status page 2 the <to> arrow is hidden with the level it points at. The arrow introduces the next level; on its own it is half a sentence. The EXP-to-next-level figure beside it is a different field and still prints.

No other surface changes

No event, no registry, no save field, no manifest key.

Migration

None. The hook is additive and defaults to current behaviour.

Verification

• tests/modkit/cases/pokemon_level_visible.lua — the contract through the public mod API: default true with no mod, false suppresses, the surface and the mon reach the hook, falling through prints, and a nil mon answers rather than throwing.
• tests/engine/gate_hooks.lua — the structural parity gate picks the hook up automatically, because it walks the live catalog rather than a list.
• tests/engine/gate_meta_coverage.lua — the coverage ratchet; the seam is covered by name from the change that introduces it, so it never enters the DEBT ledger.

Backward compatibility

A build with no mod wrapping the hook never reaches Runtime.call: wantsHook is checked first, which matters because two of the four sites are on a per-frame draw path. Pixels are unchanged, and the parity gates assert it.

Scope, and what is deliberately not in this change

Gen 1 only. The Gen 2 screens keep their own level readouts (src/ui/gen2/PartyMenu.lua, SummaryMenu.lua, BoxMenu.lua, HallOfFame.lua) and do not consult the hook. So does the Gen 1 PC box list (src/ui/BoxMenu.lua), where the level is baked into a row label string rather than drawn as a field, and the box-to-PNG print path beside it.

Those are mechanical follow-ups, held back so this change stays reviewable against screens that can actually be exercised here. The limitation is stated in docs/modding.md beside the hook, so a mod author reads it before depending on it rather than after.

Compatibility seam for older engines

There is none, and none is possible without patching: the call sites are mid-draw, so a mod on a stock engine cannot reach them. That is the argument for the seam rather than a gap around it — the alternatives available to a mod today are painting over the engine's own pixels or reaching into its render modules, and the second is the thing the mod contract exists to prevent.