Skip to content

Commit 523782d

Browse files
author
DavidQ
committed
docs: game integration planning bundle
1 parent f3b4727 commit 523782d

10 files changed

Lines changed: 159 additions & 48 deletions

‎docs/dev/BIG_PICTURE_ROADMAP.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,9 @@ Do NOT change structure or wording.
6060

6161
# 🎮 TRACK F — GAME INTEGRATION
6262

63+
- [x] PLAN_PR_DEBUG_SURFACES_GAME_INTEGRATION
64+
- [x] BUILD_PR_DEBUG_SURFACES_GAME_INTEGRATION
65+
- [.] APPLY_PR_DEBUG_SURFACES_GAME_INTEGRATION
6366
- [ ] Sample game uses full debug platform
6467
- [ ] Toggle debug in production-safe mode
6568
- [ ] Performance-safe overlays
@@ -74,17 +77,17 @@ Do NOT change structure or wording.
7477
- [ ] Replication state viewer
7578
- [ ] Client/server divergence inspector
7679
- [ ] Event tracing
77-
- [x] PLAN_PR_DEBUG_SURFACES_NETWORK_SUPPORT
78-
- [x] BUILD_PR_DEBUG_SURFACES_NETWORK_SUPPORT
79-
- [.] APPLY_PR_DEBUG_SURFACES_NETWORK_SUPPORT
80+
- [.] PLAN_PR_DEBUG_SURFACES_NETWORK_SUPPORT
81+
- [ ] BUILD_PR_DEBUG_SURFACES_NETWORK_SUPPORT
82+
- [ ] APPLY_PR_DEBUG_SURFACES_NETWORK_SUPPORT
8083

8184
---
8285

8386
# 🧊 TRACK H — 3D DEBUG SUPPORT
8487

8588
- [.] Transform inspector
8689
- [x] BUILD_PR_DEBUG_SURFACES_3D_SUPPORT
87-
- [x] APPLY_PR_DEBUG_SURFACES_3D_SUPPORT
90+
- [.] APPLY_PR_DEBUG_SURFACES_3D_SUPPORT
8891
- [ ] Camera debug panel
8992
- [ ] Render pipeline stages
9093
- [ ] Collision overlays

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 4 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,9 @@ MODEL: GPT-5.4-codex
22
REASONING: high
33

44
COMMAND:
5-
Create PLAN_PR_DEBUG_SURFACES_NETWORK_SUPPORT, BUILD_PR_DEBUG_SURFACES_NETWORK_SUPPORT, and APPLY_PR_DEBUG_SURFACES_NETWORK_SUPPORT as a bundled docs pack
5+
Create PLAN/BUILD/APPLY_PR_DEBUG_SURFACES_GAME_INTEGRATION bundle
66

77
Requirements:
8-
- Follow PLAN_PR -> BUILD_PR -> APPLY_PR
9-
- Docs-first only
10-
- One PR purpose per document, but package all three together
11-
- Plan/build/apply the first reusable network support layer for the debug surfaces platform
12-
- Define shared network panels, shared network providers, optional shared network presets, adapter boundaries, adoption models, naming conventions, and target structure
13-
- Keep the first version summary-level and opt-in
14-
- Exclude protocol-specific implementations, packet inspectors, auth/matchmaking tooling, and deep inspectors from this bundle
15-
- Keep transport/protocol adapters outside the shared layer
16-
- Update BIG_PICTURE_ROADMAP.md by changing bracket states only
17-
- Include ROADMAP_GUARDRAILS.md unchanged
18-
- Package to <project folder>/tmp/DEBUG_SURFACES_NETWORK_SUPPORT_BUNDLE.zip
8+
- Docs only
9+
- Follow guardrails
10+
- Update roadmap brackets only

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
docs: bundle network support PLAN/BUILD/APPLY contracts for debug surfaces
1+
docs: bundle game integration PLAN/BUILD/APPLY contracts for debug surfaces

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
Next:
2-
PLAN_PR_DEBUG_SURFACES_GAME_INTEGRATION
2+
CONVERGENCE_PHASE_BUNDLE

‎docs/dev/reports/change_summary.txt‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,15 @@
1-
Created a docs-only bundled pack for network support planning/build/apply contracts.
1+
Created docs-only PLAN/BUILD/APPLY bundle for debug surfaces game integration.
22

