docs(roadmap): Phase M — Network Stack Conformance plan
Adds the Phase M planning entry: replace the happy-path WorldSession shape with a holtburger-aligned reliable network stack while keeping acdream's stricter checksum verification + live ACE compatibility. Lays out M.1–M.x sub-lanes (audit/parity map, layer extraction, reliability core, etc.). Detailed spec to land at docs/superpowers/specs/2026-05-02-network-stack-conformance.md before implementation starts. Holtburger is the client-behavior oracle for this phase. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Erik
parent
17a9ff1158
commit
77b59d89e2
1 changed files with 102 additions and 1 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# acdream — strategic roadmap
|
||||
|
||||
**Status:** Living document. Updated 2026-04-29 for Phase L.2 movement/collision conformance planning.
|
||||
**Status:** Living document. Updated 2026-05-02 for Phase M network-stack conformance planning.
|
||||
**Purpose:** One source of truth for where the project is and where it's going. Every observed defect or missing feature has a named phase that owns it; when something looks wrong in-game, look here to find the phase that'll address it. Implementation details live in per-phase specs under `docs/superpowers/specs/`, not in this file.
|
||||
|
||||
---
|
||||
|
|
@ -403,6 +403,101 @@ diagnostic scaffolding, not yet the final collision system.
|
|||
|
||||
---
|
||||
|
||||
### Phase M — Network Stack Conformance
|
||||
|
||||
**Status:** PLANNED.
|
||||
|
||||
**Goal:** replace the current happy-path `WorldSession` networking shape with a
|
||||
proper AC client network stack that reaches functional parity with
|
||||
`references/holtburger/` while preserving acdream's stricter packet checksum
|
||||
verification and live ACE compatibility. This phase owns packet reliability,
|
||||
ordered delivery, retransmission, ACK piggybacking, echo/keepalive, typed
|
||||
message/action routing, diagnostics, and the migration of low-level network
|
||||
responsibilities out of the render tick.
|
||||
|
||||
**Why now:** The Phase 4/A.3 stack is good enough for local ACE smoke testing:
|
||||
login, ISAAC, checksums, per-packet ACKs, fragments, movement, chat, combat,
|
||||
and object updates all work. It is not yet a complete client network runtime.
|
||||
Compared with holtburger it lacks ordered S2C delivery, retransmit request
|
||||
handling, outbound packet caching/retransmission, ACK piggybacking,
|
||||
EchoRequest/EchoResponse handling, runtime ping/timeout policy, and a typed
|
||||
protocol/action layer. These gaps will become expensive as movement, dungeons,
|
||||
inventory, combat, and plugins depend on stable packet semantics.
|
||||
|
||||
**Plan of record:** create
|
||||
`docs/superpowers/specs/2026-05-02-network-stack-conformance.md` before
|
||||
implementation starts. Treat holtburger as the client-behavior oracle for this
|
||||
phase; cross-check wire details against named retail, ACE, Chorizite, and AC2D
|
||||
before porting.
|
||||
|
||||
**Sub-lanes:**
|
||||
- **M.1 — Audit & parity map.** Produce a source-by-source comparison of
|
||||
acdream `AcDream.Core.Net` and holtburger `holtburger-session`,
|
||||
`holtburger-protocol`, and `holtburger-core` networking code. Inventory each
|
||||
packet flag, optional header, session transition, control packet, fragment
|
||||
path, game message, and game action. Mark each as `parity`, `partial`,
|
||||
`missing`, or `intentional divergence`.
|
||||
- **M.2 — Layer extraction.** Split the low-level stack under `WorldSession`
|
||||
into testable components: `INetTransport`, `PacketCodec`,
|
||||
`ReliablePacketSession`, `FragmentSession`, `GameMessageSession`, and the
|
||||
high-level `WorldSession` behavior layer. Preserve existing public events and
|
||||
live-client call sites during the migration.
|
||||
- **M.3 — Reliability core.** Port holtburger-style sequence tracking:
|
||||
last-delivered server sequence, duplicate/old-packet suppression,
|
||||
out-of-order buffering, missing-sequence detection, throttled
|
||||
`RequestRetransmit`, outbound packet cache, server-requested C2S retransmit,
|
||||
`RejectRetransmit` handling, and retransmission checksum recomputation.
|
||||
- **M.4 — ACK and control-packet policy.** Replace standalone-only ACKs with
|
||||
queued ACK state, ACK piggybacking on normal outbound packets, standalone ACK
|
||||
flush when idle, and clean handling for ACK-only packets. Add EchoRequest /
|
||||
EchoResponse and idle ping/timeout behavior matching holtburger unless named
|
||||
retail proves a different cadence.
|
||||
- **M.5 — Fragment and payload completeness.** Keep inbound multi-fragment
|
||||
assembly, add TTL/eviction diagnostics for orphaned partials, implement
|
||||
outbound multi-fragment splitting when payloads exceed the current single
|
||||
fragment limit, and verify fragment id/sequence/queue behavior against
|
||||
holtburger, ACE, and retail evidence.
|
||||
- **M.6 — Typed protocol surface.** Introduce typed `GameMessage` and
|
||||
`GameAction` routing modeled on holtburger. Migrate current builders and
|
||||
parsers first: login complete, DDD, movement, chat/TurbineChat, combat,
|
||||
spellcast, item/appraise, object/update/motion/position, and teleport.
|
||||
Unknown opcodes must remain observable and non-fatal.
|
||||
- **M.7 — Runtime loop and diagnostics.** Move decode/order/reassembly/control
|
||||
handling out of the render tick into a dedicated network runtime that emits
|
||||
clean session events through channels. Add byte counters, packet trace hooks,
|
||||
optional capture/replay fixtures, idle/disconnect state, and dev-panel
|
||||
diagnostics suitable for packet debugging.
|
||||
- **M.8 — Conformance tests and live validation.** Add deterministic unit tests
|
||||
for checksum, ISAAC key consumption, optional headers, ordering, retransmit,
|
||||
ACK piggybacking, echo, fragments, typed actions, and login flow. Add
|
||||
replay/capture tests from holtburger-style fixtures where possible. Finish
|
||||
with `dotnet build`, `dotnet test`, local ACE login, chat, movement, combat
|
||||
action smoke test, reconnect test, and user visual sign-off where networking
|
||||
affects the running client.
|
||||
|
||||
**Non-goals:**
|
||||
- Do not reimplement ACE server behavior.
|
||||
- Do not replace acdream's stricter inbound checksum verification unless named
|
||||
retail proves it is wrong.
|
||||
- Do not rewrite renderer/gameplay systems as part of this phase; migrate
|
||||
network call sites through compatibility adapters first.
|
||||
- Do not remove unknown-message visibility. Plugins and devtools need packet
|
||||
trace surfaces even when parsers are incomplete.
|
||||
|
||||
**Acceptance:**
|
||||
- acdream has a layered, testable network stack rather than one monolithic
|
||||
`WorldSession`.
|
||||
- Every holtburger session capability has an acdream equivalent, an explicit
|
||||
test, or a documented intentional divergence with retail/ACE evidence.
|
||||
- Packet ordering, retransmit, outbound cache, ACK piggybacking, echo/keepalive,
|
||||
fragment assembly/splitting, and typed message/action routing are covered by
|
||||
tests.
|
||||
- Live ACE loop succeeds: login, enter world, movement, chat, combat action,
|
||||
teleport/reconnect, and clean logout.
|
||||
- `dotnet build` and `dotnet test` are green for every implementation slice.
|
||||
|
||||
---
|
||||
|
||||
### Phase J — Long-tail (deferred / low-priority)
|
||||
|
||||
Not detailed here; each gets its own brainstorm when it becomes relevant.
|
||||
|
|
@ -486,6 +581,12 @@ port in any phase — no separate listing here.
|
|||
| Can't walk past the loaded 3×3 window | **A.1 FIXED** ✓ (5×5 default, `ACDREAM_STREAM_RADIUS` to tune) |
|
||||
| Frame hitch crossing landblock boundary | **Phase A.3** (synchronous loader for now; async returns when DatCollection is thread-safe) |
|
||||
| Walking around doesn't move me on the server | **Phase B.2/B.3 FIXED** ✓ for coarse server movement; fine retail collision parity is **Phase L.2** |
|
||||
| Packet loss / out-of-order UDP causes stale or missing world updates | **Phase M.3** |
|
||||
| Server asks for retransmit and client doesn't resend cached packets | **Phase M.3** |
|
||||
| ACKs are standalone-only instead of piggybacked like a full client | **Phase M.4** |
|
||||
| Echo / idle keepalive / reconnect behavior is incomplete | **Phase M.4 + M.7** |
|
||||
| Large outbound game messages exceed the current single-fragment path | **Phase M.5** |
|
||||
| Network protocol coverage is spread across ad-hoc builders/parsers | **Phase M.6** |
|
||||
| Sliding along buildings / walls feels wrong | **Phase L.2c + L.2d** |
|
||||
| Roof edge / cliff / precipice blocks or slides wrong | **Phase L.2c** |
|
||||
| Crossing outdoor cell seams reports the wrong cell | **Phase L.2e** |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue