Skip to content

Commit 1978ca3

Browse files
author
DavidQ
committed
define playable multiplayer validation slice and acceptance gates — PLAN_PR_LEVEL_12_4_PLAYABLE_MULTIPLAYER_VALIDATION & reorder and clarify section 17 finalize engine — PLAN_PR_LEVEL_17_ENGINE_FINALIZATION_REORDER
1 parent ecac3c9 commit 1978ca3

8 files changed

Lines changed: 236 additions & 30 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 7 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,8 @@
1-
2-
MODEL: GPT-5.4
3-
REASONING: medium
4-
1+
MODEL: GPT-5.3-codex
2+
REASONING: low
53
COMMAND:
6-
Prepare for Phase 16 execution using PLAN_PR_3D_PHASE16_MASTER_EXECUTION
7-
8-
Do NOT implement yet.
9-
10-
Tasks:
11-
- understand layer ordering
12-
- prepare for Layer 1 start
13-
- ensure no conflicts with existing engine
14-
- confirm separation from 2D systems
15-
16-
Rules:
17-
- no code generation in this step
18-
- no repo modification
19-
- planning only
4+
Update Section 17 in MASTER_ROADMAP_HIGH_LEVEL.md.
5+
Only reorder and lightly clarify wording.
6+
Do NOT remove items.
7+
Do NOT change meaning.
8+
Do NOT modify other sections.

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Plan Phase 16 3D execution (all items structured into layers)
1+
reorder and clarify section 17 finalize engine — PLAN_PR_LEVEL_17_ENGINE_FINALIZATION_REORDER

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,4 @@
1-
plan-only; no code; no repo changes; layered execution defined
1+
- All items preserved
2+
- Order improved
3+
- No wording drift
4+
- Section isolated

‎docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -661,13 +661,13 @@
661661

662662

663663
## 17. Finalize engine
664-
[ ] Verify all samples/ and games/ must use engine and not coded locally, if local, update to use engine
665-
[ ] docs/organization, classify all ./docs/ into buckets
666-
[ ] arrage docs into a classification bucket
667-
[ ] any doc that is a move/rename/etc. should be deleted (verify content is in the correct doc before deleting)
668-
[ ] consolidate PR for easier, one stop, review, no need to look as 6 different docs for one capability (a good example of this is bezel/background), all people care about is what it does.
669-
[ ] some games are actually samples/demo, identify and recomment a phase-xx to move to.
670-
[ ] simulated code (like some of the netword samples) should be coverted to use real networks) understanding, tests may need some moch
671-
[ ] single class per file
672-
[ ] organize/rebuild samples/games so the are as if new construction with proper classes/data/etc in proper folder
673-
[ ] flatten css layer, there should only be a few, use as much as possible to top layer a button is a button, should be a single class to operate, I know exceptions can exist
664+
[ ] Verify all `samples/` and `games/` use engine systems and are not coded locally; if local, migrate to engine.
665+
[ ] Some games are actually samples/demos; identify and recommend a `phase-xx` move target.
666+
[ ] 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.
668+
[ ] Single class per file.
669+
[ ] 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).
670+
[ ] Docs organization: classify all `./docs/` into buckets.
671+
[ ] Arrange docs into classification buckets.
672+
[ ] Any doc that is only move/rename/etc. should be deleted (verify content is in the correct doc before deleting).
673+
[ ] Consolidate PRs for easier one-stop review, so one capability does not require reading many docs (for example, bezel/background); focus on what the capability does.