33
Updated:
4-
- PLAN_PR_DEBUG_SURFACES_NETWORK_SUPPORT.md
5-
- BUILD_PR_DEBUG_SURFACES_NETWORK_SUPPORT.md
6-
- APPLY_PR_DEBUG_SURFACES_NETWORK_SUPPORT.md
4+
- PLAN_PR_DEBUG_SURFACES_GAME_INTEGRATION.md
5+
- BUILD_PR_DEBUG_SURFACES_GAME_INTEGRATION.md
6+
- APPLY_PR_DEBUG_SURFACES_GAME_INTEGRATION.md
77
- docs/dev command + commit artifacts
88
- docs/dev/reports summary/checklist/tree
99
- BIG_PICTURE_ROADMAP.md bracket states only
1010

11-
Scope enforced:
12-
- docs-first only
13-
- one purpose per document
14-
- summary-level + opt-in
15-
- transport/protocol specifics remain local
16-
- packet inspectors, auth/matchmaking, deep inspectors excluded
11+
Guardrails followed:
12+
- docs-only scope
13+
- one PR purpose per document
14+
- no structure/text edits in roadmap beyond bracket states
15+
- ROADMAP_GUARDRAILS.md retained unchanged

‎docs/dev/reports/file_tree.txt‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
DEBUG_SURFACES_NETWORK_SUPPORT_BUNDLE.zip
2-
- docs/pr/PLAN_PR_DEBUG_SURFACES_NETWORK_SUPPORT.md
3-
- docs/pr/BUILD_PR_DEBUG_SURFACES_NETWORK_SUPPORT.md
4-
- docs/pr/APPLY_PR_DEBUG_SURFACES_NETWORK_SUPPORT.md
1+
DEBUG_SURFACES_GAME_INTEGRATION_BUNDLE.zip
2+
- docs/pr/PLAN_PR_DEBUG_SURFACES_GAME_INTEGRATION.md
3+
- docs/pr/BUILD_PR_DEBUG_SURFACES_GAME_INTEGRATION.md
4+
- docs/pr/APPLY_PR_DEBUG_SURFACES_GAME_INTEGRATION.md
55
- docs/dev/BIG_PICTURE_ROADMAP.md
66
- docs/dev/ROADMAP_GUARDRAILS.md
77
- docs/dev/codex_commands.md

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 9 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,12 @@
11
Validation Checklist
22

3-
[x] PLAN/BUILD/APPLY docs are all present
4-
[x] One PR purpose per document is clear
5-
[x] Workflow PLAN -> BUILD -> APPLY is explicit in all docs
6-
[x] Shared network panel inventory is explicit
7-
[x] Shared network provider inventory is explicit
8-
[x] Optional shared network presets are explicit
9-
[x] Adapter boundaries are explicit
10-
[x] Adoption models are included
11-
[x] Naming conventions are included
12-
[x] Target structure is included
13-
[x] Transport/protocol adapters are outside shared layer
14-
[x] Protocol-specific implementation excluded
15-
[x] Packet inspector scope excluded
16-
[x] Auth/matchmaking tooling excluded
17-
[x] Deep inspector scope excluded
3+
[x] PLAN/BUILD/APPLY docs are present
4+
[x] One PR purpose per document is explicit
5+
[x] Docs-only scope maintained
6+
[x] PLAN -> BUILD -> APPLY workflow is explicit
7+
[x] Game-integration boundaries are defined
8+
[x] Env flag contract is defined
9+
[x] Lifecycle and rollback notes are defined
1810
[x] BIG_PICTURE_ROADMAP.md changed by bracket states only
19-
[x] ROADMAP_GUARDRAILS.md included unchanged
11+
[x] ROADMAP_GUARDRAILS.md left unchanged
12+
[x] Bundle contains docs-only artifacts

‎docs/pr/APPLY_PR_DEBUG_SURFACES_GAME_INTEGRATION.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# APPLY_PR_DEBUG_SURFACES_GAME_INTEGRATION
2+
3+
## Purpose
4+
Apply the approved game-integration contract in one focused implementation step.
5+
6+
## Workflow
7+
PLAN_PR -> BUILD_PR -> APPLY_PR
8+
9+
## PR Purpose
10+
One PR purpose only: implement sample/game integration wiring for debug surfaces.
11+
12+
## Apply Scope
13+
- apply integration in one selected sample/game entry file
14+
- respect debug environment flags
15+
- initialize and dispose debug surfaces via public APIs only
16+
- preserve gameplay/render loop behavior parity when debug disabled
17+
18+
## Execution Order
19+
1. Add/normalize debug flags at sample entry.
20+
2. Wire debug surface init behind flags.
21+
3. Wire update/render calls in deterministic order.
22+
4. Ensure dispose/cleanup path.
23+
5. Validate enabled and disabled mode behavior.
24+
25+
## Hard Rules
26+
- no engine-core changes unless absolutely required
27+
- no unrelated refactors
28+
- keep sample-specific wiring in sample layer
29+
- use existing debug surface public APIs only
30+
31+
## Validation
32+
- syntax checks for touched files
33+
- sample run with debug disabled (parity check)
34+
- sample run with debug enabled (console/overlay functional)
35+
- input behavior remains scoped and stable

