Skip to content

Commit c12a1b2

Browse files
ToolboxAidToolboxAid
committed
Use the individual commit comment generated for each PR. Do not squash PR_26152_159 through PR_26152_163 into a single commit.
1 parent fa2d798 commit c12a1b2

5 files changed

Lines changed: 485 additions & 0 deletions

File tree

‎docs/dev/reports/config_driven_roadmap_baseline.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Config Driven Roadmap Baseline
2+
3+
PR: PR_26152_163-config-driven-roadmap-baseline
4+
Date: 2026-06-02
5+
6+
## Scope
7+
8+
- Established config-driven roadmap baseline.
9+
- Prioritized engine work required to support manifest-only games.
10+
- Explicitly excluded samples.
11+
- Explicitly excluded user code requirements.
12+
- Defined the next implementation lane.
13+
- Added no runtime implementation.
14+
15+
## Baseline
16+
17+
Manifest-only games require a validated data path from `game.manifest.json` to engine runtime without requiring game-specific JavaScript for baseline object/rule behavior. Custom game code may remain allowed for advanced features, but it must not be required for first-pass config-driven gameplay.
18+
19+
## Prioritized Engine Work
20+
21+
| Priority | Work | Output |
22+
| --- | --- | --- |
23+
| 1 | Manifest object type schema | Validated static/dynamic/killable/collectible/trigger/projectile/zone/UI records. |
24+
| 2 | Manifest rule schema | Validated movement/bounce/gravity/health/damage/collision/spawn/despawn/scoring/cooldown records. |
25+
| 3 | Engine manifest validation adapter | Runtime-visible validation that rejects invalid object/rule payloads before render. |
26+
| 4 | Manifest object factory | Converts validated object type records into ECS entities/components. |
27+
| 5 | Rule interpreter | Applies declarative rules through existing engine systems. |
28+
| 6 | Error/reporting contract | Logs PASS/FAIL/WARN/SKIP outcomes for manifest-driven boot and rule execution. |
29+
| 7 | First manifest-only pilot | One minimal game launches from manifest object/rule data without user-authored gameplay code. |
30+
| 8 | ProjectWorkspace handoff validation | Confirms ProjectWorkspace passes explicit manifest references and owns no runtime gameplay state. |
31+
32+
## Explicit Exclusions
33+
34+
- Samples are permanently out of scope for this stack.
35+
- No sample planning, sample validation, sample rebuild, or sample fixture work is included.
36+
- User-authored game code is not required for the manifest-only baseline lane.
37+
- No runtime implementation is included in this stack.
38+
- No schema implementation is included in this stack.
39+
40+
## Next Implementation Lane
41+
42+
Next lane: `manifest-object-rule-schema-and-validation`.
43+
44+
Expected scope:
45+
46+
- Add manifest object type schema definitions.
47+
- Add manifest rule schema definitions.
48+
- Add targeted fixtures for valid/invalid object and rule payloads.
49+
- Add targeted validation proving invalid object/rule payloads reject before runtime use.
50+
- Keep ProjectWorkspace as explicit handoff coordination only.
51+
- Keep samples out of scope.
52+
53+
## Readiness Criteria For Runtime Work
54+
55+
- Object type schema exists and validates targeted fixtures.
56+
- Rule schema exists and validates targeted fixtures.
57+
- Engine validation adapter can report actionable failures without rendering.
58+
- Existing engine systems are mapped to declarative rule types.
59+
- No silent defaults are used for manifest-required values.
60+
- ProjectWorkspace boundary is documented in every validation report.
61+
62+
## Validation
63+
64+
Command:
65+
66+
```powershell
67+
git diff --check
68+
```
69+
70+
Result: PASS.
71+
72+
## Lanes Executed
73+
74+
- engine - documentation/static roadmap baseline for config-driven gameplay.
75+
- contract - documentation/static review of manifest and ProjectWorkspace ownership boundaries.
76+
77+
## Lanes Skipped
78+
79+
- runtime - no runtime behavior changed.
80+
- integration - no ProjectWorkspace handoff implementation changed.
81+
- samples - permanently out of scope for this stack.
82+
- recovery/UAT - no recovery behavior changed.
83+
- Playwright - not impacted.
84+
85+
## Samples Decision
86+
87+
SKIP. Samples are permanently out of scope for this stack.
88+
89+
## Playwright
90+
91+
Playwright impacted: No. This PR is docs/report-only.
92+
93+
## Blocker Scope
94+
95+
No blocker for the roadmap baseline. Runtime work should begin only after the manifest object/rule schema validation lane is approved.

