Skip to content

Commit 07c2192

Browse files
author
DavidQ
committed
define real-network sample launch and live dashboard requirements — PLAN_PR_LEVEL_12_10_REAL_NETWORK_SAMPLE_AND_DASHBOARD
1 parent 738bc7d commit 07c2192

6 files changed

Lines changed: 259 additions & 20 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 5 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,8 @@
11
MODEL: GPT-5.4
22
REASONING: high
33
COMMAND:
4-
Implement BUILD_PR_LEVEL_12_9_NETWORK_USAGE_SAMPLE_STANDARDIZATION exactly as defined.
5-
Standardize the targeted phase-13 sample scenes so they consume the network API via src/engine/network/index.js only.
6-
Remove deep or legacy flat network-path usage in the targeted sample set where present.
7-
Do not change sample behavior, controls, timing, outputs, or runtime logic.
8-
If needed, update src/engine/network/index.js export coverage so sample behavior stays unchanged.
9-
Run real validation:
10-
- import/path resolution for all targeted samples
11-
- network runtime smoke boot
12-
- transport/session lifecycle smoke
13-
- authoritative runtime boot smoke
14-
- replication/apply smoke
15-
- focused 2D regression smoke
16-
Update docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md by changing status markers only.
17-
Do not modify roadmap wording, structure, add content, or delete content.
4+
Use this PLAN to prepare the next BUILD for a real-network launchable sample plus live server dashboard.
5+
Keep scope minimal and testable.
6+
Do not start 3D work.
7+
Do not rely on simulation-only networking.
8+
Update roadmap by status markers only.

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
apply standardized network usage across phase-13 samples — APPLY_PR_LEVEL_12_9_NETWORK_USAGE_SAMPLE_STANDARDIZATION
1+
define real-network sample launch and live dashboard requirements — PLAN_PR_LEVEL_12_10_REAL_NETWORK_SAMPLE_AND_DASHBOARD

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
- imports normalized
2-
- validation passed
3-
- no regressions
4-
- roadmap markers updated only
1+
- missing execution-facing network capabilities identified
2+
- scope limited to real-network sample + dashboard
3+
- remains testable
4+
- roadmap updates restricted to marker-only progression
5+
- 3D remains gated

‎docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -664,7 +664,7 @@
664664
[ ] Verify all `samples/` and `games/` use engine systems and are not coded locally; if local, migrate to engine.
665665
[ ] Some games are actually samples/demos; identify and recommend a `phase-xx` move target.
666666
[ ] Organize/rebuild `samples/` and `games/` as if newly constructed, with proper classes/data in proper folders.
667-
[ ] Simulated code (for example, some network samples) should be converted to real networks, with tests as needed.
667+
[.] Simulated code (for example, some network samples) should be converted to real networks, with tests as needed.
668668
[ ] Single class per file.
669669
[ ] Flatten CSS layers so only a few remain; use top-layer shared classes as much as possible (for example, a button should use one standard class, with exceptions only when needed).
670670
[ ] Docs organization: classify all `./docs/` into buckets.

