Skip to content

Commit 7eb12be

Browse files
ToolboxAidToolboxAid
committed
build(vector-runtime): harden asteroids demo to vector-only runtime path
1 parent 8f11489 commit 7eb12be

11 files changed

+277
-69
lines changed

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,24 +2,28 @@ MODEL: GPT-5.4
22
REASONING: high
33

44
COMMAND:
5-
Execute this clean progression in order.
5+
Execute this clean vector-only progression in order.
66

77
Step 1:
8-
Treat docs/pr/APPLY_PR_VECTOR_ASSET_SYSTEM.md as the docs-only acceptance boundary for the completed vector asset system build.
8+
Treat docs/pr/PLAN_PR_VECTOR_ONLY_RUNTIME.md as the governing architecture contract.
99

1010
Step 2:
11-
Treat docs/pr/PLAN_PR_ASTEROIDS_VECTOR_MIGRATION.md as the governing architecture contract for the next build slice.
11+
Create BUILD_PR_VECTOR_ONLY_RUNTIME.
12+
13+
BUILD requirements:
14+
- Remove `sprite.asteroids-demo` as an active packaged/runtime dependency for the Asteroids demo
15+
- Enforce vector-only visual requirements for ship, asteroid variants, and title treatment where configured
16+
- Preserve strict validation, packaging, runtime, debug, profiler, export, and publishing flows
17+
- Keep deterministic behavior stable
18+
- Preserve runtime handoff at `games/Asteroids/main.js#bootAsteroids`
19+
- Do not modify engine core APIs
20+
- Keep rollback notes documented, but do not keep sprite fallback as active runtime dependency
1221

1322
Step 3:
14-
Create BUILD_PR_ASTEROIDS_VECTOR_MIGRATION.
23+
Validate BUILD against docs/pr/BUILD_PR_VECTOR_ONLY_RUNTIME.md.
1524

16-
BUILD requirements:
17-
- Migrate the flagship Asteroids demo to use first-class vector assets as the preferred visual path
18-
- Use the accepted vector asset system and normalized tool naming baseline
19-
- Preserve validation, packaging, runtime, debug, profiler, export, and publishing flows
20-
- Keep existing demo behavior and gameplay loop intact
21-
- Avoid engine core API changes
22-
- Document any temporary migration fallback paths clearly
25+
Step 4:
26+
Treat docs/pr/APPLY_PR_VECTOR_ONLY_RUNTIME.md as the acceptance boundary and package results.
2327

2428
Package:
25-
HTML-JavaScript-Gaming/tmp/BUILD_PR_ASTEROIDS_VECTOR_MIGRATION_delta.zip
29+
HTML-JavaScript-Gaming/tmp/VECTOR_ONLY_RUNTIME_PR_BUNDLE_delta.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
build(vector-demo): apply vector system baseline and migrate asteroids demo toward vector assets
1+
build(vector-runtime): harden asteroids demo to vector-only runtime path

‎docs/dev/change_summary.txt‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
1-
Combined clean progression bundle that first applies the accepted vector asset system baseline and then
2-
defines the Asteroids flagship demo migration toward first-class vector assets.
1+
Clean, surgical vector-only progression bundle for Codex.
2+
Converts the Asteroids demo from vector-preferred/sprite-fallback to true vector-only runtime behavior,
3+
while preserving accepted platform boundaries and docs-first workflow.

‎docs/dev/file_tree.txt‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1-
docs/pr/APPLY_PR_VECTOR_ASSET_SYSTEM.md
2-
docs/pr/PLAN_PR_ASTEROIDS_VECTOR_MIGRATION.md
1+
docs/pr/PLAN_PR_VECTOR_ONLY_RUNTIME.md
2+
docs/pr/BUILD_PR_VECTOR_ONLY_RUNTIME.md
3+
docs/pr/APPLY_PR_VECTOR_ONLY_RUNTIME.md
34
docs/dev/codex_commands.md
45
docs/dev/commit_comment.txt
56
docs/dev/change_summary.txt

