Skip to content

Commit 50da812

Browse files
ToolboxAidToolboxAid
committed
build(vector-platform): add vector template sample game and define geometry runtime
1 parent d2bd894 commit 50da812

28 files changed

Lines changed: 657 additions & 20 deletions

‎docs/dev/CODEX_COMMANDS.md‎

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

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

7-
Requirements:
8-
- Implement a reusable vector-native game template
9-
- Use first-class vector assets as the required visual contract
10-
- Preserve strict validation, packaging, runtime, CI, export, and publishing boundaries
11-
- Avoid reintroducing sprite fallback as an active runtime dependency
12-
- Keep the template reusable for future vector-led games
13-
- Do not modify engine core APIs
7+
Step 1:
8+
Create BUILD_PR_VECTOR_TEMPLATE_SAMPLE_GAME.
149

15-
Target template path:
16-
- templates/vector-native-arcade/
10+
BUILD requirements:
11+
- Build a standalone sample game from `templates/vector-native-arcade/`
12+
- Use vector assets as the only active visual runtime dependency
13+
- Preserve strict validation, packaging, runtime, debug, profiler, export, and publishing compatibility
14+
- Avoid engine core API changes
15+
16+
Step 2:
17+
Treat docs/pr/PLAN_PR_VECTOR_GEOMETRY_RUNTIME.md as the governing architecture contract for the next runtime evolution.
1718

1819
Package:
19-
HTML-JavaScript-Gaming/tmp/BUILD_PR_VECTOR_NATIVE_TEMPLATE_delta.zip
20+
HTML-JavaScript-Gaming/tmp/VECTOR_TEMPLATE_SAMPLE_GAME_AND_GEOMETRY_RUNTIME_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(template): define reusable vector-native arcade template
1+
build(vector-platform): add vector template sample game and define geometry runtime

‎docs/dev/change_summary.txt‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
1-
Adds a docs-only plan for a reusable vector-native game template built on the accepted vector-only runtime baseline.
2-
Establishes vector-first starter structure for future arcade-style games.
1+
Combined progression bundle:
2+
1. build a standalone sample game from the vector-native template
3+
2. define the next runtime evolution for deterministic vector geometry behavior

‎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_NATIVE_TEMPLATE.md
1+
docs/pr/BUILD_PR_VECTOR_TEMPLATE_SAMPLE_GAME.md
2+
docs/pr/PLAN_PR_VECTOR_GEOMETRY_RUNTIME.md
23
docs/dev/codex_commands.md
34
docs/dev/commit_comment.txt
45
docs/dev/change_summary.txt

‎docs/dev/reports/vector_template_sample_game_validation.txt‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
Vector template sample game ready with 10 packaged assets.
2+
Game path: games/vector-arcade-sample/
3+
Validation: 0 blocking findings, 0 warnings
4+
Packaging: Package ready with 10 assets and 8 dependencies.
5+
Runtime: Runtime loader ready with 10 assets.
6+
Gameplay: Gameplay system layer ready with 10 content bindings.
7+
Templates: Game templates ready with 3 templates.
8+
Debug: Debug view: 10 nodes, 8 edges, 0 findings.
9+
Profiler: Performance profiler captured 4 deterministic samples.
10+
Export: Multi-target export ready for 3 targets.
11+
Publishing: Publishing pipeline ready with 5 release targets.
12+
Runtime entry: games/vector-arcade-sample/main.js#bootVectorArcadeSample
13+
Vector-only runtime: ready
14+
Config: games/vector-arcade-sample/config/sample.project.json
15+
Runtime bootstrap: games/vector-arcade-sample/runtime/bootstrap.runtime.json
16+
[info] VECTOR_TEMPLATE_SAMPLE_GAME_READY: Standalone vector sample game completed validation, packaging, runtime, debug, profiler, export, and publishing flows.
17+
[info] VECTOR_TEMPLATE_SAMPLE_GAME_CONTRACT: Vector assets remain the only active visual runtime dependency for the sample game.
18+
[info] VECTOR_TEMPLATE_SAMPLE_GAME_REUSE: Sample game proves the vector-native arcade template is reusable outside the Asteroids-owned project path.

‎docs/dev/validation_checklist.txt‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
1-
- PLAN doc exists and is docs-only
2-
- Vector-native template baseline is explicit
3-
- No sprite fallback dependency is allowed in the template baseline
4-
- Validation, packaging, runtime, CI, export, and publishing expectations are defined
1+
- BUILD_PR_VECTOR_TEMPLATE_SAMPLE_GAME is present
2+
- PLAN_PR_VECTOR_GEOMETRY_RUNTIME is present
53
- docs/dev contains codex_commands.md and commit_comment.txt
6-
- No engine core API changes are authorized
4+
- vector-only runtime assumptions are preserved
5+
- no engine core API changes are authorized

