mirror of
https://github.com/bryanthaboi/gen1recomp.git
synced 2026-08-16 16:21:30 +02:00
AverageConsumer
55 lines
1.9 KiB
Markdown
55 lines
1.9 KiB
Markdown
# RFC 0002 — Let mods hide an active screen state from the main render
|
|
|
|
## Status
|
|
|
|
Proposed. Engine: `StateStack.lua`, `Game.lua`. Tests:
|
|
`screen_render_visible.lua`.
|
|
|
|
## Motivation
|
|
|
|
A mod can render a native menu on a companion display through
|
|
`render.compose`, but it cannot remove that menu from the main display without
|
|
also popping it. Popping transfers update and input ownership and forces the
|
|
mod to reimplement native menu behavior.
|
|
|
|
## The decision it extends
|
|
|
|
No prior D-number. Extends the render-hook plan in `docs/modding.md` and the
|
|
state-stack rendering contract in `docs/architecture.md`.
|
|
|
|
## The exact API delta
|
|
|
|
Backward-compatible, additive-only.
|
|
|
|
### `screen.render_visible`
|
|
|
|
New hook called with `(state) -> boolean` through the public wrapper signature
|
|
`(next, state)`. Its vanilla result is `true`.
|
|
|
|
Returning `false` excludes the state from the main draw, from opaque-base
|
|
selection and from palette-zone ownership. It does not remove the state or
|
|
change update, input, push or pop behavior. The call sites are
|
|
`StateStack:visibleBase`, `StateStack:draw` and the equivalent draw and palette
|
|
walks in `Game:draw`.
|
|
|
|
The hook is guarded by `Runtime.wantsHook`, so the no-subscriber path allocates
|
|
nothing. It is a pure render predicate and may be evaluated more than once per
|
|
frame.
|
|
|
|
## Migration note for existing mods
|
|
|
|
**Nothing.** With no subscriber every state remains visible, and the existing
|
|
state-stack, event and hook behavior is unchanged.
|
|
|
|
## Parity tests
|
|
|
|
- **No-mod:** the topmost opaque state still owns drawing and palette zones,
|
|
and `Runtime.wantsHook("screen.render_visible")` stays false.
|
|
- **Mod-API:** a fixture mod registers through `mod.hooks:wrap`, hides one
|
|
opaque state and proves the state beneath draws and owns the palette while
|
|
the hidden state remains topmost and continues updating.
|
|
|
|
## Deprecation etiquette
|
|
|
|
Nothing deprecated. This is one additive hook with a `true` vanilla default.
|