‎docs/pr/BUILD_PR_LEVEL_12_4_PLAYABLE_MULTIPLAYER_VALIDATION.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# BUILD_PR_LEVEL_12_4_PLAYABLE_MULTIPLAYER_VALIDATION
2+
3+
## Purpose
4+
Execute one minimal playable real-multiplayer validation slice on top of completed Level 12.1, 12.2, and 12.3 network layers.
5+
6+
## Scope
7+
Primary target files:
8+
- `tests/final/MultiplayerNetworkingStack.test.mjs`
9+
- `docs/pr/LEVEL_12_4_PLAYABLE_MULTIPLAYER_VALIDATION_CHECKLIST.md`
10+
- `docs/pr/LEVEL_12_4_PLAYABLE_MULTIPLAYER_VALIDATION_FAILURE_MODES.md`
11+
- `docs/pr/APPLY_PR_LEVEL_12_4_PLAYABLE_MULTIPLAYER_VALIDATION.md`
12+
13+
Allowed nearby reads:
14+
- `src/engine/network/LoopbackTransport.js`
15+
- `src/engine/network/HandshakeSimulator.js`
16+
- `src/engine/network/AuthoritativeServerRuntime.js`
17+
- `src/engine/network/ClientReplicationApplicationLayer.js`
18+
- `docs/pr/LEVEL_12_3_REPLICATION_CLIENT_APPLICATION_CONTRACTS.md`
19+
20+
## Required implementation
21+
- Add one validation-only multiplayer scenario proving end-to-end flow in a single deterministic slice:
22+
- server starts
23+
- client connects and session reaches active state
24+
- authoritative state is replicated to client
25+
- one minimal shared action is observable on both sides
26+
- disconnect and cleanup complete without residue
27+
- Keep scenario narrow and reusable; no feature expansion beyond validation.
28+
- Produce repeatable validation checklist and failure-mode checklist docs.
29+
- Record APPLY summary focused on validation evidence only.
30+
31+
## Acceptance criteria
32+
- Real session startup and shutdown are validated in one repeatable slice.
33+
- Live replication is observed at client for the chosen action.
34+
- Validation and failure modes are documented and reproducible.
35+
- Scope remains one playable validation slice only.
36+
- No 3D work is introduced.
37+
38+
## Validation
39+
Run only:
40+
- `node --input-type=module -e "import('./tests/final/MultiplayerNetworkingStack.test.mjs').then(async ({ run }) => { await run(); console.log('PASS MultiplayerNetworkingStack'); })"`
41+
- `node --input-type=module -e "import('./tests/production/EnginePublicBarrelImports.test.mjs').then(async ({ run }) => { await run(); console.log('PASS EnginePublicBarrelImports'); })"`
42+
43+
## Non-goals
44+
- no gameplay expansion beyond the one validation action
45+
- no prediction/rollback lane work
46+
- no debug platform expansion unless strictly required to validate the slice
47+
- no tool expansion
48+
- no 3D/Phase 16 work
49+
- no roadmap wording or structure edits
50+
51+
## Working tree rule
52+
If the tree is already dirty, ignore unrelated files and modify only the scoped files for this PR purpose.

‎docs/pr/LEVEL_12_4_PLAYABLE_MULTIPLAYER_VALIDATION_PREP.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# LEVEL_12_4_PLAYABLE_MULTIPLAYER_VALIDATION_PREP
2+
3+
## Goal
4+
Prepare a docs-first, implementation-ready plan for one minimal playable real-multiplayer validation slice, without broadening scope and without any 3D work.
5+
6+
## Validation Slice Definition (Single Scenario)
7+
8+
Scenario key: `multiplayer.validation.slice.one`
9+
10+
Minimal flow:
11+
1. Start authoritative server runtime
12+
2. Establish client session and active handshake
13+
3. Send one validated client action to server (`move` input)
14+
4. Server emits one authoritative replication update
15+
5. Client applies update and reflects synchronized state
16+
6. Execute disconnect and cleanup
17+
18+
## Startup / Shutdown Contract
19+
20+
Startup success conditions:
21+
- server runtime phase is `running`
22+
- handshake reaches active on host + client
23+
- replication apply status advances to new authoritative tick
24+
25+
Shutdown success conditions:
26+
- session transitions to disconnected
27+
- pending input/replication queues drain to zero
28+
- no stale runtime state leaks into next run
29+
30+
## Deterministic Acceptance Checks
31+
32+
- Connection: `connected`/`active` state achieved in defined order
33+
- Session: lifecycle transitions valid and complete
34+
- Replication: client `lastAppliedTick` increases after server update
35+
- Playability: one shared action produces same observable authoritative result on both sides
36+
- Cleanup: stop/disconnect leaves runtime in deterministic terminal state
37+
38+
## Failure-Mode Checklist Targets
39+
40+
- handshake does not reach active
41+
- server ingest rejects valid action unexpectedly
42+
- replication envelope rejected unexpectedly
43+
- client apply ignores non-stale authoritative update
44+
- disconnect leaves pending queues or active runtime phase
45+
46+
## Scope Guardrails
47+
48+
- one validation slice only
49+
- no new gameplay systems
50+
- no debug/tool expansion unless required by this exact validation
51+
- no prediction/rollback additions
52+
- no Phase 16 / 3D work
53+
54+
## Roadmap Marker Rule
55+
56+
`docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md` may be updated by status markers only (`[ ]`, `[.]`, `[x]`) and only where validation evidence exists.

