suaveplan/openspec/archive/2026-05-19-enterprise-gaming-ecs/tasks.md

Tasks: enterprise-gaming-ecs

Phase 1 — Scaffold

• Create gaming/engine/ecs/ with package.json (@suaveplan/ecs, version 0.1.0, sideEffects: false)
• Add tsconfig.json extending @suaveplan/typescript-config/library.json
• Add vitest.config.ts using createTestConfig()
• Wire bunx turbo lint typecheck test in turbo pipeline

Phase 2 — Error codes & constants

• Implement src/error-codes.ts — EcsError extends SuaveplanError, defineCodes for ECS.* codes
• Implement src/constants/index.ts — DEFAULT_MAX_ENTITIES, ROOT_ARCHETYPE_MASK

Phase 3 — Types

• Implement src/types/common.ts — Entity, ComponentType, ComponentDescriptor<T>, QueryMask, QueryResult, System, WorldOptions, Archetype
• Write src/types/common.md

Phase 4 — Component registry

• Implement src/core/component/component.ts — defineComponent<T>(), auto-incrementing type IDs
• Write tests and docs

Phase 5 — Archetype store

• Implement src/core/archetype/archetype.ts — bigint mask, entity roster, typed array storage for numeric components
• Write tests and docs

Phase 6 — Query engine

• Implement src/core/query/query.ts — buildQueryMask(), matchArchetype(), QueryResult with forEach
• Property-based test: query result = exhaustive entity scan filtered by component membership

Phase 7 — System registry

• Implement src/core/system/system.ts — SystemRegistry with ordered update loop, registerSystem, unregisterSystem
• Write tests and docs

Phase 8 — World

• Implement src/core/world/world.ts — createWorld(), spawn/despawn, component add/remove, tick with AbortSignal, OTel spans
• Wire @suaveplan/events entity lifecycle events
• Write tests and docs

Phase 9 — Utils

• Implement src/utils/bitset.ts — maskFromTypes(), maskHasAll(), maskHasNone(), maskHasAny()
• Write tests

Phase 10 — Integration & property tests

• tests/integration.test.ts — full ECS loop: spawn entities, add components, query, system update, despawn
• tests/property.test.ts — fast-check: entity count monotonicity, archetype mask algebra, query consistency

Phase 11 — Benchmark

• src/__benchmarks__/ecs.bench.ts — 10k spawn, 100k query iteration, 60fps tick with 10 systems

Phase 12 — Pre-publish gate

• bunx turbo lint typecheck test --filter=@suaveplan/ecs green
• bunx turbo test:coverage --filter=@suaveplan/ecs — 100% on all touched modules
• Publish: bun scripts/publish.ts --package @suaveplan/ecs