‎docs/pr/BUILD_PR_LEVEL_12_10_REAL_NETWORK_SAMPLE_AND_DASHBOARD.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# BUILD_PR_LEVEL_12_10_REAL_NETWORK_SAMPLE_AND_DASHBOARD
2+
3+
## Build Scope
4+
Implement one minimal real-network launchable sample plus one live server dashboard surface.
5+
6+
## One PR Purpose Only
7+
Real-network sample launch + live dashboard execution slice only.
8+
9+
## Build Intent
10+
Deliver the smallest execution-backed, non-simulated network sample flow that is launchable and observable:
11+
1. real server endpoint
12+
2. real client connection path
13+
3. live session telemetry dashboard
14+
15+
## Constraints
16+
- no 3D work
17+
- no feature expansion beyond launchability + observability
18+
- no simulation-only networking path
19+
- no protocol redesign beyond minimal needs for this launchable slice
20+
21+
## Required Deliverables
22+
23+
### A. Real-Network Launchable Sample
24+
- one canonical sample under `samples/phase-13/1319/`
25+
- browser/client path connects to a real server endpoint
26+
- at least two clients can join one live session
27+
- authoritative state update is visible across clients
28+
- disconnect/reconnect path is observable and stable
29+
30+
### B. Live Server Dashboard
31+
- dashboard loads over HTTP
32+
- live values are sourced from real session/runtime data (not fake loopback feed)
33+
- minimum visible telemetry:
34+
- active players
35+
- connection/session count
36+
- per-player status
37+
- lag / RTT
38+
- RX bytes
39+
- TX bytes
40+
- health status
41+
42+
## Exact Target Files
43+
44+
### New / Updated Sample Runtime
45+
- `samples/phase-13/1319/index.html`
46+
- `samples/phase-13/1319/main.js`
47+
- `samples/phase-13/1319/game/RealNetworkLaunchScene.js`
48+
49+
### New / Updated Real Server + Dashboard
50+
- `samples/phase-13/1319/server/realNetworkServer.mjs`
51+
- `samples/phase-13/1319/server/realNetworkDashboard.mjs`
52+
- `samples/phase-13/1319/server/README.md`
53+
- `samples/phase-13/1319/server/docker-compose.yml` (single-node local/live validation)
54+
55+
### Optional Engine Export Adjustment (only if needed)
56+
- `src/engine/network/index.js`
57+
58+
## Implementation Rules
59+
1. Do not use fake loopback/simulation as the primary network path for this sample.
60+
2. Keep behavior minimal and testable; avoid broad UI or gameplay additions.
61+
3. Reuse existing network contracts and layers where possible.
62+
4. Preserve existing engine/network API surfaces unless an additive export is required.
63+
5. Keep all changes scoped to this real-network sample + dashboard lane.
64+
65+
## Validation Requirements (Execution-Backed)
66+
67+
### 1. Import / Path Resolution
68+
- all new/updated sample and server modules load successfully
69+
- no broken imports in targeted files
70+
71+
### 2. Real-Network Runtime Boot
72+
- server process starts and listens on configured real endpoint
73+
- health endpoint returns ready state
74+
75+
### 3. Transport / Session Lifecycle
76+
- client-1 connects successfully
77+
- client-2 connects successfully
78+
- both clients transition to active session
79+
- one client disconnects and reconnects without invalid/stuck lifecycle state
80+
81+
### 4. Authoritative Runtime
82+
- authoritative runtime starts and remains running during active session window
83+
- server accepts input and produces authoritative updates
84+
85+
### 5. Replication / Apply
86+
- client receives authoritative updates
87+
- replicated state changes are visible for both connected clients
88+
- replication/apply path remains stable through reconnect step
89+
90+
### 6. Live Dashboard Validation
91+
- dashboard route loads
92+
- player/session counts update during connect/disconnect
93+
- lag/RTT and RX/TX values are visible and change during traffic
94+
- per-player rows/status update during session lifecycle
95+
96+
### 7. Focused 2D Regression Smoke
97+
- `tests/core/Engine2DCapabilityCombinedFoundation.test.mjs`
98+
- `tests/core/EngineCoreBoundaryBaseline.test.mjs`
99+
- `tests/games/AsteroidsValidation.test.mjs`
100+
101+
## Required Validation Commands (minimum)
102+
- `node --input-type=module -` (import/path and lifecycle/replication smoke harness)
103+
- `node --input-type=module -` (live dashboard/telemetry probe harness)
104+
- `node --input-type=module -` (focused 2D regression harness)
105+
106+
## Roadmap Rule
107+
Update:
108+
`docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
109+
110+
Allowed:
111+
- status markers only: `[ ]` `[.]` `[x]`
112+
113+
Forbidden:
114+
- wording edits
115+
- structure edits
116+
- additions
117+
- deletions
118+
119+
## Marker Progress
120+
- planning/prep can move related real-network conversion lane to in-progress
121+
- completion moves to complete only on full execution-backed validation pass
122+
123+
## Acceptance Criteria
124+
- one real-network launchable sample exists and boots
125+
- one live dashboard exists and shows real session telemetry
126+
- simulation-only dependency is not the sample's primary network path
127+
- all required validation areas pass with execution evidence
128+
- no 3D work introduced

‎docs/pr/PLAN_PR_LEVEL_12_10_REAL_NETWORK_SAMPLE_AND_DASHBOARD.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# PLAN_PR_LEVEL_12_10_REAL_NETWORK_SAMPLE_AND_DASHBOARD
2+
3+
## Purpose
4+
Add a real-network launchable sample and a live server dashboard so networking can be tested without simulation.
5+
6+
## Why This PR Exists
7+
The current network lane is still missing two execution-facing capabilities:
8+
1. a sample that launches against a real network path (not simulated/loopback-only)
9+
2. a dashboard that shows players, lag, and related live session telemetry
10+
11+
This means the network lane should continue before any 3D activation work.
12+
13+
## One PR Purpose Only
14+
Real-network sample launch + live dashboard planning only.
15+
16+
## Scope
17+
Define the smallest testable PR that delivers:
18+
- one canonical sample that can connect over a real network
19+
- one live dashboard surface for server/session visibility
20+
21+
## In Scope
22+
- one real-network sample target
23+
- server launch/startup path for real network use
24+
- dashboard requirements for players, lag, and session visibility
25+
- validation requirements
26+
- roadmap marker-only update rule
27+
28+
## Out Of Scope
29+
- no 3D work
30+
- no simulation-only path
31+
- no broad UI redesign
32+
- no unrelated engine cleanup
33+
- no feature expansion beyond launchability and observability
34+
35+
## Required Capabilities
36+
37+
### A. Real-Network Launchable Sample
38+
The sample must:
39+
- launch without simulation-only dependencies
40+
- connect to a real server endpoint
41+
- support at least one live multi-client session
42+
- demonstrate authoritative state updates over a real connection
43+
- remain minimal and testable
44+
45+
### B. Live Server Dashboard
46+
The dashboard must show at minimum:
47+
- active players
48+
- connection/session count
49+
- per-player status
50+
- lag / RTT
51+
- RX bytes
52+
- TX bytes
53+
- server/session health visibility
54+
55+
## Preferred Location Targets
56+
These exact file paths can be finalized in BUILD against the current repo state, but the intent is:
57+
58+
### Sample
59+
- `samples/phase-13/<real-network-sample>/`
60+
or
61+
- one canonical `samples/network/validation/` home if that is already the accepted pattern
62+
63+
### Dashboard
64+
- existing server/dashboard surface if already present and suitable
65+
- otherwise a minimal dedicated server dashboard surface under the current network/server tool/runtime area
66+
67+
## Validation Requirements
68+
The BUILD/APPLY that follows this PLAN must be testable and must validate:
69+
70+
### Real-Network Sample
71+
1. server starts on a real endpoint
72+
2. client sample connects over non-simulated transport
73+
3. second client can join
74+
4. authoritative state is visible across clients
75+
5. disconnect/reconnect behavior is valid
76+
77+
### Dashboard
78+
1. dashboard loads successfully
79+
2. player/session counts are visible
80+
3. lag / RTT is visible
81+
4. RX/TX visibility works
82+
5. per-player visibility works
83+
6. values update during a live session
84+
85+
### Regression Protection
86+
1. no breakage to existing normalized network imports
87+
2. no breakage to targeted phase-13 sample scenes
88+
3. focused 2D regression smoke still passes
89+
90+
## Testability Rule
91+
This must be a real, testable PR.
92+
It must not be commit-only.
93+
Roadmap progression must move only through execution-backed markers:
94+
- `[ ]`
95+
- `[.]`
96+
- `[x]`
97+
98+
## Roadmap Rule
99+
Update:
100+
`docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
101+
102+
Allowed:
103+
- status markers only
104+
105+
Forbidden:
106+
- wording edits
107+
- structure edits
108+
- additions
109+
- deletions
110+
111+
## Recommended Next Step
112+
Generate:
113+
- `BUILD_PR_LEVEL_12_10_REAL_NETWORK_SAMPLE_AND_DASHBOARD`
114+
115+
## Acceptance Criteria
116+
- one real-network launchable sample is defined
117+
- one live server dashboard requirement set is defined
118+
- validation is execution-backed and testable
119+
- 3D remains gated until this is done

0 commit comments

Comments
 (0)