Skip to content

Commit 8f11489

Browse files
ToolboxAidToolboxAid
committed
build(vector-demo): apply vector system baseline and migrate asteroids demo toward vector assets
1 parent d07d2e5 commit 8f11489

15 files changed

Lines changed: 435 additions & 35 deletions

‎docs/dev/CODEX_COMMANDS.md‎

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

44
COMMAND:
5-
Create BUILD_PR_VECTOR_ASSET_SYSTEM.
5+
Execute this clean progression in order.
66

7-
Requirements:
8-
- Implement a first-class vector asset type integrated with registry, dependency graph, validation, packaging, and runtime
9-
- Use the SVG-focused tool as the authoring bridge for vector asset output
10-
- Normalize tool naming and planned tool paths to match actual responsibilities
11-
- Ignore the original legacy SpriteEditor naming as the target standard
12-
- Preserve accepted platform boundaries and do not modify engine core APIs
13-
- Document any transitional compatibility needed for renamed tool paths
7+
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.
149

15-
Tool naming targets:
16-
- tools/Pixel Asset Studio/
17-
- tools/Tilemap Studio/
18-
- tools/Parallax Scene Studio/
19-
- tools/Vector Asset Studio/
10+
Step 2:
11+
Treat docs/pr/PLAN_PR_ASTEROIDS_VECTOR_MIGRATION.md as the governing architecture contract for the next build slice.
12+
13+
Step 3:
14+
Create BUILD_PR_ASTEROIDS_VECTOR_MIGRATION.
15+
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
2023

2124
Package:
22-
HTML-JavaScript-Gaming/tmp/BUILD_PR_VECTOR_ASSET_SYSTEM_delta.zip
25+
HTML-JavaScript-Gaming/tmp/BUILD_PR_ASTEROIDS_VECTOR_MIGRATION_delta.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
plan(vector-assets): define first-class vector asset system and normalized tool naming
1+
build(vector-demo): apply vector system baseline and migrate asteroids demo toward vector assets

‎docs/dev/change_summary.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
Adds a docs-only plan for first-class vector asset support and a normalized naming plan for editor tools.
2-
Establishes SVG authoring as the vector asset bridge and standardizes future-facing tool names/spaces.
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.

‎docs/dev/file_tree.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
docs/pr/PLAN_PR_VECTOR_ASSET_SYSTEM.md
1+
docs/pr/APPLY_PR_VECTOR_ASSET_SYSTEM.md
2+
docs/pr/PLAN_PR_ASTEROIDS_VECTOR_MIGRATION.md
23
docs/dev/codex_commands.md
34
docs/dev/commit_comment.txt
45
docs/dev/change_summary.txt

‎docs/dev/reports/asteroids_vector_migration_validation.txt‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
Asteroids platform demo ready with 13 packaged assets.
2+
Validation: valid (0 blocking findings, 0 warnings)
3+
Packaging: Package ready with 13 assets and 10 dependencies.
4+
Runtime: Runtime loader ready with 13 assets.
5+
Gameplay: Gameplay system layer ready with 13 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: 13 nodes, 10 edges, 0 findings.
10+
Profiler: Performance profiler captured 4 deterministic samples.
11+
Runtime entry: games/Asteroids/main.js#bootAsteroids
12+
Visual path: vector preferred, sprite fallback
13+
Startup roots: parallax.asteroids-overlay, parallax.asteroids-title, sprite.asteroids-demo, tilemap.asteroids-stage, vector.asteroids.asteroid.large, vector.asteroids.asteroid.medium, vector.asteroids.asteroid.small, vector.asteroids.ship, vector.asteroids.ui.title
14+
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
15+
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/sprites/asteroids-demo.sprite.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
16+
[info] ASTEROIDS_PLATFORM_DEMO_READY: Asteroids demo completed strict validation, packaging, runtime, export, and publishing flows.
17+
[info] ASTEROIDS_RUNTIME_HANDOFF: Runtime handoff preserved bootAsteroids from games/Asteroids/main.js.
18+
[info] ASTEROIDS_VECTOR_PREFERRED: Vector assets are the preferred visual path for ship, asteroid variants, and title presentation.
19+
[info] ASTEROIDS_SPRITE_FALLBACK: Sprite atlas fallback remains documented as a temporary migration safety path while vector-led visuals are verified.

‎docs/dev/validation_checklist.txt‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
1-
- PLAN doc exists and is docs-only
2-
- Vector asset type is defined as first-class and registry-owned
3-
- SVG authoring bridge is documented
4-
- Validation, packaging, runtime, debug, and profiler expectations are defined
5-
- Tool rename map is explicit
6-
- docs/dev contains codex_commands.md and commit_comment.txt
1+
- APPLY_PR_VECTOR_ASSET_SYSTEM is docs-only
2+
- PLAN_PR_ASTEROIDS_VECTOR_MIGRATION is docs-only
3+
- 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
76
- No engine core API changes are authorized

