Skip to content

Commit d2bd894

Browse files
ToolboxAidToolboxAid
committed
plan(template): define reusable vector-native arcade template
1 parent 7eb12be commit d2bd894

26 files changed

Lines changed: 838 additions & 33 deletions

‎docs/dev/CODEX_COMMANDS.md‎

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

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

7-
Step 1:
8-
Treat docs/pr/PLAN_PR_VECTOR_ONLY_RUNTIME.md as the governing architecture contract.
9-
10-
Step 2:
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`
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
1913
- Do not modify engine core APIs
20-
- Keep rollback notes documented, but do not keep sprite fallback as active runtime dependency
21-
22-
Step 3:
23-
Validate BUILD against docs/pr/BUILD_PR_VECTOR_ONLY_RUNTIME.md.
2414

25-
Step 4:
26-
Treat docs/pr/APPLY_PR_VECTOR_ONLY_RUNTIME.md as the acceptance boundary and package results.
15+
Target template path:
16+
- templates/vector-native-arcade/
2717

2818
Package:
29-
HTML-JavaScript-Gaming/tmp/VECTOR_ONLY_RUNTIME_PR_BUNDLE_delta.zip
19+
HTML-JavaScript-Gaming/tmp/BUILD_PR_VECTOR_NATIVE_TEMPLATE_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-runtime): harden asteroids demo to vector-only runtime path
1+
plan(template): define reusable vector-native arcade template

‎docs/dev/change_summary.txt‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,2 @@
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.
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.

‎docs/dev/file_tree.txt‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
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
1+
docs/pr/PLAN_PR_VECTOR_NATIVE_TEMPLATE.md
42
docs/dev/codex_commands.md
53
docs/dev/commit_comment.txt
64
docs/dev/change_summary.txt

‎docs/dev/reports/vector_native_template_validation.txt‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Vector native template ready with 10 packaged assets.
2+
Template path: templates/vector-native-arcade/
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+
CI: Platform validation suite pass with 8/8 scenarios passing. CI gate green.
12+
Publishing: Publishing pipeline ready with 5 release targets.
13+
Vector-only runtime: ready
14+
Required vectors: vector.template.player, vector.template.obstacle.large, vector.template.obstacle.small, vector.template.ui.title, vector.template.ui.hud
15+
Config: templates/vector-native-arcade/config/template.project.json
16+
Runtime bootstrap: templates/vector-native-arcade/runtime/bootstrap.runtime.json
17+
Docs: templates/vector-native-arcade/docs/STARTER_GUIDE.md
18+
[info] VECTOR_NATIVE_TEMPLATE_READY: Vector-native arcade template completed validation, packaging, runtime, CI, export, and publishing flows.
19+
[info] VECTOR_NATIVE_TEMPLATE_CONTRACT: First-class vector assets are the required visual contract for the template baseline.
20+
[info] VECTOR_NATIVE_TEMPLATE_REUSE: Template provides reusable starter structure for future vector-led arcade games without sprite fallback.

‎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, BUILD, and APPLY docs are all present
2-
- codex_commands.md and commit_comment.txt are under docs/dev
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
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
5+
- docs/dev contains codex_commands.md and commit_comment.txt
66
- No engine core API changes are authorized
7-
- APPLY remains docs-only acceptance boundary

‎docs/pr/BUILD_PR_VECTOR_NATIVE_TEMPLATE.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# BUILD_PR_VECTOR_NATIVE_TEMPLATE
2+
3+
## Purpose
4+
Implement a reusable vector-native arcade template that preserves the accepted strict platform boundaries and uses first-class vector assets as the required visual contract.
5+
6+
## Build Scope
7+
- create `templates/vector-native-arcade/` as the reusable starter path
8+
- require first-class vector assets for player, obstacle, title, and HUD baseline visuals
9+
- preserve strict validation, packaging, runtime, CI, export, and publishing boundaries
10+
- avoid reintroducing sprite fallback as an active runtime dependency
11+
- keep the template reusable for future vector-led games
12+
- avoid engine core API changes
13+
14+
## Implemented Files
15+
- `templates/vector-native-arcade/README.md`
16+
- `templates/vector-native-arcade/assets/palettes/vector-native-primary.palette.json`
17+
- `templates/vector-native-arcade/assets/vectors/template-player.vector.json`
18+
- `templates/vector-native-arcade/assets/vectors/template-obstacle-large.vector.json`
19+
- `templates/vector-native-arcade/assets/vectors/template-obstacle-small.vector.json`
20+
- `templates/vector-native-arcade/assets/vectors/template-title.vector.json`
21+
- `templates/vector-native-arcade/assets/vectors/template-hud.vector.json`
22+
- `templates/vector-native-arcade/assets/tilemaps/template-ui.tileset.json`
23+
- `templates/vector-native-arcade/assets/tilemaps/template-arena.tilemap.json`
24+
- `templates/vector-native-arcade/assets/parallax/template-backdrop.parallax.json`
25+
- `templates/vector-native-arcade/assets/parallax/template-backdrop.svg`
26+
- `templates/vector-native-arcade/config/template.project.json`
27+
- `templates/vector-native-arcade/runtime/bootstrap.runtime.json`
28+
- `templates/vector-native-arcade/docs/STARTER_GUIDE.md`
29+
- `templates/vector-native-arcade/docs/ROLLBACK_NOTES.md`
30+
- `tools/shared/vectorNativeTemplate.js`
31+
- `tests/tools/VectorNativeTemplate.test.mjs`
32+
- `tests/run-tests.mjs`
33+
34+
## Build Notes
35+
- Added a reusable template definition and verifier in `tools/shared/vectorNativeTemplate.js`.
36+
- The template uses a vector-only visual contract with required vector IDs for player, obstacles, title, and HUD starter content.
37+
- The template preserves strict validation, packaging, runtime, debug, profiler, CI, export, and publishing flows.
38+
- The template does not package or load sprite fallback assets as part of the active runtime baseline.
39+
- Runtime bootstrap remains compatible with `games/Asteroids/main.js#bootAsteroids` as a starter seam without modifying engine core APIs.
40+
41+
## Verification
42+
- `node --check tools/shared/vectorNativeTemplate.js`
43+
- `node --check tests/tools/VectorNativeTemplate.test.mjs`
44+
- `node ./scripts/run-node-tests.mjs`
45+
- Result: `108/108` explicit `run()` tests passed.
46+
47+
## Validation Summary
48+
- Template status: ready
49+
- Validation: valid with `0` blocking findings
50+
- Packaging: ready with `10` assets and `8` dependencies
51+
- Runtime: ready with `10` loaded assets
52+
- Debug: `10` nodes and `8` edges
53+
- CI: pass
54+
- Publishing: ready with `5` release targets
55+
56+
## Manual Validation Checklist
57+
1. Template exists at `templates/vector-native-arcade/`.
58+
2. Required vector asset categories are present.
59+
3. Validation passes with no blocking findings.
60+
4. Packaging remains deterministic.
61+
5. Runtime reaches ready state.
62+
6. CI, export, and publishing remain ready.
63+
7. No sprite fallback is required as an active runtime dependency.
64+
8. No engine core APIs are changed.

