Skip to content

Commit 6a3b783

Browse files
author
DavidQ
committed
Define King of the Iceberg layout contract
- Add minimal first-playable layout contract - Base contract on validated tool workflow export - Define platform, top-control, water, and visual roles - Add validation rules and example layout JSON - Keep scope docs-only with no gameplay implementation
1 parent 747333e commit 6a3b783

5 files changed

Lines changed: 479 additions & 43 deletions

File tree

‎docs/dev/codex_commands.md‎

Lines changed: 52 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -2,44 +2,59 @@ MODEL: GPT-5.3-codex
22
REASONING: low
33

44
PR purpose:
5-
Validate the tool workflow for creating a basic King of the Iceberg layout.
5+
Create the King of the Iceberg layout contract document from the validated tool workflow output.
66

77
Do not implement gameplay.
8-
Do not add new features unless a tiny test-only artifact is required to validate existing workflow.
8+
Do not modify runtime engine code.
9+
Do not modify sample games.
910
Do not modify start_of_day folders.
10-
Do not modify sample games or runtime engine files.
11-
12-
Main workflow:
13-
1. Launch Vector Map Editor.
14-
2. Confirm no hidden/default map loads.
15-
3. Create or load an explicit baseline layout.
16-
4. Represent 3 to 5 fragmented horizontal ice platforms.
17-
5. Confirm each platform is independently selectable.
18-
6. Confirm clearing selection shows explicit no-selection state.
19-
7. Save/export the layout state.
20-
8. Inspect exported state in State Inspector.
21-
9. Sanity-check Vector Asset Studio paint/stroke controls.
22-
10. Sanity-check Sprite Editor launch/header/no-fallback behavior.
23-
24-
Required report:
25-
Create docs/dev/reports/PR_tool_layout_workflow_baseline_report.md
26-
27-
Report must include:
11+
Do not run long samples tests unless directly required.
12+
13+
Use these inputs:
14+
- tmp/uat_exports/king_of_the_iceberg_layout_snapshot.json
15+
- tmp/uat_tool_layout_workflow_results.json
16+
- docs/dev/reports/PR_tool_layout_workflow_baseline_report.md
17+
18+
Create:
19+
- docs/dev/koti_layout_contract.md
20+
21+
The contract must include:
22+
1. Purpose
23+
2. Source artifacts used
24+
3. Minimal layout object shape
25+
4. Platform object requirements
26+
5. Required roles
27+
6. Optional fields
28+
7. Validation rules
29+
8. Example minimal layout JSON
30+
9. Out-of-scope items
31+
32+
Required roles:
33+
- platform
34+
- top-control-platform
35+
- water-zone
36+
- visual-background
37+
- visual-midground
38+
39+
Validation rules:
40+
- layout/map id is required
41+
- at least one top-control-platform is required
42+
- one water-zone is required
43+
- MVP layout has 3 to 5 platform objects
44+
- roles must be explicit
45+
- hidden fallback objects are not allowed
46+
- missing required fields produce actionable errors
47+
48+
Testing:
49+
- Docs-only targeted validation.
50+
- Do not run full samples suite.
51+
- If no JavaScript changed, node --check is not required.
52+
- Report what was validated.
53+
54+
Report:
55+
Create or update docs/dev/reports/PR_koti_layout_contract_report.md with:
2856
- PASS/FAIL
29-
- Changed files, if any
30-
- Validation steps performed
31-
- Export/save path
32-
- Any blockers
33-
- Remaining issues without masking them
34-
35-
Hard rules:
36-
- No silent fallback data.
37-
- No hidden sample auto-load.
38-
- Missing/invalid input must produce actionable messages.
39-
- Do not add King of the Iceberg runtime code.
40-
- Do not build tileset breakout yet.
41-
42-
Validation:
43-
- Run node --check on any changed JavaScript files.
44-
- Run npm run test:launch-smoke -- --tools.
45-
- If an exported JSON/layout file is produced, verify it with State Inspector.
57+
- changed files
58+
- source artifacts reviewed
59+
- validation performed
60+
- remaining issues

‎docs/dev/commit_comment.txt‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
Validate baseline tool layout workflow
1+
Define King of the Iceberg layout contract
22

3-
- Verify Vector Map Editor can represent fragmented platform layout
4-
- Confirm explicit selection and no-selection behavior
5-
- Confirm layout save/export path can be inspected
6-
- Sanity-check asset, sprite, and state tools after stabilization
7-
- Document workflow findings for first King of the Iceberg layout
3+
- Add minimal first-playable layout contract
4+
- Base contract on validated tool workflow export
5+
- Define platform, top-control, water, and visual roles
6+
- Add validation rules and example layout JSON
7+
- Keep scope docs-only with no gameplay implementation