‎docs/pr/BUILD_PR_VECTOR_TEMPLATE_SAMPLE_GAME.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# BUILD_PR_VECTOR_TEMPLATE_SAMPLE_GAME
2+
3+
## Purpose
4+
Implement a clean sample game built from the accepted `templates/vector-native-arcade/` baseline,
5+
proving that the reusable vector-native template can produce a standalone playable project without
6+
sprite fallback and without engine core API changes.
7+
8+
## Build Scope
9+
- create a standalone sample game from the vector-native template baseline
10+
- keep the sample game small, playable, and demo-ready
11+
- use first-class vector assets as the required visual contract
12+
- preserve strict validation, packaging, runtime, CI, export, and publishing compatibility
13+
- keep the sample reusable as proof that the template is not Asteroids-specific
14+
- avoid engine core API changes
15+
16+
## Suggested Target
17+
```text
18+
games/vector-arcade-sample/
19+
```
20+
21+
## Required Contracts
22+
- vector assets are the only active visual runtime dependency
23+
- no sprite fallback is packaged as active runtime dependency
24+
- registry, dependency graph, validation, packaging, and runtime all recognize the sample cleanly
25+
- debug/profiler/export/publishing remain compatible
26+
- deterministic behavior remains stable
27+
- no engine core APIs are changed
28+
29+
## Likely Files
30+
- `games/vector-arcade-sample/*`
31+
- template-derived vector assets/config/runtime files
32+
- validation/packaging/runtime/debug/profiler reports
33+
- docs/dev reports
34+
- no engine core API files
35+
36+
## Implemented Files
37+
- `games/vector-arcade-sample/index.html`
38+
- `games/vector-arcade-sample/main.js`
39+
- `games/vector-arcade-sample/README.md`
40+
- `games/vector-arcade-sample/assets/palettes/vector-native-primary.palette.json`
41+
- `games/vector-arcade-sample/assets/vectors/template-player.vector.json`
42+
- `games/vector-arcade-sample/assets/vectors/template-obstacle-large.vector.json`
43+
- `games/vector-arcade-sample/assets/vectors/template-obstacle-small.vector.json`
44+
- `games/vector-arcade-sample/assets/vectors/template-title.vector.json`
45+
- `games/vector-arcade-sample/assets/vectors/template-hud.vector.json`
46+
- `games/vector-arcade-sample/assets/tilemaps/template-ui.tileset.json`
47+
- `games/vector-arcade-sample/assets/tilemaps/template-arena.tilemap.json`
48+
- `games/vector-arcade-sample/assets/parallax/template-backdrop.parallax.json`
49+
- `games/vector-arcade-sample/assets/parallax/template-backdrop.svg`
50+
- `games/vector-arcade-sample/config/sample.project.json`
51+
- `games/vector-arcade-sample/runtime/bootstrap.runtime.json`
52+
- `games/vector-arcade-sample/docs/STARTER_GUIDE.md`
53+
- `games/vector-arcade-sample/docs/ROLLBACK_NOTES.md`
54+
- `tools/shared/vectorTemplateSampleGame.js`
55+
- `tests/tools/VectorTemplateSampleGame.test.mjs`
56+
- `tests/run-tests.mjs`
57+
58+
## Build Notes
59+
- Built `games/vector-arcade-sample/` as a standalone sample derived from `templates/vector-native-arcade/`.
60+
- Kept vector assets as the only active visual runtime dependency.
61+
- Preserved strict validation, packaging, runtime, debug, profiler, export, and publishing compatibility through a shared sample-game verifier.
62+
- Added a sample-local runtime entry at `games/vector-arcade-sample/main.js#bootVectorArcadeSample` without changing engine core APIs.
63+
64+
## Verification
65+
- `node --check tools/shared/vectorTemplateSampleGame.js`
66+
- `node --check games/vector-arcade-sample/main.js`
67+
- `node --check tests/tools/VectorTemplateSampleGame.test.mjs`
68+
- `node ./scripts/run-node-tests.mjs`
69+
- Result: `109/109` explicit `run()` tests passed.
70+
71+
## Validation Summary
72+
- Sample status: ready
73+
- Validation: valid with `0` blocking findings
74+
- Packaging: ready with `10` assets and `8` dependencies
75+
- Runtime: ready with `10` loaded assets
76+
- Debug: `10` nodes and `8` edges
77+
- Publishing: ready with `5` release targets
78+
79+
## Verification Expectations
80+
- sample validates successfully
81+
- sample packages successfully
82+
- runtime reaches ready state
83+
- debug graph shows vector-native sample assets
84+
- profiler captures deterministic sample data
85+
- export and publishing remain ready
86+
87+
## Manual Validation Checklist
88+
1. Sample game is created from the vector-native template baseline.
89+
2. Validation passes with no blocking findings.
90+
3. Packaging succeeds without sprite fallback.
91+
4. Runtime reaches ready state.
92+
5. Gameplay/sample loop is demonstrable.
93+
6. Debug and profiler surfaces reflect sample participation.
94+
7. Export and publishing remain ready.
95+
8. No engine core APIs are changed.
96+
97+
## Approved Commit Comment
98+
build(sample-game): add standalone game from vector-native template
99+
100+
## Next Command
101+
APPLY_PR_VECTOR_TEMPLATE_SAMPLE_GAME