‎docs/pr/PLAN_PR_VECTOR_NATIVE_TEMPLATE.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# PLAN_PR_VECTOR_NATIVE_TEMPLATE
2+
3+
## Goal
4+
Define a reusable vector-native game template that uses first-class vector assets as the default and required visual path,
5+
building on the accepted vector-only runtime baseline without reintroducing sprite fallback dependencies.
6+
7+
## Why This PR Exists
8+
The Asteroids demo now proves that the platform can author, validate, package, publish, and run a vector-only game.
9+
The next multiplier is to turn that success into a reusable template so future vector-native games can start from a clean,
10+
validated, platform-approved baseline instead of rebuilding the same structure each time.
11+
12+
## Intent
13+
- create a true vector-native template
14+
- preserve accepted strict validation, packaging, runtime, CI, export, and publishing boundaries
15+
- make vector-first authoring the default path for new arcade-style games
16+
- avoid reintroducing sprite fallback as an active runtime dependency
17+
18+
## Scope
19+
- define template structure for vector-native projects
20+
- define required vector asset categories for template bootstrapping
21+
- define template registry, dependency graph, validation, packaging, and runtime expectations
22+
- define debug/profiler/template/publishing participation for vector-native projects
23+
- define migration and starter content expectations for future vector-led demos/games
24+
25+
## Non-Goals
26+
- No engine core API changes
27+
- No broad template redesign for unrelated game styles
28+
- No sprite fallback dependency in the vector-native template baseline
29+
- No destructive migration of existing non-vector templates
30+
- No bypass of accepted validation, packaging, runtime, CI, export, or publishing boundaries
31+
32+
## Template Intent
33+
The vector-native template should serve as the default starting point for games that benefit from:
34+
- geometric line art
35+
- clean scaling
36+
- rotation without raster artifacts
37+
- low-overhead visual definitions
38+
- classic arcade or abstract visual styles
39+
40+
## Proposed Template Path
41+
```text
42+
templates/vector-native-arcade/
43+
```
44+
45+
## Proposed Baseline Structure
46+
```text
47+
templates/vector-native-arcade/
48+
assets/
49+
palettes/
50+
vectors/
51+
tilemaps/
52+
parallax/
53+
config/
54+
runtime/
55+
docs/
56+
```
57+
58+
## Required Vector Asset Categories
59+
- player vehicle/entity vector
60+
- enemy or obstacle vector set
61+
- title or UI vector treatment
62+
- optional vector HUD or indicator elements
63+
- vector-aware startup configuration
64+
65+
## Core Contracts
66+
1. Vector assets are the required primary visual contract.
67+
2. Registry owns vector asset identity and template content.
68+
3. Dependency graph records template vector relationships deterministically.
69+
4. Validation enforces vector-native requirements.
70+
5. Packaging includes vector-native assets deterministically.
71+
6. Runtime loads vector-native packaged content without sprite fallback.
72+
7. Debug, profiler, export, publishing, and CI systems all recognize the template as first-class.
73+
8. No engine core APIs are changed.
74+
75+
## Template Expectations
76+
- ships with a minimal playable or near-playable bootstrap state
77+
- demonstrates title/start/gameplay/restart flow hooks
78+
- exposes clean extension points for future game-specific logic
79+
- preserves docs-first compatibility with platform workflow
80+
- provides a reliable starting point for future vector-first demos
81+
82+
## Likely Files
83+
- `docs/pr/BUILD_PR_VECTOR_NATIVE_TEMPLATE.md`
84+
- template content under `templates/vector-native-arcade/`
85+
- vector starter assets and config
86+
- docs/dev reports
87+
- no engine core API files
88+
89+
## Acceptance Criteria
90+
1. Template validates successfully as vector-native content.
91+
2. Packaging succeeds without sprite fallback dependency.
92+
3. Runtime reaches ready state from template-packaged content.
93+
4. Debug and profiler surfaces reflect vector-native template participation.
94+
5. Export and publishing remain compatible.
95+
6. Template is reusable for future vector-led games.
96+
7. No engine core APIs are changed.
97+
98+
## Manual Validation Checklist
99+
1. Template contains required vector asset categories.
100+
2. Registry/dependency graph include vector-native template assets.
101+
3. Validation passes with no blocking findings.
102+
4. Packaging remains deterministic.
103+
5. Runtime reaches ready state.
104+
6. No sprite fallback is required.
105+
7. Debug/profiler/export/publishing remain ready.
106+
8. No engine core APIs are changed.
107+
108+
## Approved Commit Comment
109+
plan(template): define reusable vector-native arcade template
110+
111+
## Next Command
112+
BUILD_PR_VECTOR_NATIVE_TEMPLATE

‎templates/vector-native-arcade/README.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Vector Native Arcade Template
2+
3+
This template is the reusable vector-native starting point for future arcade-style games.
4+
5+
## Baseline
6+
7+
- first-class vector assets are the required visual contract
8+
- strict validation, packaging, runtime, CI, export, and publishing boundaries remain active
9+
- sprite fallback is not part of the runtime baseline
10+
- runtime bootstrap remains compatible with `games/Asteroids/main.js#bootAsteroids` as a starter handoff seam
11+
12+
## Structure
13+
14+
- `assets/` contains palette, vector, tilemap, and parallax starter content
15+
- `config/` contains starter project configuration
16+
- `runtime/` contains starter runtime bootstrap metadata
17+
- `docs/` contains starter guidance and rollback notes

‎templates/vector-native-arcade/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)