‎docs/dev/reports/vector_only_runtime_validation.txt‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Asteroids platform demo ready with 12 packaged assets.
2+
Validation: valid (0 blocking findings, 0 warnings)
3+
Packaging: Package ready with 12 assets and 9 dependencies.
4+
Runtime: Runtime loader ready with 12 assets.
5+
Gameplay: Gameplay system layer ready with 12 content bindings.
6+
Templates: Game templates ready with 3 templates.
7+
Export: Multi-target export ready for 3 targets.
8+
Publishing: Publishing pipeline ready with 5 release targets.
9+
Debug: Debug view: 12 nodes, 9 edges, 0 findings.
10+
Profiler: Performance profiler captured 4 deterministic samples.
11+
Runtime entry: games/Asteroids/main.js#bootAsteroids
12+
Visual path: vector only
13+
Required vectors: vector.asteroids.ship, vector.asteroids.asteroid.large, vector.asteroids.asteroid.medium, vector.asteroids.asteroid.small, vector.asteroids.ui.title
14+
Rollback notes: documented=true
15+
Startup roots: parallax.asteroids-overlay, parallax.asteroids-title, tilemap.asteroids-stage, vector.asteroids.asteroid.large, vector.asteroids.asteroid.medium, vector.asteroids.asteroid.small, vector.asteroids.ship, vector.asteroids.ui.title
16+
Gameplay pillars: player ship rotation, thrust, and fire; asteroid spawning, splitting, and destruction; score, lives, and wave progression; title, start, game-over, and restart loop
17+
Content paths: games/Asteroids/platform/assets/vectors/asteroids-ship.vector.json, games/Asteroids/platform/assets/vectors/asteroids-asteroid-large.vector.json, games/Asteroids/platform/assets/vectors/asteroids-asteroid-medium.vector.json, games/Asteroids/platform/assets/vectors/asteroids-asteroid-small.vector.json, games/Asteroids/platform/assets/vectors/asteroids-title.vector.json, games/Asteroids/platform/assets/tilemaps/asteroids-stage.tilemap.json, games/Asteroids/platform/assets/parallax/asteroids-title.parallax.json, games/Asteroids/platform/assets/parallax/asteroids-overlay.parallax.json
18+
[info] ASTEROIDS_PLATFORM_DEMO_READY: Asteroids demo completed strict validation, packaging, runtime, export, and publishing flows.
19+
[info] ASTEROIDS_RUNTIME_HANDOFF: Runtime handoff preserved bootAsteroids from games/Asteroids/main.js.
20+
[info] ASTEROIDS_VECTOR_ONLY_RUNTIME: Vector assets are the sole active visual runtime path for ship, asteroid variants, and title presentation.
21+
[info] ASTEROIDS_ROLLBACK_NOTES_ONLY: Rollback guidance remains documented historically and is not part of the active packaged runtime dependency set.

‎docs/dev/validation_checklist.txt‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
1-
- APPLY_PR_VECTOR_ASSET_SYSTEM is docs-only
2-
- PLAN_PR_ASTEROIDS_VECTOR_MIGRATION is docs-only
1+
- PLAN, BUILD, and APPLY docs are all present
32
- codex_commands.md and commit_comment.txt are under docs/dev
4-
- Vector assets are treated as accepted baseline before demo migration
5-
- Asteroids migration preserves strict platform boundaries
3+
- Vector-only runtime baseline is explicit
4+
- Sprite fallback is removed as active runtime dependency
5+
- Validation, packaging, runtime, debug, profiler, export, and publishing are preserved
66
- No engine core API changes are authorized
7+
- APPLY remains docs-only acceptance boundary

‎docs/pr/APPLY_PR_VECTOR_ONLY_RUNTIME.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# APPLY_PR_VECTOR_ONLY_RUNTIME
2+
3+
## Purpose
4+
Apply the completed vector-only runtime hardening as a docs-only acceptance boundary.
5+
6+
## Apply Scope
7+
- Confirm PLAN and BUILD are complete
8+
- Confirm accepted scope does not exceed BUILD
9+
- Confirm APPLY introduces no implementation expansion
10+
- Lock vector-only runtime behavior as the accepted Asteroids demo baseline
11+
12+
## Verification Summary
13+
- BUILD artifact exists and matches scope
14+
- APPLY remains docs-only
15+
- Vector-only runtime behavior is accepted as the demo baseline
16+
- Sprite fallback is no longer an active runtime dependency
17+
- No engine core API changes are required by APPLY
18+
19+
## Accepted Baseline
20+
- Asteroids demo is vector-only at runtime
21+
- strict validation, packaging, runtime, debug, profiler, export, and publishing flows remain intact
22+
- rollback guidance may remain documented historically, but not as active runtime dependency
23+
24+
## Manual Validation Checklist
25+
1. Confirm BUILD artifact exists in repo tmp path.
26+
2. Confirm APPLY bundle only contains docs/pr and docs/dev files.
27+
3. Confirm accepted scope does not exceed BUILD scope.
28+
4. Confirm no new implementation files are introduced by APPLY.
29+
5. Confirm vector-only runtime baseline is documented as accepted.
30+
31+
## Approved Commit Comment
32+
build(vector-runtime): harden asteroids demo to vector-only runtime path

‎docs/pr/BUILD_PR_VECTOR_ONLY_RUNTIME.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# BUILD_PR_VECTOR_ONLY_RUNTIME
2+
3+
## Purpose
4+
Implement the vector-only runtime hardening defined in PLAN_PR_VECTOR_ONLY_RUNTIME.
5+
6+
## Build Scope
7+
- remove active sprite fallback dependency from the Asteroids demo runtime/package path
8+
- update visual preference contracts from vector-preferred/sprite-fallback to vector-only
9+
- update validation rules and demo tests to enforce vector-only requirements
10+
- preserve strict packaging, runtime, debug, profiler, export, and publishing flows
11+
- preserve deterministic behavior and stable runtime handoff
12+
- avoid engine core API changes
13+
14+
## Required Contracts
15+
- `vector.asteroids.ship` is required
16+
- `vector.asteroids.asteroid.large` is required
17+
- `vector.asteroids.asteroid.medium` is required
18+
- `vector.asteroids.asteroid.small` is required
19+
- `vector.asteroids.ui.title` is required where title vector treatment is configured
20+
- `sprite.asteroids-demo` must not be required for packaged runtime success
21+
- rollback guidance may remain documented but not as active packaged dependency
22+
- runtime handoff remains `games/Asteroids/main.js#bootAsteroids`
23+
- no engine core APIs are changed
24+
25+
## Likely Files
26+
- `tools/shared/asteroidsPlatformDemo.js`
27+
- `tools/shared/projectAssetValidation.js`
28+
- `tools/shared/projectPackaging.js`
29+
- `tests/games/AsteroidsPlatformDemo.test.mjs`
30+
- Asteroids demo vector asset/config references as needed
31+
- docs/dev reports
32+
- no engine core API files
33+
34+
## Implemented Files
35+
- `tools/shared/asteroidsPlatformDemo.js`
36+
- `tools/shared/projectAssetValidation.js`
37+
- `tools/shared/projectPackaging.js`
38+
- `tests/games/AsteroidsPlatformDemo.test.mjs`
39+
- `docs/dev/reports/vector_only_runtime_validation.txt`
40+
41+
## Build Notes
42+
- Removed `sprite.asteroids-demo` from the active Asteroids demo registry, packaging roots, packaged asset list, and runtime asset source map.
43+
- Hardened the demo contract so required vector IDs are explicit and the demo is not ready if any required vector is missing or if `sprite.asteroids-demo` reappears as an active packaged/runtime dependency.
44+
- Preserved runtime handoff at `games/Asteroids/main.js#bootAsteroids`.
45+
- Kept rollback guidance documented historically in demo metadata and reporting without leaving sprite fallback active in the package/runtime baseline.
46+
- Preserved deterministic validation, packaging, runtime, debug, profiler, export, and publishing behavior.
47+
48+
## Verification Expectations
49+
- node checks pass on updated shared/demo files
50+
- Asteroids demo tests pass
51+
- packaging summary shows vector-only asset baseline
52+
- runtime summary shows ready state
53+
- debug/profiler/publishing remain ready
54+
55+
## Verification
56+
- `node --check tools/shared/asteroidsPlatformDemo.js`
57+
- `node --check tests/games/AsteroidsPlatformDemo.test.mjs`
58+
- `node ./scripts/run-node-tests.mjs`
59+
- Result: `107/107` explicit `run()` tests passed.
60+
61+
## Validation Summary
62+
- Demo status: ready
63+
- Validation: valid with `0` blocking findings
64+
- Packaging: ready with `12` assets and `9` dependencies
65+
- Runtime: ready with `12` loaded assets
66+
- Debug: `12` nodes and `9` edges
67+
- Publishing: ready with `5` release targets
68+
69+
## Manual Validation Checklist
70+
1. Packaged runtime no longer depends on `sprite.asteroids-demo`.
71+
2. Validation enforces vector-only requirements.
72+
3. Demo reaches ready state with vector-only assets.
73+
4. Gameplay loop remains intact.
74+
5. Deterministic output remains stable across repeated runs.
75+
6. Export and publishing remain ready.
76+
7. No engine core APIs are changed.
77+
78+
## Approved Commit Comment
79+
build(vector-runtime): harden asteroids demo to vector-only runtime path
80+
81+
## Next Command
82+
APPLY_PR_VECTOR_ONLY_RUNTIME

