The RouteEngine is the core runtime for RVN visual novels. It manages state, processes actions, and coordinates rendering.

Initializes the engine with project data and global settings.

Localization is not implemented in the current runtime. The planned patch-based l10n model is documented in L10n.md.

The engine will:

1. Create the system store with initial state
2. Append a render effect
3. Execute any actions on the initial line
4. Trigger pending effects handler
5. Clear pending effects

Resolves authored layout references into renderer-facing fields without mutating the input value.

It resolves:

• textStyleId into textStyle
• colorId into fill
• imageId into src
• nested interaction references such as hover.colorId, clickImageId, and rightClick.colorId

It uses the same strict rules as the engine render-state pipeline, so inline authored textStyle, fill, and sprite src fields still throw.

Dispatches a single action to the system store.

Dispatches multiple actions from an object. Optionally accepts event context for _event.* payload bindings.

When eventContext is provided, action payloads can use _event.* bindings to reference event values. Action payloads can also reference ${variables.*} and they will be resolved at runtime. eventContext only supports _event for event data; using event will throw. Invalid _event.* bindings fail fast with an explicit error.

The integration layer should pass event context when handling events:

Layout authoring uses project resource references, not the renderer-facing fields that RouteGraphics consumes directly.

• textStyleId resolves through resources.textStyles to renderer textStyle
• imageId / hoverImageId / clickImageId resolve through resources.images to renderer src, hover.src, and click.src
• colorId / hover.colorId / click.colorId / rightClick.colorId resolve through resources.colors to renderer fill

This resolution happens during render-state construction, before RouteGraphics parses the layout tree.

Layout text should be authored with textStyleId and resolved through resources.textStyles. Authored inline textStyle objects in layout elements are rejected at render-state construction. Text transparency should be authored on the text style resource with colorAlpha and strokeAlpha, not baked into the shared color resource itself. Whole-node transparency still uses the element alpha. resources.colors[*].hex must be opaque hex only.

Layout sprite elements should be authored with imageId and optional hoverImageId / clickImageId. Authored inline sprite src and interaction hover.src / click.src fields are rejected at render-state construction. Legacy url, hoverUrl, and clickUrl fields are also rejected.

If resources.images[imageId] exists, the engine resolves the sprite to that image resource's fileId. Otherwise, the rendered imageId string is passed through directly, which allows dynamic values such as save preview image keys. Before RouteGraphics parses the layout, the engine resolves these IDs to sprite-facing src, hover.src, and click.src fields.

Layout rect elements should be authored with colorId and optional hover.colorId / click.colorId / rightClick.colorId. Authored inline rect fill and interaction hover.fill / click.fill / rightClick.fill fields are rejected at render-state construction. Before RouteGraphics parses the layout, the engine resolves these IDs to rect-facing fill fields.

Processes actions attached to the current line. Called automatically on line changes.

Returns the current render state for the renderer.

Returns the current presentation state.

The system store exposes these selectors (called internally):

Effects queued by actions for external handling:

Actions that can be attached to lines to control presentation: