ZEngine

Status: Active planning document, reconciled with the current source tree on 2026-09-17. Scope: production scene authoring and the engine contracts it depends on.

Current baseline

The following foundations are in source: ECS/Actor/WorldTick/WorldCommands; hierarchy and transform/light render synchronization; component reflection; VFS/asset registry and import coordinator; RenderGraph; RenderResourceManager; PSO cache; ZUI; crash handling; and the current scene YAML serializer.

They are not yet a production editor-authoring stack. The current serializer still uses runtime-oriented scene data; RenderScene is borrowed/rebuilt per rendered frame rather than an immutable full-scene snapshot; editor-wide selection/history/gizmo/picking services are incomplete; and the shipped grid is a finite world-XZ compatibility pass.

The former date-based sprint tables in this file were a historical estimate, not a completion record. They are retired because they named unimplemented APIs and made obsolete dependency promises.

Critical path

stable authored SceneDocument
  -> EditorSession mutation/history boundary
  -> universal entity/scene selection and stale-safe picking
  -> native transform gizmo
  -> serialized arbitrary-orientation analytic grid
  -> cross-process, visual, validation, and long-session production gates

1. Persistent scene document

Owner: jnyfah for serializer work.

Deliver the source-of-truth scene schema defined in scene serialization: UUID entity records, stable component/field schema keys, codecs/migrations, UUID reference resolution, transactional load, deterministic atomic save, explicit unknown-data policy, and SceneGridSettings.

Exit gate: a fresh process and another machine can open a saved scene with the same identity, hierarchy, authored components, asset references, and shared grid settings. Runtime EntityIDs, actor handles, and render/GPU handles are rebuilt and never become file identity.

2. EditorSession and history

Create the exclusive main-thread editor mutation phase and bounded semantic history specified in editor undo/redo. It owns the current scene epoch, dirty/saved checkpoint, selection invalidation, transactions, and Edit/Play/scene-replacement cancellation.

Exit gate: inspector edits, entity/subtree changes, grid settings, and completed gizmo drags each commit one undoable semantic operation. Cancelled operations leave neither history nor a dirty change.

3. Generic selection and picking

Use ECS entity UUIDs/complete EntityIDs behind per-frame compact pick tokens, not actor handles or mesh-only IDs. Selection must include every supported scene object and SceneTarget::Grid, with delayed readback discarded when scene/viewport/camera/token revisions are stale.

Exit gate: delayed/out-of-date readback cannot change selection after reload, resize, camera change, Play/Stop, or a new interaction. Multi-selection and hierarchy-root normalization work for actor-backed and pure ECS entities.

4. Gizmo and grid

Implement the native gizmo as an EditorSession adapter, then replace the finite XZ grid with the scene-owned analytic U/V/N grid. Gizmo input uses ZUI capture and one transaction per drag. The renderer receives immutable editor-overlay data and declares resources through RenderGraph.

Exit gate: translate/rotate/scale works across relevant entities under hierarchy; grid supports translate/rotate only; arbitrary orientation and default world-XZ survive save/load; perspective/orthographic/depth/high-DPI visual gates are stable.

5. Production hardening

Before release, run all documented negative, recovery, cross-process, race/lifetime, validation-layer, reference-image, and long-session memory tests. Define supported hardware and GPU-budget telemetry for each target; the environment-lighting 384 MiB gate is a separate renderer policy, not a total-VRAM declaration.

No feature is complete merely because it has an API, a visual prototype, or a passing single-machine smoke test.

Parallel work that does not block authoring

The following can progress independently only after respecting their documents' boundaries: shader/import hardening, render-graph tests, PSO hardware validation, geometry residency, sky rendering, profiling, and post-processing. Do not start physics, audio, game scripting, networking, plugins, asset streaming, or platform services from retired design snippets; their documents now record the decisions required before implementation.

Ownership and generated configuration

project.json is generated by ZodiacEngineHub. It is an input to the application via --projectConfigFile, not an engine-authored scene document. In particular, rendering.environment_lighting_budget_mb is a project-level GPU policy: retain the current generated value, and make schema/default changes in ZodiacEngineHub.

Completion evidence

Each milestone requires linked tests/references and a code-reviewable implementation. The final handoff records source locations, test commands/results, supported-platform coverage, measured CPU/GPU budgets, and any explicitly accepted limitations.