‎docs/pr/BUILD_PR_DEBUG_SURFACES_GAME_INTEGRATION.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# BUILD_PR_DEBUG_SURFACES_GAME_INTEGRATION
2+
3+
## Purpose
4+
Build a docs-only, implementation-ready bundle for game integration of debug surfaces.
5+
6+
## Workflow
7+
PLAN_PR -> BUILD_PR -> APPLY_PR
8+
9+
## PR Purpose
10+
One PR purpose only: convert game-integration planning into apply-ready implementation guidance.
11+
12+
## Build Scope
13+
- game/sample bootstrap wiring contract
14+
- environment flag contract
15+
- debug lifecycle contract
16+
- validation and rollback checklist
17+
18+
## Authoritative Build Targets
19+
- one sample/game integration reference (minimal and reversible)
20+
- debug flag normalization (`debugEnabled`, `debugMode`)
21+
- clear enable/disable lifecycle hooks
22+
- no runtime behavior drift when disabled
23+
24+
## Guardrails
25+
- docs-only
26+
- no engine-core modifications in BUILD docs
27+
- no unrelated tooling/feature expansion
28+
- keep integration sample-level first
29+
30+
## Validation Targets
31+
- disabled mode parity with baseline behavior
32+
- enabled mode deterministic console/overlay lifecycle
33+
- controlled input toggles and cleanup
34+
35+
## Rollback Strategy
36+
- remove integration wiring at sample entry only
37+
- keep debug shared modules intact
38+
- verify baseline parity after rollback
39+
40+
## Next Command
41+
`APPLY_PR_DEBUG_SURFACES_GAME_INTEGRATION`

‎docs/pr/PLAN_PR_DEBUG_SURFACES_GAME_INTEGRATION.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# PLAN_PR_DEBUG_SURFACES_GAME_INTEGRATION
2+
3+
## Objective
4+
Plan the first reusable game-integration layer for debug surfaces across sample/game entry points.
5+
6+
## Workflow
7+
PLAN_PR -> BUILD_PR -> APPLY_PR
8+
9+
## PR Purpose
10+
One PR purpose only: define game-integration planning contracts for debug surfaces.
11+
12+
## Goals
13+
- Define safe integration points for one sample/game entry.
14+
- Define debug enablement policy by environment mode.
15+
- Define command/overlay lifecycle boundaries in game runtime.
16+
- Define rollout and rollback approach for production-safe integration.
17+
18+
## In Scope
19+
- Integration seam at sample/game bootstrap level.
20+
- Feature flag contract (`debugEnabled`, `debugMode`).
21+
- Deterministic debug surface activation/deactivation behavior.
22+
- Validation strategy for enabled and disabled modes.
23+
24+
## Out of Scope
25+
- Engine-core refactors.
26+
- Gameplay logic changes.
27+
- New debug features unrelated to integration.
28+
- Network/3D/deep-inspector expansion.
29+
30+
## Integration Contract (Summary)
31+
- Debug surfaces are opt-in and disabled by default for production.
32+
- Integration occurs at game/sample entry composition only.
33+
- Console and overlay are initialized only when debug is enabled.
34+
- Existing gameplay/render loop remains unchanged when debug is disabled.
35+
36+
## Environment Modes (v1)
37+
- `dev`: debug enabled by default
38+
- `qa`: debug enabled via explicit flag
39+
- `prod`: debug disabled by default
40+
41+
## Validation Goals
42+
- No behavior regression when debug disabled.
43+
- Console and overlay lifecycle is deterministic when enabled.
44+
- Input bindings are debug-scoped and non-invasive.
45+
46+
## Next Commands
47+
1. `BUILD_PR_DEBUG_SURFACES_GAME_INTEGRATION`
48+
2. `APPLY_PR_DEBUG_SURFACES_GAME_INTEGRATION`

0 commit comments

Comments
 (0)