‎docs/dev/koti_layout_contract.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# King of the Iceberg Layout Contract
2+
3+
## 1. Purpose
4+
5+
Define the minimal, explicit data contract for a King of the Iceberg (KOTI) baseline layout using validated tool workflow artifacts. This contract is documentation-only and does not introduce gameplay or runtime behavior.
6+
7+
## 2. Source Artifacts Used
8+
9+
- `tmp/uat_exports/king_of_the_iceberg_layout_snapshot.json`
10+
- `tmp/uat_tool_layout_workflow_results.json`
11+
- `docs/dev/reports/PR_tool_layout_workflow_baseline_report.md`
12+
13+
Observed baseline facts from these artifacts:
14+
15+
- Exported baseline layout contains 4 fragmented ice platform objects.
16+
- Selection behavior includes explicit no-selection state.
17+
- Save/export workflow completed and produced the snapshot artifact.
18+
19+
## 3. Minimal Layout Object Shape
20+
21+
The minimal KOTI layout uses explicit map metadata and explicit object roles.
22+
23+
```json
24+
{
25+
"documentData": {
26+
"name": "koti_first_arena",
27+
"mode": "2d",
28+
"width": 1600,
29+
"height": 900,
30+
"objects": [
31+
{
32+
"id": "obj-001",
33+
"name": "Top Control Platform",
34+
"kind": "polyline",
35+
"role": "top-control-platform",
36+
"points": [
37+
{ "x": 640, "y": 300, "z": 0 },
38+
{ "x": 840, "y": 300, "z": 0 }
39+
]
40+
}
41+
]
42+
}
43+
}
44+
```
45+
46+
## 4. Platform Object Requirements
47+
48+
- Platform objects are objects whose `role` is `platform` or `top-control-platform`.
49+
- MVP requires 3 to 5 platform objects total.
50+
- Each platform object must include:
51+
- `id` (non-empty string)
52+
- `name` (non-empty string)
53+
- `kind` (for baseline exports, `polyline` is valid)
54+
- `role` (explicit role value)
55+
- `points` (at least 2 points with numeric `x` and `y`)
56+
- Platform objects must be explicitly authored in layout data. Hidden/generated fallback platforms are not allowed.
57+
58+
## 5. Required Roles
59+
60+
The layout contract requires explicit use of these roles:
61+
62+
- `platform`
63+
- `top-control-platform`
64+
- `water-zone`
65+
- `visual-background`
66+
- `visual-midground`
67+
68+
Role notes:
69+
70+
- At least one object must have role `top-control-platform`.
71+
- Exactly one object must represent the `water-zone` for MVP validation.
72+
- `visual-background` and `visual-midground` may be represented as geometry or non-interactive scene objects, but roles must still be explicit.
73+
74+
## 6. Optional Fields
75+
76+
Optional fields are permitted when present in authored data:
77+
78+
- Layout-level: `version`, `background`
79+
- Object-level: `style`, `flags`, `center`, `rotation`, `space`, `closed`
80+
- Point-level: `z`, `color`
81+
82+
Optional fields do not replace required fields and cannot be used to infer missing required roles.
83+
84+
## 7. Validation Rules
85+
86+
A KOTI layout is valid only when all rules pass:
87+
88+
1. Layout/map id is required:
89+
- `documentData.name` must exist and be non-empty.
90+
2. At least one `top-control-platform` is required.
91+
3. One `water-zone` is required.
92+
4. MVP layout has 3 to 5 platform objects (`platform` + `top-control-platform`).
93+
5. Roles must be explicit (`role` is required on each contract-relevant object).
94+
6. Hidden fallback objects are not allowed.
95+
7. Missing required fields produce actionable errors.
96+
97+
Actionable error examples:
98+
99+
- `Missing required layout id: documentData.name`
100+
- `Missing required role: top-control-platform`
101+
- `Missing required role: water-zone`
102+
- `Invalid platform count: expected 3-5, found <n>`
103+
- `Object <id> is missing explicit role`
104+
105+
## 8. Example Minimal Layout JSON
106+
107+
```json
108+
{
109+
"documentData": {
110+
"name": "koti_first_arena",
111+
"mode": "2d",
112+
"width": 1600,
113+
"height": 900,
114+
"objects": [
115+
{
116+
"id": "obj-top-01",
117+
"name": "Top Control Platform",
118+
"kind": "polyline",
119+
"role": "top-control-platform",
120+
"points": [
121+
{ "x": 700, "y": 290, "z": 0 },
122+
{ "x": 900, "y": 290, "z": 0 }
123+
]
124+
},
125+
{
126+
"id": "obj-plat-01",
127+
"name": "Platform 01",
128+
"kind": "polyline",
129+
"role": "platform",
130+
"points": [
131+
{ "x": 420, "y": 520, "z": 0 },
132+
{ "x": 620, "y": 520, "z": 0 }
133+
]
134+
},
135+
{
136+
"id": "obj-plat-02",
137+
"name": "Platform 02",
138+
"kind": "polyline",
139+
"role": "platform",
140+
"points": [
141+
{ "x": 760, "y": 570, "z": 0 },
142+
{ "x": 980, "y": 570, "z": 0 }
143+
]
144+
},
145+
{
146+
"id": "obj-water-01",
147+
"name": "Water Zone",
148+
"kind": "rectangle",
149+
"role": "water-zone",
150+
"points": [
151+
{ "x": 0, "y": 760, "z": 0 },
152+
{ "x": 1600, "y": 900, "z": 0 }
153+
]
154+
},
155+
{
156+
"id": "obj-bg-01",
157+
"name": "Background Visual",
158+
"kind": "rectangle",
159+
"role": "visual-background",
160+
"points": [
161+
{ "x": 0, "y": 0, "z": 0 },
162+
{ "x": 1600, "y": 900, "z": 0 }
163+
]
164+
},
165+
{
166+
"id": "obj-mg-01",
167+
"name": "Midground Visual",
168+
"kind": "polyline",
169+
"role": "visual-midground",
170+
"points": [
171+
{ "x": 120, "y": 680, "z": 0 },
172+
{ "x": 1480, "y": 680, "z": 0 }
173+
]
174+
}
175+
]
176+
}
177+
}
178+
```
179+
180+
## 9. Out-of-Scope Items
181+
182+
- Gameplay logic
183+
- Runtime engine loader implementation details
184+
- Collision physics tuning
185+
- Platform pass-through/solid behavior implementation
186+
- Tileset breakout and art slicing
187+
- Sample game/runtime code changes

0 commit comments

Comments
 (0)