Skip to content

Commit 4cf7797

Browse files
ToolboxAidToolboxAid
committed
Use the individual commit comment generated for each PR. Do not squash PR_26152_164 through PR_26152_168 into a single commit.
1 parent c12a1b2 commit 4cf7797

5 files changed

Lines changed: 492 additions & 0 deletions

‎docs/dev/reports/config_driven_game_bootstrap.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Config Driven Game Bootstrap
2+
3+
PR: PR_26152_167-config-driven-game-bootstrap
4+
Date: 2026-06-02
5+
6+
## Scope
7+
8+
- Defined config-driven game bootstrap architecture.
9+
- Defined Manifest -> Runtime flow.
10+
- Defined ProjectWorkspace -> Manifest flow.
11+
- Defined Tool output -> Manifest flow.
12+
- Eliminated user-code assumptions.
13+
- Added no runtime implementation.
14+
15+
## Bootstrap Principle
16+
17+
A first-pass config-driven game should be able to boot from validated manifest data without requiring user-authored gameplay JavaScript. Runtime code still exists in `src/engine`; authored game behavior is expressed as manifest objects, rules, assets, and input bindings.
18+
19+
## Manifest -> Runtime Flow
20+
21+
1. Runtime receives explicit `game.manifest.json` path or payload.
22+
2. Runtime parses and validates the manifest envelope.
23+
3. Runtime validates object type declarations and rule registry records.
24+
4. Runtime resolves asset, geometry, palette, and input bindings from manifest data.
25+
5. Runtime creates engine objects and components.
26+
6. Runtime attaches rules and starts the engine only after validation passes.
27+
7. Runtime logs actionable failure details and does not render partially if validation fails.
28+
29+
## ProjectWorkspace -> Manifest Flow
30+
31+
ProjectWorkspace may select a project, active manifest, active tool, active Tool State, and active palette context. It may launch tools or pass explicit manifest references into validation. It must not store gameplay objects, rules, active score, entity state, health, cooldowns, or hidden bootstrap data.
32+
33+
Expected flow:
34+
35+
1. User selects project and manifest from ProjectWorkspace.
36+
2. ProjectWorkspace passes explicit manifest reference to the runtime/tool surface.
37+
3. Runtime/tool validates the manifest and Tool State payloads independently.
38+
4. Runtime/tool reports failures visibly and does not infer missing payloads from samples or storage.
39+
40+
## Tool Output -> Manifest Flow
41+
42+
Tool outputs remain authored data. Tool State owns saved editing payloads. Game Manifest owns portable game export/import structure. A publish/export path may promote selected Tool State outputs into manifest-owned records, but ProjectWorkspace does not become the persisted owner.
43+
44+
Expected flow:
45+
46+
1. Tool saves Tool State payload.
47+
2. Project export/publish selects Tool State outputs for manifest inclusion.
48+
3. Manifest stores only approved portable fields and path/file references.
49+
4. Runtime consumes the validated manifest, not hidden tool runtime state.
50+
51+
## Eliminated User-Code Assumptions
52+
53+
- No game-specific JavaScript is required for baseline object creation.
54+
- No game-specific JavaScript is required for baseline rule execution.
55+
- No user code is required for assets, input, object types, or rule binding.
56+
- Advanced custom code may exist later, but it must be optional and explicitly declared.
57+
- Runtime helpers must not use silent defaults when manifest-required values are missing.
58+
59+
## Required Bootstrap Capabilities
60+
61+
- manifest validation before render
62+
- object/rule validation before object creation
63+
- asset binding before engine start
64+
- no hidden defaults
65+
- no sample fallback data
66+
- no ProjectWorkspace persistence assumptions
67+
- diagnostics that identify source path, manifest section, object id, rule id, and failure reason
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 bootstrap architecture.
82+
- integration - documentation/static ProjectWorkspace handoff boundary review.
83+
- contract - documentation/static manifest and Tool State ownership review.
84+
85+
## Lanes Skipped
86+
87+
- runtime - no runtime behavior changed.
88+
- samples - permanently out of scope.
89+
- recovery/UAT - no recovery behavior changed.
90+
- Playwright - not impacted.
91+
92+
## Samples Decision
93+
94+
SKIP. Samples are permanently out of scope.
95+
96+
## Playwright
97+
98+
Playwright impacted: No. This PR is docs/report-only.
99+
100+
## Blocker Scope
101+
102+
No blocker for the bootstrap report. Runtime implementation is blocked until the manifest object/rule schema and loader validation lane exists.

