Skip to content

Commit 70d3d9a

Browse files
author
DavidQ
committed
Toolbox Aid
David Quesenberry 04/05/2026 commit_comment.txt PLAN_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS docs-only planning bundle. Defines the unified 2D render pipeline contract plan for Tile Map Editor, Parallax Editor, Sprite Editor, and Vector Asset Studio, including metadata, asset, layer, validation, and runtime boundary expectations for the next BUILD_PR.
1 parent bfee9fc commit 70d3d9a

10 files changed

Lines changed: 668 additions & 74 deletions

‎.env‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
TEST_VAR=hello_world
2+
API_URL=http://localhost:3000

‎HTML-JavaScript-Gaming-main/tmp/BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS_delta.zip‎

5.62 KB
Binary file not shown.

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 28 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,35 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
codex_commands.md
5+
16
# Codex Commands
27

3-
MODEL: GPT-5.4
4-
REASONING: high
8+
## Recommended Model
9+
- Model: GPT-5.4
10+
- Reasoning: high
511

6-
COMMAND:
7-
Create `BUILD_PR_STARTER_PROJECT_TEMPLATE` as a docs-first implementation PR.
12+
## Primary Command
13+
Create BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS as a docs-only, repo-structured delta.
814

915
Requirements:
10-
- Add one starter project template only
11-
- Keep `Sprite Editor` first-class
12-
- Keep `SpriteEditor_old_keep` hidden legacy
13-
- Keep `tools/index.html` tool-only and sample-free
14-
- Use shared assets and palettes by reference
15-
- Do not add gameplay systems
16-
- Do not add samples back to the main tools surface
16+
- Follow PLAN_PR -> BUILD_PR -> APPLY_PR
17+
- Docs-first only
18+
- No implementation code in the bundle
19+
- One PR per purpose
20+
- Preserve exact repo-relative structure inside the ZIP
21+
- Place outputs under docs/pr and docs/dev
22+
- Use docs/dev/codex_commands.md and docs/dev/commit_comment.txt
23+
- Output ZIP path:
24+
- HTML-JavaScript-Gaming-main/tmp/BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS_delta.zip
1725

18-
Implement:
19-
1. Starter project template folder and manifest
20-
2. Shared asset references for acvector/tile/parallax/sprite validation
21-
3. Shared palette references
22-
4. Project open/save/reload compatibility
23-
5. Minimal README or inline project notes if helpful
24-
6. Validation pass for cross-tool loading
26+
Deliverables:
27+
- docs/pr/BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS.md
28+
- docs/dev/codex_commands.md
29+
- docs/dev/commit_comment.txt
30+
- docs/dev/change_summary.txt
31+
- docs/dev/validation_checklist.txt
32+
- docs/dev/file_tree.txt
2533

26-
Package output to:
27-
`<project folder>/tmp/BUILD_PR_STARTER_PROJECT_TEMPLATE.zip`
34+
Next command:
35+
- APPLY_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,6 @@
1-
Add one starter project template with shared vector, tilemap, parallax, sprite, and palette references plus cross-tool validation
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
commit_comment.txt
5+
6+
docs: define unified 2D render pipeline contract seam across tilemap parallax sprite and vector tools

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,8 @@
1-
Create BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS as a docs-only, repo-structured delta
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
next_command.txt
5+
6+
Create BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS as a docs-only, repo-structured delta ZIP aligned to the approved PLAN_PR and output it to:
7+
8+
HTML-JavaScript-Gaming-main/tmp/BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS_delta.zip

‎docs/dev/change_summary.txt‎

Lines changed: 25 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,27 @@
1-
Final release verification suite
2-
--------------------------------
3-
- verified the Asteroids vector-only runtime acceptance state against current shared build output
4-
- verified the standalone vector-native template sample-game acceptance state against current shared build output
5-
- tightened reporting so geometry participation is explicitly visible in both debug and profiler outputs
6-
- verified deterministic vector geometry runtime behavior with repeated runs
7-
- built the public-facing showcase package and release-ready support assets from verified platform evidence only
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
change_summary.txt
85