‎docs/pr/PLAN_PR_VECTOR_GEOMETRY_RUNTIME.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# PLAN_PR_VECTOR_GEOMETRY_RUNTIME
2+
3+
## Goal
4+
Define a runtime geometry layer for vector-native content so vector assets can evolve beyond static authored paths
5+
into richer runtime-driven geometry behaviors while preserving accepted platform boundaries.
6+
7+
## Why This PR Exists
8+
The platform now supports first-class vector assets and a reusable vector-native template. The next multiplier
9+
is a geometry runtime that allows procedural generation, controlled transforms, shape composition, and future
10+
vector-native effects without reintroducing raster dependency.
11+
12+
## Intent
13+
- extend vector-native runtime capability
14+
- keep authored vector assets as the source baseline
15+
- allow deterministic runtime geometry behaviors on top of packaged vector content
16+
- preserve strict validation, packaging, runtime, CI, export, and publishing guarantees
17+
18+
## Scope
19+
- define runtime geometry contracts for vector assets
20+
- define procedural and transformed geometry categories
21+
- define deterministic runtime composition rules
22+
- define validation boundaries for runtime geometry inputs
23+
- define debug/profiler visibility expectations for geometry runtime behavior
24+
- define future integration points for AI-assisted vector generation and gameplay-driven geometry
25+
26+
## Non-Goals
27+
- No engine core API changes
28+
- No replacement of authored vector assets as the baseline truth
29+
- No uncontrolled runtime mutation outside deterministic contracts
30+
- No bypass of accepted validation, packaging, runtime, CI, export, or publishing boundaries
31+
32+
## Geometry Runtime Categories
33+
- procedural shape generation
34+
- deterministic transforms
35+
- composed vector assemblies
36+
- runtime stroke/fill parameterization
37+
- geometry state transitions
38+
- gameplay-driven vector effects
39+
40+
## Core Contracts
41+
1. Authored vector assets remain the source baseline.
42+
2. Runtime geometry behavior must be deterministic enough for stable validation and profiling.
43+
3. Geometry runtime must compose with packaging/runtime rather than bypass them.
44+
4. Debug and profiler systems must be able to surface geometry runtime participation.
45+
5. Future AI/gameplay systems may consume these contracts without redefining the asset baseline.
46+
6. No engine core APIs are changed.
47+
48+
## Proposed Next Runtime Areas
49+
- vector asteroid breakup generation
50+
- procedural debris and effects
51+
- shape morphing under controlled rules
52+
- vector HUD composition
53+
- reusable geometry behaviors for future templates/games
54+
55+
## Likely Files
56+
- `docs/pr/BUILD_PR_VECTOR_GEOMETRY_RUNTIME.md`
57+
- shared vector runtime helper modules
58+
- debug/profiler reporting integrations
59+
- docs/dev reports
60+
- no engine core API files
61+
62+
## Acceptance Criteria
63+
1. Runtime geometry contracts are clearly defined.
64+
2. Deterministic behavior expectations are explicit.
65+
3. Validation, packaging, runtime, debug, and profiler participation are defined.
66+
4. Future procedural vector work has a clean platform path.
67+
5. No engine core APIs are changed.
68+
69+
## Manual Validation Checklist
70+
1. Runtime geometry categories are clearly scoped.
71+
2. Authored vector assets remain the baseline truth.
72+
3. Deterministic runtime expectations are explicit.
73+
4. Debug/profiler integration is covered.
74+
5. Future gameplay/AI integration points are identified.
75+
6. No engine core APIs are changed.
76+
77+
## Approved Commit Comment
78+
plan(vector-runtime): define deterministic geometry runtime for vector-native assets
79+
80+
## Next Command
81+
BUILD_PR_VECTOR_GEOMETRY_RUNTIME

‎games/vector-arcade-sample/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Vector Arcade Sample
2+
3+
This sample game is built from `templates/vector-native-arcade/`.
4+
5+
## Baseline
6+
7+
- vector assets are the only active visual runtime dependency
8+
- strict validation, packaging, runtime, debug, profiler, export, and publishing compatibility are preserved
9+
- runtime uses the accepted starter seam without modifying engine core APIs

‎games/vector-arcade-sample/assets/palettes/vector-native-primary.palette.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"name": "Vector Native Primary Palette",
3+
"colors": ["#05070DFF", "#E8F0FFFF", "#6FD3FFFF", "#FFB347FF"]
4+
}

0 commit comments

Comments
 (0)