‎docs/dev/reports/engine_implementation_priority_plan.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Engine Implementation Priority Plan
2+
3+
PR: PR_26152_168-engine-implementation-priority-plan
4+
Date: 2026-06-02
5+
6+
## Scope
7+
8+
- Prioritized implementation order.
9+
- Identified smallest executable engine slices.
10+
- Identified required `src` capabilities.
11+
- Defined first implementation lane.
12+
- Added no runtime implementation.
13+
14+
## Priority Order
15+
16+
| Priority | Slice | Purpose | Validation Target |
17+
| --- | --- | --- | --- |
18+
| 1 | Object/rule schema contracts | Establish valid manifest object and rule records. | Targeted schema/contract tests only. |
19+
| 2 | Engine manifest validation adapter | Validate manifest object/rule sections before runtime use. | Node validation with valid/invalid fixtures. |
20+
| 3 | Runtime object factory | Convert one static object and one dynamic object into ECS entities. | Engine unit validation, no samples. |
21+
| 4 | Rule registry interpreter skeleton | Register movement and collision rules without game-specific code. | Engine unit validation with minimal fixtures. |
22+
| 5 | Asset/geometry binding adapter | Resolve manifest geometry/assets into runtime object creation. | Targeted loader validation. |
23+
| 6 | No-render failure path | Reject invalid object/rule/asset data before engine start. | Negative validation proves no partial render. |
24+
| 7 | Minimal config-driven pilot | Launch one tiny manifest-only game surface from validated data. | Targeted engine/runtime validation, no samples. |
25+
26+
## Smallest Executable Engine Slices
27+
28+
1. Add object type and rule schema definitions under the existing manifest/schema ownership surface.
29+
2. Add fixtures for one static object, one dynamic object, one movement rule, and one collision rule.
30+
3. Add validation that rejects missing `objectId`, invalid `objectType`, missing `ruleId`, invalid `ruleType`, and missing target refs.
31+
4. Add an engine adapter that reads validated object/rule data without creating a game scene.
32+
5. Add an object factory that creates ECS component data for static/dynamic records only.
33+
6. Add movement/collision rule attachment as data, then execute only after validation.
34+
35+
## Required `src` Capabilities
36+
37+
| Capability | Location Direction | Notes |
38+
| --- | --- | --- |
39+
| Manifest object/rule validation adapter | `src/engine/config` or dedicated engine manifest folder | Should consume schema-validated data and report actionable failures. |
40+
| Runtime object factory | `src/engine/ecs` or `src/engine/runtime` | Should map object declarations to `World` entities/components. |
41+
| Rule registry | `src/engine/systems` or dedicated rule folder | Should keep rule behavior shared and data-driven. |
42+
| Asset binding resolver | `src/engine/assets` or `src/engine/runtime` | Should resolve manifest asset ids/paths without hidden defaults. |
43+
| Diagnostics | `src/engine/logging` and engine events | Should emit PASS/FAIL/WARN/SKIP style loader results. |
44+
45+
## First Implementation Lane
46+
47+
First lane: `manifest-object-rule-schema-validation`.
48+
49+
Expected work:
50+
51+
- Add object type schema definitions.
52+
- Add rule registry schema definitions.
53+
- Add valid/invalid object and rule fixtures.
54+
- Add targeted validation proving object/rule records accept valid data and reject invalid data.
55+
- Do not create runtime object factories yet.
56+
- Do not launch games.
57+
- Do not touch samples.
58+
59+
## Explicit Exclusions
60+
61+
- Samples are permanently out of scope.
62+
- No sample work or validation.
63+
- No user-code requirement.
64+
- No game migration.
65+
- No runtime implementation in this stack.
66+
67+
## Validation
68+
69+
Command:
70+
71+
```powershell
72+
git diff --check
73+
```
74+
75+
Result: PASS.
76+
77+
## Lanes Executed
78+
79+
- engine - documentation/static implementation priority planning.
80+
- contract - documentation/static next-lane definition.
81+
82+
## Lanes Skipped
83+
84+
- runtime - no runtime behavior changed.
85+
- integration - no ProjectWorkspace handoff implementation changed.
86+
- samples - permanently out of scope.
87+
- recovery/UAT - no recovery behavior changed.
88+
- Playwright - not impacted.
89+
90+
## Samples Decision
91+
92+
SKIP. Samples are permanently out of scope.
93+
94+
## Playwright
95+
96+
Playwright impacted: No. This PR is docs/report-only.
97+
98+
## Blocker Scope
99+
100+
No blocker for priority planning. The first implementation lane should begin with schema/contract validation, not runtime launch.