9-
Release packaging
10-
-----------------
11-
- created docs-only acceptance artifacts for:
12-
- `APPLY_PR_VECTOR_ONLY_RUNTIME_VERIFIED`
13-
- `APPLY_PR_VECTOR_TEMPLATE_SAMPLE_GAME_VERIFIED`
14-
- `APPLY_PR_VECTOR_GEOMETRY_RUNTIME_VERIFIED`
15-
- created `BUILD_PR_PUBLIC_PLATFORM_SHOWCASE`
16-
- created the master release bundle package
6+
BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS summary
177

18-
Verification highlights
19-
-----------------------
20-
- Asteroids runtime remains vector-only and ready across validation, packaging, runtime, debug, profiler, export, and publishing
21-
- standalone sample remains vector-only and ready
22-
- geometry runtime repeated runs are deterministic
23-
- debug/profiler surfaces now call out geometry participation directly
24-
- `node ./scripts/run-node-tests.mjs` passed with `110/110` explicit `run()` tests
8+
- Created docs-only BUILD PR bundle for a unified 2D render pipeline contract.
9+
- Defined canonical top-level contract shape shared by:
10+
- Tile Map Editor
11+
- Parallax Editor
12+
- Sprite Editor
13+
- Vector Asset Studio
14+
- Documented shared metadata requirements and ID stability rules.
15+
- Documented shared asset record rules with project-relative path normalization.
16+
- Documented normalized layer model and deterministic render ordering.
17+
- Added explicit tool-specific mapping notes for tilemap/parallax/sprite/vector payloads.
18+
- Defined runtime ownership boundaries and non-silent validation responsibilities.
19+
- Added validation rules and acceptance criteria for the contract seam.
20+
- Added incremental migration guidance designed to avoid breaking unrelated engine APIs.
21+
22+
Guardrails honored:
23+
- Docs-first only
24+
- No implementation code
25+
- No 3D scope
26+
- No unrelated sample/game/tool changes
27+
- No engine redesign beyond contract seam

‎docs/dev/file_tree.txt‎

Lines changed: 9 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,13 @@
1-
docs/pr/APPLY_PR_VECTOR_ONLY_RUNTIME_VERIFIED.md
2-
docs/pr/APPLY_PR_VECTOR_TEMPLATE_SAMPLE_GAME_VERIFIED.md
3-
docs/pr/APPLY_PR_VECTOR_GEOMETRY_RUNTIME_VERIFIED.md
4-
docs/pr/BUILD_PR_PUBLIC_PLATFORM_SHOWCASE.md
5-
docs/pr/PLAN_PR_PUBLIC_PLATFORM_SHOWCASE.md
6-
docs/release/public_platform_showcase_summary.md
7-
docs/release/public_platform_showcase_video_plan.md
8-
docs/release/public_platform_showcase_overlays.txt
9-
docs/release/public_platform_showcase_proof_checklist.md
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
file_tree.txt
5+
6+
BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS file tree
7+
8+
docs/pr/BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS.md
109
docs/dev/codex_commands.md
1110
docs/dev/commit_comment.txt
1211
docs/dev/change_summary.txt
13-
docs/dev/file_tree.txt
1412
docs/dev/validation_checklist.txt
15-
tools/shared/performanceProfiler.js
16-
tools/shared/vectorAssetSystem.js
17-
tools/shared/vectorNativeTemplate.js
18-
tools/shared/vectorTemplateSampleGame.js
19-
tools/shared/asteroidsPlatformDemo.js
20-
tests/tools/PerformanceProfiler.test.mjs
21-
tests/tools/VectorAssetSystem.test.mjs
22-
tests/tools/VectorNativeTemplate.test.mjs
23-
tests/tools/VectorTemplateSampleGame.test.mjs
24-
tests/games/AsteroidsPlatformDemo.test.mjs
13+
docs/dev/file_tree.txt

‎docs/dev/validation_checklist.txt‎

