# Implementation guide

Status: developer handoff · Version 0.1.0 · 2026-08-21

This guide is framework-neutral. It defines the order in which a renderer, editor or Scene runtime should consume the package. A Flutter/Flame, web canvas, native or engine-specific implementation may differ internally while preserving these contracts.

## 1. Load stable definitions

1. Load `data/palette.json` and `data/materials.json`.
2. Validate `data/component-catalog.json`, `data/background-catalog.json` and every Component record in `components/records/` and `components/backgrounds/` against `schemas/component.schema.json`.
3. Validate the requested Scene against `schemas/scene.schema.json`.
4. Resolve each foreground and Background Component asset by immutable ID plus version; never by display name.

Unknown optional properties may be retained for forward compatibility. Unknown required enum values must stop activation with a readable diagnostic.

## 2. Establish world space

- World basis: X southeast, Y southwest, Z vertical.
- Projection: 2:1 diamond; 128 × 64 px base tile at 1×.
- One world unit: 0.25 m.
- Vertical scale: 64 px per world unit at 1×.
- Camera uses discrete zoom tiers; authored sprite detail is never silently rescaled into a new canonical tier.

Convert world `(x,y,z)` to screen using the formula in `ISOMETRIC-SYSTEM.md`. Retain the original world coordinates for hit testing, focus traversal, sound and spatial relationships.

## 3. Build the Scene graph

Resolve `environment.background.componentId` first. Use its declared horizon, principal light vector, haze, connection methods, transition band and reflection profile to establish the environmental plate and the rules by which foreground architecture, vegetation, paths, shadows, water or atmosphere meet it.

Create layers in this order: ground, ground decals, foundations, low objects, seated entities, standing entities, architecture, high vegetation, effects, world Panels, then Overlays and Chrome outside the world compositor. Sort within a layer by projected baseline and explicit priority.

Every runtime instance keeps:

- stable instance and Component IDs;
- transform and footprint;
- placement, interaction, focus and shadow anchors;
- current state and allowed transitions;
- visibility, permission and consent requirements;
- accessible name and focus order hint;
- provenance reference.

## 4. Light and composite

Use neutral authoring light in source assets. Apply Scene key, fill, rim, ambient and local-emitter contributions at runtime where possible. If a painterly asset has baked form light, treat it as material definition, not a fixed Scene sun.

Contact shadow is mandatory. Environmental color may alter temperature and value, but may not repaint identity, skin tone, trust or permission states.

## 5. Interaction

Render states from semantic state, not pointer events alone:

`idle → proximity → hover → focus → selected → acting → resolved`

Unavailable and permission-constrained are orthogonal states. Keyboard, switch and screen-reader focus must reach the same Action target as pointer input. When an Action is consequential, authorization is evaluated against Source, Avatar, Realm, Role, Permission, Consent and Constraint immediately before execution.

## 6. Portals and transitions

Resolve a Portal destination before activating its opening state. Preserve orientation across the transition. Use the declared entry and exit anchors for Avatar placement, camera heading and focus restoration. A failed destination resolution returns the Portal to idle and exposes a plain-language reason.

## 7. Accessibility bridge

Maintain a parallel semantic tree derived from Scene instances. It must expose:

- Scene and Area names;
- ordered interactive Components;
- Source/Avatar/Ally/Actor distinctions;
- current state and available Actions;
- destination and consequence for Portals;
- accessible alternatives for ambient motion, sound and color cues.

## 8. Performance policy

Atlas or batch only assets that remain logically addressable. Pause offscreen animation. Use level-of-detail swaps at discrete zoom tiers. Cache stable environmental composite layers, but never flatten interactive state, focus, permissions or identity into inaccessible pixels.

## 9. Acceptance integration

Make `npm run validate:system` a required build step. Add engine-specific tests for projection, depth sort, hit regions, focus traversal, Portal continuity and schema migration. New Components must pass the fixture matrix before entering the canonical runtime catalog.