‎docs/pr/PLAN_PR_VECTOR_ONLY_RUNTIME.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# PLAN_PR_VECTOR_ONLY_RUNTIME
2+
3+
## Goal
4+
Define a clean, surgical migration of the Asteroids demo and platform runtime path from
5+
vector-preferred-with-sprite-fallback to true vector-only runtime behavior, while preserving
6+
accepted platform boundaries and avoiding engine core API changes.
7+
8+
## Why This PR Exists
9+
The current Asteroids vector migration is successful, but still retains `sprite.asteroids-demo`
10+
as a temporary fallback safety path. This PR removes that runtime dependency and establishes
11+
vector assets as the sole visual contract for the flagship demo.
12+
13+
## Intent
14+
- remove sprite fallback from the Asteroids runtime/package path
15+
- preserve registry, validation, packaging, runtime, debug, profiler, export, and publishing flows
16+
- keep rollback information documented, but not packaged as an active runtime dependency
17+
- keep the migration surgical and deterministic
18+
19+
## Scope
20+
- remove sprite fallback from Asteroids demo visual preference contracts
21+
- update validation rules and demo checks to enforce vector-only runtime expectations
22+
- update packaging roots and dependency inclusion so the sprite fallback is no longer required
23+
- preserve runtime handoff at `games/Asteroids/main.js#bootAsteroids`
24+
- preserve gameplay loop, debug visibility, profiler coverage, export, and publishing readiness
25+
- document rollback guidance without keeping sprite fallback in the active runtime baseline
26+
27+
## Non-Goals
28+
- No engine core API changes
29+
- No broad platform-wide removal of sprite support
30+
- No destructive removal of unrelated sprite systems from the platform
31+
- No gameplay redesign beyond what is required to harden vector-only visuals
32+
- No bypass of validation, packaging, runtime, CI, export, or publishing boundaries
33+
34+
## Current Verified Baseline
35+
- vector assets are already the preferred visual path
36+
- sprite remains only as temporary migration fallback
37+
- runtime handoff remains stable
38+
- validation/packaging/runtime/export/publishing all pass
39+
40+
## Target Baseline
41+
- Asteroids demo uses vector assets only for ship, asteroid variants, and title presentation
42+
- runtime and package manifests no longer depend on `sprite.asteroids-demo`
43+
- validation fails if vector-only requirements are not satisfied
44+
- fallback documentation remains available only as historical rollback guidance
45+
46+
## Required Asset Set
47+
- `vector.asteroids.ship`
48+
- `vector.asteroids.asteroid.large`
49+
- `vector.asteroids.asteroid.medium`
50+
- `vector.asteroids.asteroid.small`
51+
- `vector.asteroids.ui.title`
52+
53+
## Acceptance Criteria
54+
1. Validation passes with vector-only demo requirements.
55+
2. Packaging succeeds without including `sprite.asteroids-demo` as an active runtime dependency.
56+
3. Runtime loader reaches ready state from vector-only packaged inputs.
57+
4. Gameplay loop remains intact: title, start, play, score, lives, waves, game-over, restart.
58+
5. Debug and profiler surfaces reflect vector-only participation cleanly.
59+
6. Export and publishing remain ready.
60+
7. No engine core APIs are changed.
61+
62+
## Manual Validation Checklist
63+
1. Ship renders via vector asset only.
64+
2. Asteroid variants render via vector assets only.
65+
3. Title presentation renders via vector asset only where configured.
66+
4. `sprite.asteroids-demo` is not required in packaged runtime roots/assets.
67+
5. Validation reports no blocking findings.
68+
6. Packaging remains deterministic.
69+
7. Runtime reaches ready state.
70+
8. Debug graph reflects vector-only baseline correctly.
71+
9. Profiler captures deterministic vector-only samples.
72+
10. No engine core APIs are changed.
73+
74+
## Approved Commit Comment
75+
plan(vector-runtime): define vector-only runtime hardening for asteroids demo
76+
77+
## Next Command
78+
BUILD_PR_VECTOR_ONLY_RUNTIME