‎docs/dev/reports/engine_object_model_baseline.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Engine Object Model Baseline
2+
3+
PR: PR_26152_164-engine-object-model-baseline
4+
Date: 2026-06-02
5+
6+
## Scope
7+
8+
- Defined the authoritative engine object model.
9+
- Mapped object types to engine ownership.
10+
- Defined Static, Dynamic, Killable, Collectible, Trigger, Projectile, Zone, and UI behavior ownership.
11+
- Identified reusable `src` capability requirements.
12+
- Added no runtime implementation.
13+
14+
## Authoritative Object Model
15+
16+
Engine objects are validated runtime records created from manifest-owned object declarations. The manifest owns authored object identity, object type, geometry references, rule references, and default configuration. Engine runtime owns entity creation, active component state, per-frame mutation, collision results, timers, and rendered output.
17+
18+
ProjectWorkspace remains coordination-only. It may identify the active project, manifest, tool, and toolState references, but it must not persist object records or runtime object state.
19+
20+
## Object Type Ownership
21+
22+
| Object Type | Manifest Owns | Engine Runtime Owns | Reusable `src` Capability |
23+
| --- | --- | --- | --- |
24+
| Static | Identity, geometry reference, render role, collision layer, blocking flag. | Entity creation, static collision participation, render participation. | `src/engine/ecs/World.js`, `src/engine/components/Components.js`, collision/render systems. |
25+
| Dynamic | Identity, geometry reference, movement rule refs, collision refs. | Position, previous position, velocity, bounds response, input-driven movement. | `MovementSystem.js`, `InputControlSystem.js`, `BoundsSystem.js`. |
26+
| Killable | Identity, max health, damage rules, death/despawn rule refs. | Current health, invulnerability, death flag, death events. | `src/engine/combat/Combat.js`, lifecycle/despawn adapters. |
27+
| Collectible | Identity, collection conditions, scoring/despawn refs. | Collection detection, collected state, removal, event dispatch. | `CollectSystem.js`, collision helpers, scoring rule adapter. |
28+
| Trigger | Identity, trigger condition, event name, cooldown rule refs. | Runtime enter/exit/contact evaluation, emitted event records, cooldown state. | Event bus, collision helpers, cooldown registry. |
29+
| Projectile | Identity, spawn refs, movement, damage, lifetime, collision refs. | Spawned instance state, movement, collision, lifetime, despawn. | `ProjectileSystem.js`, `LifecycleSystem.js`, collision/combat helpers. |
30+
| Zone | Identity, bounds/geometry, zone conditions, rule refs. | Runtime overlap tracking, enter/exit/inside events. | Collision helpers, event bus, zone adapter. |
31+
| UI | Identity, binding source, layout slot, render role. | Runtime state binding, draw/update timing, user-visible status. | Rendering/UI runtime adapters. |
32+
33+
## Required Model Fields
34+
35+
Future manifest object records should require:
36+
37+
- `objectId`
38+
- `objectType`
39+
- `geometryRef` or explicit `bounds` for zone/UI records
40+
- `rules` array
41+
- `components` or component hints for runtime creation
42+
- `visibility` or render participation where applicable
43+
44+
Runtime-created records should add only transient fields:
45+
46+
- `entityId`
47+
- active component instances
48+
- runtime timers
49+
- collision/contact state
50+
- current health/score/collected/despawn state
51+
52+
## Reusable `src` Capability Requirements
53+
54+
| Requirement | Current Capability | Gap |
55+
| --- | --- | --- |
56+
| Entity/component storage | `src/engine/ecs/World.js` | Needs manifest object factory wrapper. |
57+
| Component primitives | `src/engine/components/Components.js` | Needs object-type component mapping and additional health/rule/cooldown components. |
58+
| Movement | `src/engine/systems/MovementSystem.js` | Needs manifest-driven movement adapter. |
59+
| Collision | `CollisionSystem.js` and collision helpers | Needs layer/mask/response registry. |
60+
| Projectile lifecycle | `ProjectileSystem.js` and `LifecycleSystem.js` | Needs explicit manifest-derived defaults, no hidden fallback. |
61+
| Health/damage | `src/engine/combat/Combat.js` | Needs object model adapter and manifest damage profile mapping. |
62+
| Collection | `CollectSystem.js` | Needs manifest scoring/despawn integration. |
63+
| Zones/triggers | Event/collision primitives | Needs shared zone/trigger runtime adapter. |
64+
| UI object binding | Rendering/UI primitives | Needs manifest UI binding contract before implementation. |
65+
66+
## Validation
67+
68+
Command:
69+
70+
```powershell
71+
git diff --check
72+
```
73+
74+
Result: PASS.
75+
76+
## Lanes Executed
77+
78+
- engine - documentation/static object model baseline.
79+
- contract - documentation/static manifest and ProjectWorkspace ownership review.
80+
81+
## Lanes Skipped
82+
83+
- runtime - no runtime behavior changed.
84+
- integration - no ProjectWorkspace handoff implementation changed.
85+
- samples - permanently out of scope.
86+
- recovery/UAT - no recovery behavior changed.
87+
- Playwright - not impacted.
88+
89+
## Samples Decision
90+
91+
SKIP. Samples are permanently out of scope.
92+
93+
## Playwright
94+
95+
Playwright impacted: No. This PR is docs/report-only.
96+
97+
## Blocker Scope
98+
99+
No blocker for the baseline report. Runtime implementation is blocked until object model schema and validation are approved.