Lines changed: 22 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,22 @@
1-
- [x] Asteroids vector-only runtime verified as ready
2-
- [x] `sprite.asteroids-demo` confirmed absent from the active packaged/runtime dependency set
3-
- [x] Asteroids validation/package/runtime/debug/profiler/export/publishing remain ready
4-
- [x] standalone vector-native template sample verified as ready with no sprite fallback dependency
5-
- [x] repeated vector geometry runtime runs verified as deterministic
6-
- [x] geometry participation is visible in debug output
7-
- [x] geometry participation is visible in profiler output
8-
- [x] public platform showcase assets were built from verified technical evidence only
9-
- [x] no engine core API files were modified
10-
- [x] `node ./scripts/run-node-tests.mjs` passed with `110/110` explicit `run()` tests
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
validation_checklist.txt
5+
6+
BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS validation checklist
7+
8+
[x] Docs-only bundle created
9+
[x] No implementation code included
10+
[x] PLAN_PR -> BUILD_PR -> APPLY_PR workflow honored
11+
[x] One PR purpose only (render pipeline contract)
12+
[x] Unified top-level contract documented for all 4 tools
13+
[x] Shared metadata rules documented
14+
[x] Shared asset record rules documented
15+
[x] Normalized layer model documented
16+
[x] Deterministic render ordering documented
17+
[x] Tool-specific mapping notes included (tilemap/parallax/sprite/vector)
18+
[x] Runtime ownership boundaries documented
19+
[x] Validation rules and acceptance checklist documented
20+
[x] Incremental migration guidance documented
21+
[x] 2D-focused scope preserved
22+
[x] No unrelated architecture redesign introduced

