JARVIGManual

ECS and scene model

Package: @jarvig/ecs. Snapshot schema: @jarvig/scene-schema (jarvig.scene/v1). ADR: ADR-0009.

PlayCanvas's useful idea is entity, component, and system. JARVIG keeps that and separates stable identity from hot storage.

LayerContract
Entity IDStable UUID. Hierarchy via parentId.
Component schemaVersioned fields plus editor and replication metadata.
StorageDense, archetype, or SoA where that proves useful. Phase 0 is a map.
SystemQueries data and schedules work. Not implemented as a scheduler yet.
PrefabTemplate graph plus explicit overrides. Not implemented.
Runtime-only stateEphemeral simulation data. Excluded from saves unless promoted.

Phase 0 API

  • ComponentRegistry.register stores name, version, replicated, and field metadata (kind, optional min / max).
  • Scene.createEntity preserves a caller-supplied UUID or allocates one. Duplicate ids throw. Parents must already exist.
  • setParent rejects cycles.
  • addComponent checks the registered schema. Unknown fields, missing fields, and range errors throw.
  • duplicate allocates a new id, keeps the parent, and copies component data.
  • serialize / Scene.fromSnapshot round-trip jarvig.scene/v1. A version mismatch throws migration required. There is no silent downgrade and no migrator yet.

The sample schema used in tests is Health (current, max, replicated: true). It is not a gameplay system.

Hot archetype storage, prefabs, and the decorator-style authoring syntax in the founding doc (@component, @field) are future API sugar over this registry. Do not add a parallel component system beside it.

Golden fixture: tests/golden/health-scene.json. Ticket JRV-0013.