‎docs/pr/APPLY_PR_VECTOR_ASSET_SYSTEM.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# APPLY_PR_VECTOR_ASSET_SYSTEM
2+
3+
## Purpose
4+
Apply the completed vector asset system and tool naming normalization 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 assets and normalized tool naming as accepted platform baseline
11+
12+
## Verification Summary
13+
- BUILD artifact exists and matches the scoped vector asset system implementation
14+
- APPLY remains docs-only
15+
- Vector assets are treated as first-class platform assets
16+
- SVG-oriented authoring is the accepted bridge into vector asset normalization
17+
- Tool naming is normalized to match actual responsibilities
18+
- No engine core API changes are required by APPLY
19+
20+
## Accepted Baseline
21+
- Project owns a first-class vector asset system
22+
- Registry, dependency graph, validation, packaging, and runtime all recognize vector assets
23+
- Tool naming moves forward under normalized human-readable names
24+
- Legacy naming may be documented for transition, but is not the target standard
25+
26+
## Manual Validation Checklist
27+
1. Confirm BUILD artifact exists in repo tmp path.
28+
2. Confirm APPLY bundle only contains docs/pr and docs/dev files.
29+
3. Confirm accepted scope does not exceed BUILD scope.
30+
4. Confirm no new implementation files are introduced by APPLY.
31+
5. Confirm vector assets participate in platform flows without engine API changes.
32+
6. Confirm renamed tool paths and labels are documented as the accepted forward path.
33+
34+
## Approved Commit Comment
35+
build(vector-assets): add first-class vector asset system and normalize tool naming

‎docs/pr/BUILD_PR_ASTEROIDS_VECTOR_MIGRATION.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# BUILD_PR_ASTEROIDS_VECTOR_MIGRATION
2+
3+
## Purpose
4+
Migrate the flagship Asteroids platform demo to use first-class vector assets as the preferred visual path while preserving all accepted platform boundaries and avoiding engine core API changes.
5+
6+
## Build Scope
7+
- move Asteroids ship rendering preference to first-class vector assets
8+
- migrate asteroid large, medium, and small variants to vector assets
9+
- migrate title/UI framing to vector assets where appropriate
10+
- preserve validation, packaging, runtime, debug, profiler, export, and publishing flows
11+
- keep the gameplay loop and runtime handoff intact
12+
- document temporary fallback behavior clearly
13+
14+
## Implemented Files
15+
- `tools/shared/asteroidsPlatformDemo.js`
16+
- `tools/shared/projectAssetValidation.js`
17+
- `tools/shared/projectPackaging.js`
18+
- `tests/games/AsteroidsPlatformDemo.test.mjs`
19+
- `games/Asteroids/platform/assets/vectors/asteroids-ship.vector.json`
20+
- `games/Asteroids/platform/assets/vectors/asteroids-asteroid-large.vector.json`
21+
- `games/Asteroids/platform/assets/vectors/asteroids-asteroid-medium.vector.json`
22+
- `games/Asteroids/platform/assets/vectors/asteroids-asteroid-small.vector.json`
23+
- `games/Asteroids/platform/assets/vectors/asteroids-title.vector.json`
24+
25+
## Migration Notes
26+
- The demo registry now includes first-class vector assets for the player ship, all asteroid size variants, and the title treatment.
27+
- The demo uses the accepted normalized tool naming baseline:
28+
- `pixel-asset-studio`
29+
- `tilemap-studio`
30+
- `parallax-scene-studio`
31+
- `vector-asset-studio`
32+
- The packaged demo now treats vector assets as the preferred visual path while preserving the existing sprite atlas as a temporary migration fallback.
33+
- Runtime handoff remains unchanged at `games/Asteroids/main.js#bootAsteroids`, so gameplay behavior and platform entry flow stay intact.
34+
35+
## Temporary Migration Fallback
36+
- `sprite.asteroids-demo` remains packaged and documented as a temporary migration safety path.
37+
- The fallback exists only to preserve rollback safety while vector-led visuals are verified through the accepted validation, packaging, runtime, export, and publishing flows.
38+
- Vector assets are the preferred path and should be treated as the target baseline for future demo/template work.
39+
40+
## Verification
41+
- `node --check tools/shared/asteroidsPlatformDemo.js`
42+
- `node --check tools/shared/projectAssetValidation.js`
43+
- `node --check tools/shared/projectPackaging.js`
44+
- `node --check tests/games/AsteroidsPlatformDemo.test.mjs`
45+
- `node ./scripts/run-node-tests.mjs`
46+
- Result: `107/107` explicit `run()` tests passed.
47+
48+
## Validation Summary
49+
- Demo status: ready
50+
- Validation: valid with `0` blocking findings
51+
- Packaging: ready with `13` assets and `10` dependencies
52+
- Runtime: ready with `13` loaded assets
53+
- Debug: `13` nodes and `10` edges
54+
- Publishing: ready with `5` release targets
55+
56+
## Manual Validation Checklist
57+
1. Ship uses the vector asset path as the preferred visual contract.
58+
2. Asteroid large, medium, and small variants use vector assets as the preferred visual contract.
59+
3. Validation passes with no blocking findings.
60+
4. Packaging includes the migrated vector assets deterministically.
61+
5. Runtime loader reaches ready state with vector assets present.
62+
6. Debug and profiler surfaces reflect vector participation.
63+
7. Gameplay loop remains intact: title, start, play, score, lives, waves, game-over, restart.
64+
8. Temporary sprite fallback is documented clearly.
65+
9. No engine core APIs are changed.