‎docs/pr/BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS.md
5+
6+
# BUILD_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS
7+
8+
## Purpose
9+
Define a unified 2D render pipeline contract for Tile Map Editor, Parallax Editor, Sprite Editor, and Vector Asset Studio using a docs-first, non-destructive seam that does not redesign engine architecture.
10+
11+
## Scope
12+
In scope:
13+
- Unified top-level render contract shape
14+
- Shared metadata and asset record rules
15+
- Normalized layer model + deterministic render ordering
16+
- Tool-specific mapping notes for all 4 tools
17+
- Runtime ownership boundaries
18+
- Validation and acceptance checklist
19+
- Incremental migration guidance that preserves unrelated engine APIs
20+
21+
Out of scope:
22+
- Implementation code
23+
- Engine renderer rewrite
24+
- 3D scope
25+
- Unrelated tool/game/sample edits
26+
27+
## 1. Unified Top-Level Render Contract
28+
Canonical engine-facing document (2D only):
29+
30+
```json
31+
{
32+
"documentType": "toolbox.render-pipeline.contract",
33+
"contractVersion": "1.0.0",
34+
"producer": {
35+
"tool": "tile-map-editor|parallax-editor|sprite-editor|vector-asset-studio",
36+
"toolVersion": "string"
37+
},
38+
"scene": {
39+
"id": "string",
40+
"name": "string",
41+
"coordinateSpace": "2d"
42+
},
43+
"assets": [],
44+
"layers": [],
45+
"entities": [],
46+
"metadata": {}
47+
}
48+
```
49+
50+
Required:
51+
- `documentType`, `contractVersion`, `producer.tool`, `scene.id`, `scene.name`, `scene.coordinateSpace`
52+
- `assets`, `layers`, `entities`, `metadata` always present (can be empty)
53+
- `scene.coordinateSpace` must be `2d`
54+
55+
## 2. Shared Metadata Rules
56+
Top-level metadata standards:
57+
- `projectId` (optional but recommended)
58+
- `createdAt` ISO timestamp (optional)
59+
- `updatedAt` ISO timestamp (optional)
60+
- `tags` array of strings (optional)
61+
- `runtimeFlags` object (optional)
62+
63+
Common object metadata standards:
64+
- `id` required, stable within document
65+
- `name` required, human-readable
66+
- `type` required where enumerated
67+
- `visible` required for renderable items
68+
- `locked` editor-side only (optional for runtime)
69+
70+
ID rules:
71+
- Deterministic where practical
72+
- No duplicates per collection
73+
- No implicit ID rewriting at runtime
74+
75+
## 3. Shared Asset Record Rules
76+
Asset entries under `assets` must use normalized project-relative paths.
77+
78+
Minimal record:
79+
80+
```json
81+
{
82+
"id": "asset.id",
83+
"type": "image|spritesheet|vector|tileset",
84+
"path": "assets/path/file.ext",
85+
"source": "relative",
86+
"preload": true,
87+
"metadata": {}
88+
}
89+
```
90+
91+
Rules:
92+
- No absolute machine paths
93+
- No temp/session-only paths
94+
- Prefer additive updates over replacement
95+
- Avoid duplicates by `id`, then by normalized `type + path` where practical
96+
- Unknown extra fields must be preserved where low-risk
97+
98+
## 4. Normalized Layer Model + Deterministic Ordering
99+
Layer contract fields:
100+
- `id`, `name`, `kind`, `visible`, `opacity`, `zIndex`, `items`
101+
- optional: `parallaxFactorX`, `parallaxFactorY`, `blendMode`
102+
103+
Allowed `kind` values for this contract:
104+
- `tilemap`
105+
- `parallax`
106+
- `sprite`
107+
- `vector`
108+
- `collision`
109+
- `guide`
110+
- `overlay`
111+
112+
Render order rules:
113+
1. Sort by `zIndex` ascending
114+
2. Tie-break by source order (stable)
115+
3. Within layer, render items by explicit item order if present, else source order
116+
4. `guide` and tool-only diagnostic layers excluded from gameplay render unless explicitly flagged
117+
118+
## 5. Tool-Specific Mapping Notes
119+
Tile Map Editor:
120+
- Produces `tilemap` layers
121+
- Declares tileset/image assets
122+
- Maps tile grids, map dimensions, tile size
123+
- `collision`/`data` tool layers mapped as non-art or debug/runtime utility layers by policy
124+
125+
Parallax Editor:
126+
- Produces `parallax` layers
127+
- Declares image/vector assets for background planes
128+
- Maps `parallaxFactorX/Y`, repeat flags, wrap behavior
129+
- Preserves deterministic draw stack through `zIndex`
130+
131+
Sprite Editor:
132+
- Produces `sprite` layers or sprite-entity records
133+
- Declares sprite/spritesheet assets
134+
- Maps frame/animation metadata and origin hints
135+
- Supports shared palette references through metadata links (non-authoritative at runtime)
136+
137+
Vector Asset Studio:
138+
- Produces `vector` layers or vector item collections
139+
- Declares vector/template assets
140+
- Maps primitives/style/transform payloads to normalized render items
141+
142+
## 6. Runtime Ownership Boundaries
143+
Engine/runtime owns:
144+
- Contract validation
145+
- Relative asset resolution
146+
- Normalized runtime model projection
147+
- Deterministic render sequencing
148+
- Clear validation errors
149+
150+
Tools own:
151+
- Valid contract output
152+
- Stable IDs
153+
- Correct layer/asset typing
154+
- Cross-reference integrity
155+
156+
Boundary guardrails:
157+
- Runtime must not silently repair missing required fields
158+
- Runtime must not infer absolute/local paths
159+
- Contract seam should avoid unrelated engine API redesign
160+
161+
## 7. Validation Rules + Acceptance Checklist
162+
Validation rules:
163+
- Required key presence
164+
- Supported `contractVersion`
165+
- Allowed `producer.tool`
166+
- Unique IDs by collection
167+
- Allowed layer kinds only
168+
- Valid asset references from layers/entities
169+
- Numeric/order field sanity (`zIndex`, opacity range)
170+
- 2D coordinate-space enforcement
171+
172+
Acceptance checklist for this BUILD docs PR:
173+
- Contract covers all 4 tools
174+
- Metadata rules are explicit
175+
- Asset record rules are explicit
176+
- Layer model + deterministic ordering are explicit
177+
- Runtime ownership boundary is explicit
178+
- Migration guidance is incremental and non-breaking
179+
- Docs-only scope preserved
180+
181+
## 8. Incremental Migration Guidance (Non-Breaking)
182+
Phase 1: Contract publication
183+
- Publish contract docs and validation checklist
184+
- No runtime or tool behavior changes required in this PR
185+
186+
Phase 2: Tool-side adapters (future BUILD/APPLY PRs)
187+
- Add tool exporters that emit normalized contract fields
188+
- Preserve legacy payload loading in parallel
189+
190+
Phase 3: Runtime seam adoption (future BUILD/APPLY PRs)
191+
- Introduce a contract validation/normalization seam
192+
- Keep existing public engine APIs stable
193+
- Deprecate legacy ad hoc mappings only after coverage and parity checks
194+
195+
## Guardrails Confirmed
196+
- No implementation code added
197+
- No engine architecture redesign beyond contract seam
198+
- No 3D scope introduced
199+
- No unrelated sample/game/tool modifications
200+
- Contract remains 2D-focused and low-risk extensible

0 commit comments

Comments
 (0)