‎docs/dev/reports/engine_rule_registry_baseline.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Engine Rule Registry Baseline
2+
3+
PR: PR_26152_165-engine-rule-registry-baseline
4+
Date: 2026-06-02
5+
6+
## Scope
7+
8+
- Defined the authoritative rule registry model.
9+
- Defined rules as data-driven definitions.
10+
- Covered movement, bounce, gravity, health, damage, collision, spawn, despawn, scoring, and cooldown.
11+
- Defined manifest ownership.
12+
- Added no runtime implementation.
13+
14+
## Rule Registry Model
15+
16+
The rule registry is a manifest-owned catalog of gameplay rule definitions. Each rule is data, not executable JavaScript. Engine runtime owns validated interpretation, rule ordering, runtime state, and event output.
17+
18+
Future rule records should be addressable by stable `ruleId` and referenced from object declarations. Rule records must not store ProjectWorkspace state, samples, localStorage/sessionStorage state, auth state, or active runtime entity state.
19+
20+
## Rule Record Shape
21+
22+
```json
23+
{
24+
"ruleId": "movement.player-thrust",
25+
"ruleType": "movement",
26+
"targets": ["object.player.ship"],
27+
"parameters": {},
28+
"events": {}
29+
}
30+
```
31+
32+
This shape is a planning baseline only and is not implemented in schema or runtime.
33+
34+
## Rule Ownership
35+
36+
| Rule Type | Manifest Owns | Engine Runtime Owns | Existing Reusable Surface |
37+
| --- | --- | --- | --- |
38+
| Movement | Speed, acceleration, axes, input action refs, target object refs. | Per-frame position/velocity updates and bounds application. | `MovementSystem.js`, `InputControlSystem.js`. |
39+
| Bounce | Bounds refs, surface refs, restitution, axis. | Collision/bounds detection and velocity response. | `BounceSystem.js`, collision helpers. |
40+
| Gravity | Gravity vector, affected targets, terminal velocity. | Per-tick velocity integration. | Physics primitives and movement systems. |
41+
| Health | Max health, initial health, invulnerability duration, death refs. | Current health, death state, invulnerability timers. | `src/engine/combat/Combat.js`. |
42+
| Damage | Damage amount, source/target refs, hitbox refs, knockback. | Damage application, hit events, current health mutation. | Combat and collision helpers. |
43+
| Collision | Layers, masks, response type, blocking flag, shape refs. | Contact detection, response execution, hit event reporting. | `CollisionSystem.js`, collision helpers. |
44+
| Spawn | Spawn source, target object, interval, count limit, pattern. | Runtime timers, spawned entity creation, count tracking. | `src/engine/world/SpawnSystem.js`. |
45+
| Despawn | Lifetime, offscreen rule, on-hit/on-collect behavior. | Runtime removal/deactivation and event output. | `LifecycleSystem.js`, projectile/update helpers. |
46+
| Scoring | Event refs, point values, thresholds, bonus rules. | Active score mutation, high-score event output. | Future scoring adapter required. |
47+
| Cooldown | Action refs, duration, reset behavior, initial state. | Runtime cooldown timers and action gating. | Future cooldown adapter required. |
48+
49+
## Registry Rules
50+
51+
- Each rule must declare `ruleId`, `ruleType`, target references, and parameters.
52+
- Rule parameters must be serializable manifest data.
53+
- Rule ordering must be explicit when order matters.
54+
- Runtime-only state belongs in engine runtime, not the manifest.
55+
- Invalid rule records must reject before entity creation or render.
56+
- No rule may rely on hidden defaults in config-driven mode.
57+
58+
## Validation
59+
60+
Command:
61+
62+
```powershell
63+
git diff --check
64+
```
65+
66+
Result: PASS.
67+
68+
## Lanes Executed
69+
70+
- engine - documentation/static rule registry baseline.
71+
- contract - documentation/static manifest ownership review.
72+
73+
## Lanes Skipped
74+
75+
- runtime - no runtime behavior changed.
76+
- integration - no ProjectWorkspace handoff implementation changed.
77+
- samples - permanently out of scope.
78+
- recovery/UAT - no recovery behavior changed.
79+
- Playwright - not impacted.
80+
81+
## Samples Decision
82+
83+
SKIP. Samples are permanently out of scope.
84+
85+
## Playwright
86+
87+
Playwright impacted: No. This PR is docs/report-only.
88+
89+
## Blocker Scope
90+
91+
No blocker for the baseline report. Runtime implementation is blocked until rule schema, fixtures, and registry validation are approved.

0 commit comments

Comments
 (0)