‎docs/pr/PLAN_PR_ASTEROIDS_VECTOR_MIGRATION.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# PLAN_PR_ASTEROIDS_VECTOR_MIGRATION
2+
3+
## Goal
4+
Define a migration of the flagship Asteroids platform demo from sprite-led asset rendering to vector-led asset rendering
5+
using the accepted first-class vector asset system, while preserving all accepted platform boundaries.
6+
7+
## Why This PR Exists
8+
The flagship Asteroids demo already proves the platform end-to-end, but Asteroids is fundamentally a vector game.
9+
Now that vector assets are a first-class platform type, the demo should migrate to authentic vector-driven content.
10+
11+
## Intent
12+
- Move key Asteroids gameplay visuals to vector assets
13+
- Preserve strict validation, packaging, runtime, debug, profiler, export, and publishing flows
14+
- Keep the migration surgical and reusable for future vector-native templates
15+
16+
## Scope
17+
- migrate player ship visual to vector asset
18+
- migrate asteroid variants to vector assets
19+
- optionally migrate select title/UI assets where vector is a better fit
20+
- update registry/dependency graph participation for migrated demo assets
21+
- preserve gameplay loop and demo validation coverage
22+
- preserve packaging/runtime handoff for the Asteroids demo
23+
- keep migration reusable as a future vector-native demo/template baseline
24+
25+
## Non-Goals
26+
- No engine core API changes
27+
- No destructive removal of existing demo content until vector path is verified
28+
- No gameplay redesign beyond what is needed for vector-led rendering
29+
- No bypass of validation, packaging, runtime, CI, export, or publishing boundaries
30+
31+
## Migration Strategy
32+
1. Keep the existing Asteroids demo as the verified baseline.
33+
2. Introduce vector asset equivalents for ship and asteroid visuals.
34+
3. Update demo asset references to consume vector assets as the preferred path.
35+
4. Preserve fallback/reference documentation for prior sprite-led demo assets only as migration safety.
36+
5. Re-run full platform validation, packaging, runtime, export, publishing, debug, and profiler flows.
37+
38+
## Proposed Vector IDs
39+
- `vector.asteroids.ship`
40+
- `vector.asteroids.asteroid.large`
41+
- `vector.asteroids.asteroid.medium`
42+
- `vector.asteroids.asteroid.small`
43+
- `vector.asteroids.ui.title` (optional)
44+
45+
## Likely Files
46+
- vector asset definitions under `games/Asteroids/platform/assets/vectors/`
47+
- updated demo content/config references
48+
- validation and packaging reports
49+
- no engine core API files
50+
51+
## Acceptance Criteria
52+
1. Asteroids demo validates successfully with vector-led assets.
53+
2. Packaging succeeds with vector assets included deterministically.
54+
3. Runtime reaches ready state with vector assets as the preferred visual path.
55+
4. Gameplay loop remains intact: title, start, play, score, lives, waves, game-over, restart.
56+
5. Debug and profiler surfaces show vector asset participation.
57+
6. No engine core APIs are changed.
58+
59+
## Manual Validation Checklist
60+
1. Ship renders through vector asset path.
61+
2. Asteroids render through vector asset path.
62+
3. Rotation and scale feel correct for vector-led visuals.
63+
4. Validation passes with no blocking findings.
64+
5. Packaging includes migrated vector assets.
65+
6. Runtime loader reaches ready state.
66+
7. Debug graph reflects vector nodes/edges.
67+
8. Profiler captures vector participation deterministically.
68+
9. No engine core APIs are changed.
69+
70+
## Approved Commit Comment
71+
plan(demo): define vector migration for flagship asteroids demo
72+
73+
## Next Command
74+
BUILD_PR_ASTEROIDS_VECTOR_MIGRATION

‎games/Asteroids/platform/assets/vectors/asteroids-asteroid-medium.vector.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"id": "vector.asteroids.asteroid.medium",
3+
"type": "vector",
4+
"source": {
5+
"kind": "svg",
6+
"path": "games/Asteroids/platform/assets/vectors/asteroids-asteroid-medium.vector.json"
7+
},
8+
"geometry": {
9+
"viewBox": "-28 -28 56 56",
10+
"paths": [{ "d": "M -16 -10 L -2 -18 L 16 -14 L 20 2 L 8 18 L -10 16 L -20 4 Z" }]
11+
},
12+
"style": {
13+
"stroke": true,
14+
"fill": false
15+
}
16+
}

0 commit comments

Comments
 (0)