Skip to content

fix(render): let a host hold a render state back without committing it - #387

Closed
han4wluc wants to merge 2 commits into
mainfrom
fix/commit-presented-render-states
Closed

han4wluc wants to merge 2 commits into
mainfrom
fix/commit-presented-render-states

Conversation

@han4wluc

Copy link
Copy Markdown
Contributor

Problem

createEffectsHandler commits a render state as soon as the host's render returns, and the engine builds the next state's BGM audio effects from the committed state.

A host may be unable to draw a state at once, for example while the state's assets load. If such a host draws only the latest state it held back, the engine and the screen disagree about which music is playing:

  1. On a menu, the reader picks a choice whose section fades to new music. The host holds that state back; the engine commits it.
  2. The reader picks another choice before the first one is drawn. The engine builds "fade out the first section's music, fade in the second".
  3. The host draws only the second state. Its fade-out targets music the renderer never started, which a strict renderer rejects with audioEffects[0].targetId "bgm:..." does not resolve to an audio node.

Fix

A host can now tell the handler that it held a state back:

  • routeGraphics.render(renderState) returning false leaves the state uncommitted.
  • effectsHandler.commitRenderState(renderState) commits it when the host draws it. It returns true when it committed the state.
  • A held state is never committed when the host skipped it for a later state, when a later state was already committed, or when it was held before reset() or dispose().

Hosts whose render returns nothing (or any value other than false) behave exactly as before. A host that draws every held state later, in order, needs no change and must not return false; docs/RouteEngine.md describes both choices.

Tests

spec/createEffectsHandler.heldRenderStates.test.js (new):

  • Handler contract: immediate commit for undefined, true and other values; a held state committed once by the host; a skipped held state; a held state dropped when a later state is drawn at once; held states committed in order; an unknown state; states held before reset() and dispose().
  • With the real engine: a menu whose two choices each fade to their own music, and a host that draws only the latest held state. When the host reports held states, every audio effect targets music in the previously drawn or the current state. A companion test shows the same host without reporting produces the fade-out of music that was never drawn.

bun run test (2607 tests), bun run lint and bun run build pass.

This changes the host contract only; no render state output changes, so there is no visual test for it.

Version

Bumps route-engine-js to 1.51.1.

The built-in effects handler commits a render state as soon as the host's
render returns, and the engine builds the next state's BGM audio effects
from the committed state. A host that holds a state back while its assets
load, and then draws only the latest held state, was left with effects for
music it never drew: after two quick section changes the second state
faded out the first section's music, which a strict renderer rejects.

A host render can now return false for a state it holds back. The handler
leaves that state uncommitted, and the host commits it with
effectsHandler.commitRenderState(renderState) when it draws it. Held
states that are skipped for a later one, or held before a reset, are never
committed. Hosts that return nothing keep the current behaviour.
@han4wluc

Copy link
Copy Markdown
Contributor Author

Closing: the problem this addressed is fixed in the host, which now draws held render states in order, so nothing needs this API. The branch is kept in case a host that draws only the latest held state needs it later.

@han4wluc han4wluc closed this Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant