Skip to content

W-041: ecs-prefab variants and IsA chain (PREFAB-F04)

Type: feature · Size: S · Epic: E-prefab-v0 · Target: packages/ecs-prefab · Breaking: no Depends: W-039 Refs: spec PREFAB-040..PREFAB-048

Goal

Add the isA option of createPrefab and walk the IsA chain in instantiate, nearest value wins, with a visited set. A variant holds only its own traits. Variants never change their base.

Steps

  • S1 (PREFAB-040, PREFAB-041): createPrefab(world, traits, { isA }) creates a prefab with IsA(base) and only its own traits; it throws naming createPrefab if the base is not alive or lacks Prefab, with no entity created; files: packages/ecs-prefab/src/create-prefab.ts, packages/ecs-prefab/tests/variants.test.ts
  • S2 (PREFAB-042, PREFAB-043, PREFAB-044, PREFAB-045, PREFAB-004 IsA('*') part): the chain walk copies base traits the variant lacks, nearest wins across three levels; the instance has exactly one IsA pair, to the variant; base changes made before instantiate are copied; world.query(IsA('*')) returns instances and not variants; files: packages/ecs-prefab/src/chain.ts, packages/ecs-prefab/src/instantiate.ts, packages/ecs-prefab/tests/variant-chain.test.ts
  • S3 (PREFAB-046, PREFAB-047, PREFAB-048; changeset): overrides and set on a variant instance do not change the variant or base; a self-cycle or a two-prefab cycle does not loop or throw, and each entity is visited once; several manual IsA targets are walked in pre-order, first value wins; files: packages/ecs-prefab/tests/variant-safety.test.ts, .changeset/w-041-ecs-prefab-variants.md (patch, @workspace/ecs-prefab)

Log

  • 2026-11-01 created from the approved spec split of W-005 (Triage)
  • 2026-11-01 held: waits on the OQ6 decision after the W-039 S1 spike (decision logged in W-039 first) (Triage)