‎tests/games/AsteroidsPlatformDemo.test.mjs‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ export async function run() {
1515
assert.equal(first.demo.runtimeHandoff.exportName, "bootAsteroids");
1616
assert.equal(first.demo.packageResult.manifest.package.projectId, "asteroids-platform-demo");
1717
assert.equal(first.demo.definition.demo.visualBaseline.preferred, "vector");
18-
assert.equal(first.demo.definition.demo.visualBaseline.fallback, "sprite");
18+
assert.equal(first.demo.definition.demo.visualBaseline.rollbackDocumented, true);
1919
assert.deepEqual(
2020
first.demo.packageResult.manifest.package.assets.filter((asset) => asset.type === "vector").map((asset) => asset.id),
2121
[
@@ -26,10 +26,17 @@ export async function run() {
2626
"vector.asteroids.ui.title"
2727
]
2828
);
29+
assert.equal(first.demo.vectorOnly.hasSpriteRuntimeDependency, false);
30+
assert.deepEqual(first.demo.vectorOnly.missingRequiredVectorIds, []);
31+
assert.equal(
32+
first.demo.packageResult.manifest.package.assets.some((asset) => asset.id === "sprite.asteroids-demo"),
33+
false
34+
);
2935
assert.deepEqual(first, second);
3036
assert.match(first.demo.reportText, /title, start, game-over, and restart loop/i);
31-
assert.match(first.demo.reportText, /Visual path: vector preferred, sprite fallback/);
32-
assert.match(first.demo.reportText, /ASTEROIDS_SPRITE_FALLBACK/);
37+
assert.match(first.demo.reportText, /Visual path: vector only/);
38+
assert.match(first.demo.reportText, /ASTEROIDS_VECTOR_ONLY_RUNTIME/);
39+
assert.match(first.demo.reportText, /ASTEROIDS_ROLLBACK_NOTES_ONLY/);
3340
assert.match(first.demo.reportText, /Publishing pipeline ready with 5 release targets\./);
34-
assert.equal(summarizeAsteroidsPlatformDemo(first), "Asteroids platform demo ready with 13 packaged assets.");
41+
assert.equal(summarizeAsteroidsPlatformDemo(first), "Asteroids platform demo ready with 12 packaged assets.");
3542
}

0 commit comments

Comments
 (0)