‎docs/dev/reports/manifest_driven_engine_audit.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Manifest Driven Engine Audit
2+
3+
PR: PR_26152_162-manifest-driven-engine-audit
4+
Date: 2026-06-02
5+
6+
## Scope
7+
8+
- Audited current engine against manifest-driven architecture.
9+
- Identified hard-coded behaviors.
10+
- Identified engine ownership gaps.
11+
- Identified config-driven readiness gaps.
12+
- Added no runtime implementation.
13+
14+
## Audit Summary
15+
16+
Current manifests are strongest for launch, assets, palette, input mapping, music/tool payloads, and object-vector geometry. Engine runtime already contains reusable systems for movement, collision, spawning, combat, rendering, and lifecycle. The missing middle is an approved manifest-owned gameplay object/rule contract plus a runtime interpreter that converts validated manifest data into engine systems.
17+
18+
## Current Manifest Readiness
19+
20+
| Surface | Status | Evidence |
21+
| --- | --- | --- |
22+
| Launch and screen | READY | `tools/schemas/game.manifest.schema.json` defines `launch` and optional `screen`. |
23+
| Assets and palette | READY | Game manifests use `tools.asset-manager-v2` and `tools.palette-manager-v2`. |
24+
| Input mappings | READY | Game manifests use `tools.input-mapping-v2`. |
25+
| Object geometry | PARTIAL | Object-vector data exists in manifests; gameplay type semantics are still game-specific. |
26+
| Object types | GAP | No manifest schema section for static/dynamic/killable/collectible/trigger/projectile/zone/UI. |
27+
| Rules | GAP | No manifest schema section for movement/bounce/gravity/health/damage/collision/spawn/despawn/scoring/cooldowns. |
28+
| Runtime interpreter | GAP | Engine systems exist, but there is no shared manifest-to-ECS/rule loader. |
29+
30+
## Hard-Coded Behavior Findings
31+
32+
| Area | Current Location | Finding |
33+
| --- | --- | --- |
34+
| Space Invaders constants | `games/SpaceInvaders/game/SpaceInvadersWorld.js` | Player size/speed, alien rows/columns, spawn interval, score cycle, lives, respawn delays, and bomb types are code-owned. |
35+
| Space Duel scoring | `games/SpaceDuel/game/ScoreManager.js` | Starting lives and extra-life step are code-owned. |
36+
| Space Duel waves | `games/SpaceDuel/game/WaveController.js` | Enemy score values, hazard score, shot score, enemy counts, hazard counts, speed ranges, cooldown ranges, and spawn rules are code-owned. |
37+
| Asteroids wave setup | `games/Asteroids/game/AsteroidsWorld.js` | Asteroid counts, safe spawn rectangles, world dimensions, spawn margins, attempts, and update step caps are code-owned. |
38+
| Asteroids runtime object bridge | `games/Asteroids/game/asteroidsObjectGeometryManifest.js` | Required object ids are manifest-related but game-specific, not yet a shared object type contract. |
39+
| Projectile defaults | `src/engine/systems/ProjectileSystem.js` | Runtime helper has default projectile size, life, color, and velocity defaults instead of manifest-required explicit values. |
40+
| Input defaults | `src/engine/systems/InputControlSystem.js` | Runtime helper defaults to arrow-key bindings when no binding data is passed. Future manifest-driven lane should reject missing bindings instead. |
41+
| Rendering defaults | `src/engine/systems/RenderSystem.js` | Runtime helper uses hard-coded stroke color, label color, and font defaults. |
42+
43+
## Engine Ownership Gaps
44+
45+
| Gap | Needed Ownership |
46+
| --- | --- |
47+
| Manifest gameplay object validation | Shared manifest schema/contract should validate object type records before runtime. |
48+
| Manifest rule validation | Shared manifest schema/contract should validate rule records before runtime. |
49+
| Manifest-to-ECS loader | Engine should map validated object/rule records to ECS components and systems. |
50+
| Rule interpreter | Engine should interpret declarative rules without embedding game-specific code. |
51+
| Error reporting | Invalid object/rule records should reject before render with actionable logs. |
52+
| No silent defaults | Runtime helpers should receive explicit manifest-derived values in config-driven mode. |
53+
54+
## Config-Driven Readiness Gaps
55+
56+
| Priority | Gap |
57+
| --- | --- |
58+
| 1 | Add manifest object type schema and fixtures. |
59+
| 2 | Add manifest rule schema and fixtures. |
60+
| 3 | Add engine validation adapter for manifest object/rule payloads. |
61+
| 4 | Add manifest-to-runtime object factory for ECS/component creation. |
62+
| 5 | Add rule interpreter for movement, collision, spawn, despawn, scoring, health, damage, and cooldowns. |
63+
| 6 | Add targeted engine validation for manifest-only game boot without sample dependency. |
64+
65+
## ProjectWorkspace Boundary
66+
67+
ProjectWorkspace remains coordination-only. It may pass explicit manifest and Tool State references into tools/runtime validation, but it must not persist gameplay objects, rules, active entity state, score state, health state, timers, or hidden defaults.
68+
69+
## Validation
70+
71+
Command:
72+
73+
```powershell
74+
git diff --check
75+
```
76+
77+
Result: PASS.
78+
79+
## Lanes Executed
80+
81+
- engine - documentation/static audit of engine and game runtime ownership.
82+
- contract - documentation/static review of manifest and ProjectWorkspace boundaries.
83+
84+
## Lanes Skipped
85+
86+
- runtime - no runtime behavior changed.
87+
- integration - no ProjectWorkspace handoff implementation changed.
88+
- samples - permanently out of scope for this stack.
89+
- recovery/UAT - no recovery behavior changed.
90+
- Playwright - not impacted.
91+
92+
## Samples Decision
93+
94+
SKIP. Samples are permanently out of scope for this stack.
95+
96+
## Playwright
97+
98+
Playwright impacted: No. This PR is docs/report-only.
99+
100+
## Blocker Scope
101+
102+
No blocker for the audit report. Config-driven implementation remains blocked on approved manifest object/rule schemas and targeted engine validation.