‎docs/pr/PLAN_PR_LEVEL_12_4_PLAYABLE_MULTIPLAYER_VALIDATION.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# PLAN_PR_LEVEL_12_4_PLAYABLE_MULTIPLAYER_VALIDATION
2+
3+
## Purpose
4+
Validate a playable real-multiplayer path on top of completed transport, authoritative server runtime, and client replication layers.
5+
6+
## Scope
7+
- Define the smallest playable multiplayer validation slice
8+
- Define server/client startup path for the validation scenario
9+
- Define success/failure conditions for live session validation
10+
- Define deterministic acceptance checks for connection, session, replication, and playability
11+
12+
## In Scope
13+
- One minimal playable scenario only
14+
- Real transport/server/client interaction
15+
- Validation-focused session flow
16+
- Validation-focused replication correctness checks
17+
18+
## Out of Scope
19+
- No broad gameplay expansion
20+
- No new debug platform expansion unless strictly required for validation
21+
- No prediction/rollback lane
22+
- No 3D work
23+
- No tool expansion
24+
25+
## Required Inputs
26+
- Real transport/session layer already integrated
27+
- Authoritative server runtime already integrated
28+
- Client replication/application layer already integrated
29+
30+
## Validation Scenario
31+
Use one minimal multiplayer scenario that proves:
32+
1. server starts and accepts a client
33+
2. client connects successfully
34+
3. session state becomes active
35+
4. replicated authoritative state reaches the client
36+
5. a minimal shared gameplay action is observable on both sides
37+
6. disconnect/cleanup path behaves correctly
38+
39+
## Deliverables
40+
- Playable validation target definition
41+
- Session startup/shutdown contract
42+
- Minimal validation checklist
43+
- Failure-mode checklist
44+
- Roadmap status update instruction
45+
46+
## Acceptance Criteria
47+
- A real client/server multiplayer session can be started
48+
- The chosen validation action is observable and synchronized
49+
- Replication path is proven in a live session
50+
- Validation steps are documented and repeatable
51+
- No wording edits in roadmap; status markers only
52+
53+
## Roadmap Update Rule
54+
Codex must update:
55+
docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
56+
57+
Rule:
58+
- only update status markers [ ] [.] [x]
59+
- do not change wording
60+
- do not change structure
61+
- do not add content
62+
- do not delete content
63+
64+
## Non-Goals
65+
- Do not start Phase 16 / 3D execution here
66+
- Do not broaden scope beyond multiplayer validation

‎docs/pr/PLAN_PR_LEVEL_17_ENGINE_FINALIZATION_REORDER.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# PLAN_PR_LEVEL_17_ENGINE_FINALIZATION_REORDER
2+
3+
## Purpose
4+
Reorder and clarify Section 17 "Finalize engine" without changing scope, intent, or removing any items.
5+
6+
## Rules
7+
- Do NOT remove any items
8+
- Do NOT change core meaning
9+
- Only reorder and clarify wording
10+
- Keep status markers intact
11+
12+
## Updated Section 17 (Reordered)
13+
14+
## 17. Finalize engine
15+
16+
### Engine Integrity
17+
[ ] Verify all samples/ and games/ must use engine and not coded locally, if local, update to use engine
18+
[ ] single class per file
19+
20+
### Network Alignment
21+
[ ] simulated code (like some of the network samples) should be converted to use real networks (tests may require mocks)
22+
23+
### Samples & Games Normalization
24+
[ ] organize/rebuild samples/games so they are as if new construction with proper classes/data/etc in proper folder
25+
[ ] some games are actually samples/demo, identify and recommend a phase-xx to move to
26+
27+
### Documentation Cleanup
28+
[ ] docs/organization, classify all ./docs/ into buckets
29+
[ ] arrange docs into a classification bucket
30+
[ ] any doc that is a move/rename/etc. should be deleted (verify content is in the correct doc before deleting)
31+
[ ] consolidate PR docs into single review surfaces per capability
32+
33+
### UI/CSS Normalization
34+
[ ] flatten css layer, minimize layers, prefer shared top-level styles (button = single class where possible)
35+
36+
## Acceptance Criteria
37+
- Section 17 reordered only
38+
- No meaning changed
39+
- No items removed
40+
- Readability improved

0 commit comments

Comments
 (0)