‎docs/dev/reports/manifest_runtime_boundary.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Manifest Runtime Boundary
2+
3+
PR: PR_26152_159-manifest-runtime-boundary
4+
Date: 2026-06-02
5+
6+
## Scope
7+
8+
- Defined the manifest-to-runtime boundary.
9+
- Defined what belongs in `game.manifest.json`.
10+
- Defined what belongs in engine runtime.
11+
- Defined authoritative ownership.
12+
- Added no runtime implementation.
13+
14+
## Boundary
15+
16+
`game.manifest.json` is the portable authored game configuration surface. It should describe what a game is and what data the runtime consumes after validation. It must not become executable code, hidden runtime state, sample fallback data, or ProjectWorkspace storage.
17+
18+
Engine runtime owns interpretation, execution, timing, rendering, input dispatch, physics, collision algorithms, audio playback, scene orchestration, and error reporting. Runtime may consume manifest data only after explicit validation and must reject invalid handoff before partial render.
19+
20+
## Belongs In `game.manifest.json`
21+
22+
| Area | Manifest Ownership |
23+
| --- | --- |
24+
| Identity | Game id, display name, folder, schema/version. |
25+
| Launch | Direct launch path and optional ProjectWorkspace launch path. |
26+
| Screen | Intended canvas/screen dimensions and viewport configuration. |
27+
| Assets | Asset ids, file/path references, roles, types, and portable metadata. |
28+
| Input | Action names and declared input bindings. |
29+
| Object geometry | Object ids, tags, shape payloads, animation states, and runtime object identity. |
30+
| Object types | Future declarative object type records such as static, dynamic, killable, collectible, trigger, projectile, zone, and UI. |
31+
| Rules | Future declarative gameplay rule records such as movement, bounce, gravity, health, damage, collision, spawn, despawn, scoring, and cooldowns. |
32+
| Tool payload references | Project/tool payload data that is already approved as manifest-owned or Tool State-owned. |
33+
34+
## Belongs In Engine Runtime
35+
36+
| Area | Runtime Ownership |
37+
| --- | --- |
38+
| Execution | Main loop, fixed tick, scene transitions, update/render order. |
39+
| Algorithms | Physics, collision resolution, pathfinding, combat application, spawn ticking, rendering transforms. |
40+
| Runtime state | Transient entity state, timers, active scene state, frame metrics, current input state, audio handles. |
41+
| Validation handling | Rejecting invalid manifest/toolState handoff before render and logging actionable failures. |
42+
| Asset resolution | Resolving manifest paths to loadable runtime resources without rewriting manifest ownership. |
43+
| ProjectWorkspace handoff | Accepting explicit manifest/toolState inputs while leaving ProjectWorkspace as coordination-only. |
44+
45+
## Authoritative Ownership
46+
47+
| Surface | Owns | Must Not Own |
48+
| --- | --- | --- |
49+
| Project | Persisted DB container and ownership boundary. | Runtime session state. |
50+
| ProjectWorkspace | Runtime-only working context and active references. | Saved game data, Tool State payloads, manifest payloads. |
51+
| Tool State | Persisted per-tool payload record. | Engine execution logic. |
52+
| Game Manifest | Portable export/import description of a game. | Database source of truth or runtime session state. |
53+
| Engine runtime | Validated execution of manifest-authored data. | Authored configuration ownership. |
54+
55+
## Current Evidence
56+
57+
- `tools/schemas/game.manifest.schema.json` currently owns schema/version, game identity, launch, screen, music, and a `tools` map.
58+
- `src/shared/contracts/gameManifestContract.js` defines Game Manifest as portable export/import format, not the database source of truth.
59+
- `src/shared/contracts/projectWorkspaceRuntimeContract.js` defines ProjectWorkspace as runtime-only and forbids persisted payload/storage fields.
60+
- `src/engine/core/Engine.js` owns runtime loop, scene updates, rendering, fullscreen layers, audio, and runtime monitoring.
61+
62+
## Validation
63+
64+
Command:
65+
66+
```powershell
67+
git diff --check
68+
```
69+
70+
Result: PASS.
71+
72+
## Lanes Executed
73+
74+
- engine - documentation/static boundary review for manifest-to-runtime ownership.
75+
- contract - documentation/static review against Game Manifest, Tool State, and ProjectWorkspace contracts.
76+
77+
## Lanes Skipped
78+
79+
- runtime - no runtime behavior changed.
80+
- integration - no ProjectWorkspace handoff implementation changed.
81+
- samples - permanently out of scope for this stack.
82+
- recovery/UAT - no recovery behavior changed.
83+
- Playwright - not impacted.
84+
85+
## Samples Decision
86+
87+
SKIP. Samples are permanently out of scope for this stack.
88+
89+
## Playwright
90+
91+
Playwright impacted: No. This PR is docs/report-only.
92+
93+
## Blocker Scope
94+
95+
No blocker for the documentation boundary. Future implementation is blocked until object type and rule contracts are explicitly promoted into manifest schema/runtime validation.

‎docs/dev/reports/object_type_foundation.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Object Type Foundation
2+
3+
PR: PR_26152_160-object-type-foundation
4+
Date: 2026-06-02
5+
6+
## Scope
7+
8+
- Defined the object type foundation.
9+
- Defined ownership and expected manifest structure.
10+
- Added no runtime implementation.
11+
12+
## Foundation
13+
14+
Object types are manifest-owned declarations that describe what an object is allowed to do. Engine runtime remains responsible for interpreting validated object type records into runtime components, systems, and transient state.
15+
16+
Object type declarations should live under a future manifest-owned object section, separate from tool payload identity and separate from ProjectWorkspace runtime state. Object geometry may continue to resolve from object-vector data, while object type declarations define gameplay semantics.
17+
18+
## Object Types
19+
20+
| Object Type | Purpose | Expected Manifest Fields | Runtime Responsibility |
21+
| --- | --- | --- | --- |
22+
| Static | Non-moving object, terrain, wall, decorative or blocking element. | `objectId`, `type: "static"`, `geometryRef`, optional `collision`, optional `render`. | Render, collision participation, no autonomous movement. |
23+
| Dynamic | Moving object that can update position or velocity. | `objectId`, `type: "dynamic"`, `geometryRef`, `movement`, optional `collision`. | Apply movement rules and runtime velocity. |
24+
| Killable | Object with health/death lifecycle. | `objectId`, `type: "killable"`, `health`, optional `damageResponses`, optional `despawn`. | Track transient health and death state. |
25+
| Collectible | Object consumed by a collector. | `objectId`, `type: "collectible"`, `collectRules`, optional `score`, optional `despawn`. | Detect collection, apply rule effects, remove or update object. |
26+
| Trigger | Object that emits actions on contact, zone entry, or event. | `objectId`, `type: "trigger"`, `triggerEvent`, `conditions`, optional `cooldown`. | Evaluate runtime conditions and emit events. |
27+
| Projectile | Moving object spawned by another object/action. | `objectId`, `type: "projectile"`, `spawn`, `movement`, `damage`, `lifetime`, optional `collision`. | Spawn, move, collide, expire, and report damage events. |
28+
| Zone | Spatial gameplay region. | `objectId`, `type: "zone"`, `bounds` or `geometryRef`, `zoneRules`. | Track enter/exit/inside behavior. |
29+
| UI | HUD/menu/status object rendered by runtime. | `objectId`, `type: "ui"`, `binding`, `layout`, `render`. | Bind runtime state to display, without owning game rules. |
30+
31+
## Expected Manifest Shape
32+
33+
```json
34+
{
35+
"objects": {
36+
"object.player.ship": {
37+
"type": "dynamic",
38+
"geometryRef": "object.asteroids.ship",
39+
"rules": ["movement.player-thrust", "collision.player", "health.player"]
40+
}
41+
}
42+
}
43+
```
44+
45+
This shape is a planning baseline only. It is not implemented in `tools/schemas/game.manifest.schema.json` yet.
46+
47+
## Ownership Rules
48+
49+
- Manifest owns object identity, object type, geometry references, rule references, and author-authored defaults.
50+
- Tool State owns editor-specific saved payloads for tools that produce object geometry or object definitions.
51+
- ProjectWorkspace owns only active references and handoff coordination.
52+
- Engine runtime owns current position, velocity, timers, collision results, health changes, collection events, spawn instances, and render frames.
53+
54+
## Current Evidence
55+
56+
- `tools/schemas/game.manifest.schema.json` currently defines object-vector geometry under `tools.object-vector-studio-v2`, but not gameplay object type declarations.
57+
- `src/engine/components/Components.js` has reusable component names such as `transform`, `velocity`, `collider`, `solid`, `lifetime`, and `tag`.
58+
- `games/Asteroids/game/asteroidsObjectGeometryManifest.js` maps required geometry ids, showing a game-specific bridge from manifest geometry to runtime use.
59+
60+
## Validation
61+
62+
Command:
63+
64+
```powershell
65+
git diff --check
66+
```
67+
68+
Result: PASS.
69+
70+
## Lanes Executed
71+
72+
- engine - documentation/static object type ownership review.
73+
- contract - documentation/static manifest ownership review.
74+
75+
## Lanes Skipped
76+
77+
- runtime - no runtime behavior changed.
78+
- integration - no ProjectWorkspace handoff implementation changed.
79+
- samples - permanently out of scope for this stack.
80+
- recovery/UAT - no recovery behavior changed.
81+
- Playwright - not impacted.
82+
83+
## Samples Decision
84+
85+
SKIP. Samples are permanently out of scope for this stack.
86+
87+
## Playwright
88+
89+
Playwright impacted: No. This PR is docs/report-only.
90+
91+
## Blocker Scope
92+
93+
No blocker for the foundation report. Implementation is blocked until a future PR adds a manifest object type schema and targeted runtime validation.

0 commit comments

Comments
 (0)