acdream/docs/research/deepdives/r08-network-protocol-atlas.md

# R8 — Network Protocol Atlas

**Scope:** exhaustive map of every AC retail network opcode the client must
see, send, or at least tolerate. This document is the single reference for
every port ticket under phases C, D, E (chat), and F (inventory/combat/
spells). If an opcode is listed here as "unhandled," we already know what
it is and what it needs — the only remaining work is wiring up the parser
+ event surface.

**Inputs cross-referenced:**

- `references/ACE/Source/ACE.Server/Network/GameMessages/GameMessageOpcode.cs`
  — canonical S2C primary-opcode enum.
- `references/ACE/Source/ACE.Server/Network/GameAction/GameActionType.cs`
  — canonical C2S GameAction sub-opcode enum.
- `references/ACE/Source/ACE.Server/Network/GameEvent/GameEventType.cs`
  — canonical S2C GameEvent sub-opcode enum.
- `references/ACE/Source/ACE.Server/Network/Handlers/*.cs` — handler
  implementations (what the server accepts, what fields it expects).
- `references/Chorizite.ACProtocol/Chorizite.ACProtocol/protocol.xml` —
  the authoritative XML generated from decompiled client stubs.
- `references/holtburger/crates/holtburger-protocol/src/opcodes.rs` —
  curated "what a real client actually sends / listens for" list, 829
  lines, with cross-validated comments.
- `docs/research/decompiled/chunk_006B0000.c` (confirmed 0xF7B0 switch).
- `src/AcDream.Core.Net/` — what acdream handles today.

**How to read the tables:**

- "Dir": `C→S` (client to server), `S→C` (server to client), or `bi` (can
  travel either direction — rare; mostly DDD and TurbineChat).
- "Envelope": `GM` = standalone GameMessage (primary opcode at the top of
  the body), `GA` = client-to-server GameAction inside the 0xF7B1 envelope,
  `GE` = server-to-client GameEvent inside the 0xF7B0 envelope. Login-
  phase opcodes use neither envelope (they ride on header flags).
- "Status": `done` = full parse/dispatch + event surface in acdream today;
  `partial` = parsed but not exposed as an event, or built but not
  generated by player input; `stub` = recognised opcode but body is
  ignored; `unhandled` = acdream does not parse this opcode at all today.
- "Prio": rank for minimum viable play. `P0` blocks login. `P1` blocks
  basic in-world feedback (chat, health, combat). `P2` blocks inventory/
  spells. `P3` is housing, allegiance, fellowship. `P4` is admin,
  minigames, barber.

---

## 1. Transport layer — recap

AC's wire stack is a three-layer stack on top of UDP:

```
UDP datagram
 ├─ 20-byte PacketHeader             src/AcDream.Core.Net/Packets/PacketHeader.cs
 ├─ N×MessageFragment                  (0..many, depending on header.Flags)
 │   ├─ 16-byte MessageFragmentHeader  src/AcDream.Core.Net/Packets/MessageFragmentHeader.cs
 │   └─ fragment payload               (≤448 bytes)
 └─ optional retransmit body (if Retransmission flag set)
```

### 1.1 PacketHeader (20 bytes, LE)

| Off | Name      | Type | Notes |
|----:|-----------|------|-------|
|   0 | Sequence  | u32  | Monotonic per direction. `0` = control/handshake packets. |
|   4 | Flags     | u32  | `PacketHeaderFlags` bitmask (see below). |
|   8 | Checksum  | u32  | Hash32 of header+body with this field replaced by `0xBADD70DD`. When `EncryptedChecksum` flag is set, XOR with one 32-bit word of ISAAC keystream before transmit. |
|  12 | Id        | u16  | Session id, assigned in ConnectRequest by the server. |
|  14 | Time      | u16  | Server-time echo for latency tracking. Clients may send 0. |
|  16 | DataSize  | u16  | Total body size (excludes this 20-byte header). |
|  18 | Iteration | u16  | Retransmit iteration counter. |

### 1.2 PacketHeaderFlags (32-bit bitmask, wire source of truth)

| Value | Name | Meaning |
|------:|------|---------|
| 0x00000001 | Retransmission | Body starts with one u32 retransmit-sequence, then the original body. |
| 0x00000002 | EncryptedChecksum | The Checksum field has been XOR'd with the next ISAAC keystream word. |
| 0x00000004 | BlobFragments | Body contains one or more MessageFragment blocks. |
| 0x00000100 | ServerSwitch | Optional body prefix: `u32 ServerSwitchType` (0=World, 1=Logon). |
| 0x00000200 | LogonServerAddr | Body prefix: a sockaddr blob (u16 family, u16 port, u32 IPv4, 8 bytes padding). |
| 0x00000400 | EmptyHeader1 | Observed rarely; legacy. |
| 0x00000800 | Referral | Body prefix: u64 cookie steering the client to another server. |
| 0x00001000 | RequestRetransmit | Body: u32 count + count×u32 sequences to retransmit. |
| 0x00002000 | RejectRetransmit | Body: u32 count + count×u32 rejected sequences. |
| 0x00004000 | AckSequence | Body: u32 highest-sequence-received. |
| 0x00008000 | Disconnect | No body; teardown. |
| 0x00010000 | LoginRequest | Body is the LoginRequest blob. |
| 0x00020000 | WorldLoginRequest | (unused today, pre-live legacy.) |
| 0x00040000 | ConnectRequest | Body: `double serverTime, u64 cookie, u32 clientId, u32 serverSeed, u32 clientSeed, u32 padding`. |
| 0x00080000 | ConnectResponse | Body: `u64 cookie` (echo). |
| 0x00100000 | NetError | Body: `u32 errorCode`. |
| 0x00200000 | NetErrorDisconnect | Body: `u32 errorCode, u32 reason` + disconnect. |
| 0x00400000 | CICMDCommand | Legacy admin control channel. |
| 0x01000000 | TimeSync | Body: `double clientTime`. |
| 0x02000000 | EchoRequest | Body: `float clientTime`. |
| 0x04000000 | EchoResponse | Body: `float clientTime, float serverTime`. |
| 0x08000000 | Flow | Body: `u32 bytesSinceLast, u16 delta, u16 pad` — TCP-style flow control. |

### 1.3 MessageFragmentHeader (16 bytes, LE)

| Off | Name      | Type | Notes |
|----:|-----------|------|-------|
|   0 | Sequence  | u32  | Per-message sequence. Outbound messages set the high bit (`0x80000000`). |
|   4 | Id        | u32  | Logical message id — fragments with the same Id belong to the same logical GameMessage. |
|   8 | Count     | u16  | Total fragments in this logical message. |
|  10 | TotalSize | u16  | Total bytes of this fragment **including** the 16-byte header. Max 464. |
|  12 | Index     | u16  | 0-based index of this fragment in the logical message. |
|  14 | Queue     | u16  | `GameMessageGroup` — `Event=1, Control=2, Weenie=3, Logon=4, Database=5, UIQueue=9, SmartBox=10`, etc. |

### 1.4 ISAAC encryption

Each direction has its own `IsaacRandom` (ported in `Cryptography/`),
seeded from the 4-byte server seed (for the inbound stream) and 4-byte
client seed (for the outbound stream) that the server returns in the
ConnectRequest handshake. Every packet with `EncryptedChecksum` set
XORs the header Checksum field with the next u32 drawn from that
direction's ISAAC keystream. Cleartext control packets (ACKs, login,
connect response, disconnect) do NOT advance ISAAC.

### 1.5 Ack protocol (source: holtburger `session/receive.rs`)

**Every** received server packet whose `Sequence > 0` and that does NOT
already carry the `AckSequence` flag gets exactly one ack queued back.
This is the "eager ack" pattern — there is no periodic ack timer in the
retail client. The ack packet is:

```
PacketHeader {
  Sequence = last client sequence sent (no increment),
  Flags    = AckSequence,
  Id       = session id,
}
body = u32 server_sequence_being_acked   // cleartext — no ISAAC
```

Failing to ack → ACE emits "Network Timeout" after ~60s. Symptom visible
to other clients: character appears as a stationary purple loading haze.

### 1.6 Sequence counters (four flavours, movement-only)

Separate from the packet-level Sequence, a player carries four u16
sequence counters that the server uses to detect stale/out-of-order
movement messages. These live on `WorldSession` as
`_instanceSequence`, `_teleportSequence`, `_serverControlSequence`,
`_forcePositionSequence`. They're seeded from the player's own
CreateObject and updated whenever an inbound UpdatePosition or
PlayerTeleport arrives. Every outbound MoveToState / AutonomousPosition
must echo them or ACE silently rejects the message.

---

## 2. GameMessage opcodes (S→C primary)

These ride as standalone messages — the first u32 of the fragment body
is the opcode itself, followed immediately by the payload.

| Hex | Name | Envelope | Dir | Status | Prio | Notes |
|----:|------|:--------:|:---:|:------:|:----:|-------|
| 0x0024 | InventoryRemoveObject | GM | S→C | unhandled | P2 | `u32 guid` — client-side inventory eviction. |
| 0x0197 | SetStackSize | GM | S→C | unhandled | P2 | `u32 guid, u32 newStackSize`. |
| 0x019E | PlayerKilled | GM | S→C | unhandled | P1 | `u32 victimGuid, u32 killerGuid, string message`. Triggers the dead-player state. |
| 0x01E0 | EmoteText | GM | S→C | unhandled | P1 | `string message` — "The Olthoi growls at you." class feedback. |
| 0x01E2 | SoulEmote | GM | S→C | unhandled | P3 | `u32 senderGuid, u32 motion, string text`. |
| 0x02BB | HearSpeech | GM | S→C | unhandled | P1 | `string16L text, string16L sender, u32 senderGuid, u32 chatType`. Local-area speech. |
| 0x02BC | HearRangedSpeech | GM | S→C | unhandled | P1 | Same layout as HearSpeech but longer radius (shouts). |
| 0x02CD | PrivateUpdatePropertyInt | GM | S→C | unhandled | P1 | `u32 guid, u32 propertyId, u32 value` — Only sent to the object's owner. |
| 0x02CE | PublicUpdatePropertyInt | GM | S→C | unhandled | P1 | Same as above; sent to everyone who sees the object. |
| 0x02CF / 0x02D0 | Private/PublicUpdatePropertyInt64 | GM | S→C | unhandled | P1 | `u32 guid, u32 propId, u64 value`. |
| 0x02D1 / 0x02D2 | Private/PublicUpdatePropertyBool | GM | S→C | unhandled | P1 | `u32 guid, u32 propId, u32 value`. |
| 0x02D3 / 0x02D4 | Private/PublicUpdatePropertyFloat | GM | S→C | unhandled | P1 | `u32 guid, u32 propId, f64 value`. |
| 0x02D5 / 0x02D6 | Private/PublicUpdatePropertyString | GM | S→C | unhandled | P1 | `u32 guid, u32 propId, string16L value`. |
| 0x02D7 / 0x02D8 | Private/PublicUpdatePropertyDataID | GM | S→C | unhandled | P2 | `u32 guid, u32 propId, u32 dataId`. |
| 0x02D9 / 0x02DA | Private/PublicUpdatePropertyInstanceID | GM | S→C | unhandled | P2 | `u32 guid, u32 propId, u32 iid`. |
| 0x02DB / 0x02DC | Private/PublicUpdatePosition | GM | S→C | unhandled | P2 | `u32 guid, u32 propId, PositionPack`. |
| 0x02DD / 0x02DE | Private/PublicUpdateSkill | GM | S→C | unhandled | P2 | `u32 guid, u32 skillId, SkillValue`. |
| 0x02DF / 0x02E0 | Private/PublicUpdateSkillLevel | GM | S→C | unhandled | P2 | Skill-level only. |
| 0x02E3 / 0x02E4 | Private/PublicUpdateAttribute | GM | S→C | unhandled | P1 | Strength/Endurance/etc. |
| 0x02E7 / 0x02E8 | Private/PublicUpdateVital | GM | S→C | unhandled | P1 | Max HP/Stam/Mana + regen. |
| 0x02E9 | PrivateUpdateAttribute2ndLevel | GM | S→C | unhandled | P1 | Current vital value (the fast-tick channel). |
| 0xEA60 | AdminEnvirons | GM | S→C | unhandled | P4 | Admin-tool overlay. |
| 0xF619 | PositionAndMovement | GM | S→C | unhandled | P4 | Ghost opcode — declared but never fired by ACE. |
| 0xF625 | ObjDescEvent | GM | S→C | unhandled | P1 | `u32 guid, ObjectDescription` — full re-send of visual description (body parts, textures, palettes). Critical for seeing other players' gear changes. |
| 0xF643 | CharacterCreateResponse / CharacterRestoreResponse | GM | S→C | unhandled | P0+ | `u32 responseCode` — login-phase, only relevant after char-create. Same opcode, two semantics (disambiguated by session state). |
| 0xF653 | CharacterLogOff | GM | bi | partial | P0 | No payload. Client sends before Disconnect to release the character lock immediately. acdream sends it from `Dispose`. |
| 0xF655 | CharacterDelete | GM | bi | unhandled | P4 | `u32 slot` — char-select-screen deletion. |
| 0xF656 | CharacterCreate | GM | C→S | unhandled | P4 | Full character-creation blob — heritage, gender, starting town, appearance. |
| 0xF657 | CharacterEnterWorld | GM | C→S | done | P0 | `u32 characterGuid, string16L account`. Built by `Messages/CharacterEnterWorld.cs`. |
| 0xF658 | CharacterList | GM | S→C | done | P0 | `u32 serverName?, u32 numChars, char[] chars, u32 accountSlots, u32 accountGuid`. Parsed in `Messages/CharacterList.cs`. |
| 0xF659 | CharacterError | GM | S→C | unhandled | P0 | `u32 errorCode` — login failure enum. We should parse this to give the user a real error instead of a timeout. |
| 0xF6EA | ForceObjectDescSend | GM | bi | unhandled | P2 | `u32 guid`. Both directions use the same opcode; C→S asks the server to re-send, S→C pushes a forced refresh. |
| **0xF745** | **CreateObject** | GM | S→C | done | P0 | Parser: `Messages/CreateObject.cs` (538 lines). Layout: `u32 guid, WeenieHeader, ObjectDescription, PhysicsData`. Emits `EntitySpawned` event. |
| 0xF746 | PlayerCreate | GM | S→C | partial | P0 | Identifies our own character guid. acdream watches for this to send LoginComplete. Does NOT parse the body (it's a full CreateObject-shaped payload — we rely on 0xF745 for that to arrive separately, though retail bundles both). |
| 0xF747 | ObjectDelete | GM | S→C | unhandled | P1 | `u32 guid, u16 instanceSequence`. When an object leaves our bubble or is destroyed. Without handling this, stale entities accumulate forever. |
| **0xF748** | **UpdatePosition** | GM | S→C | done | P0 | Parser: `Messages/UpdatePosition.cs`. Emits `PositionUpdated` event. |
| 0xF749 | ParentEvent | GM | S→C | unhandled | P1 | `u32 parentGuid, u32 childGuid, u32 equipLocation, u32 placementId` — item equipped / child attached. Needed to draw weapons in hands, clothing over armour. |
| 0xF74A | PickupEvent | GM | S→C | unhandled | P2 | `u32 guid, u32 animationType` — player picks up an item, animation dispatched. |
| 0xF74B | SetState | GM | S→C | unhandled | P1 | `u32 guid, u32 physicsState, u16 instanceSeq, u16 stateSeq` — door opens, chest unlocks, visibility flips. |
| **0xF74C** | **UpdateMotion / MovementEvent** | GM | S→C | done | P0 | Parser: `Messages/UpdateMotion.cs`. Emits `MotionUpdated` event. Two names are the same opcode — ACE aliases. |
| 0xF74E | VectorUpdate | GM | S→C | unhandled | P1 | `u32 guid, f32 vx, f32 vy, f32 vz, f32 avx, f32 avy, f32 avz, u16 seq, u16 pad` — velocity + angular velocity. Missile tracking, continuous turns. |
| 0xF750 | Sound | GM | S→C | unhandled | P2 | `u32 guid, u32 soundId, f32 volume` — spatialised SFX trigger. |
| **0xF751** | **PlayerTeleport** | GM | S→C | done | P0 | Parser inline in `WorldSession.cs`. Emits `TeleportStarted` with `u16 teleportSequence`. |
| 0xF752 | AutonomyLevel | GM | S→C | unhandled | P1 | `u32 autonomyLevel` — server tells client how much physics trust to grant. Default 0 = full client sim; higher = server authoritative. |
| 0xF753 | AutonomousPosition | GM | S→C | unhandled | P1 | Server-forced position resync. Same body as C→S AutonomousPosition (see §3). Causes a snap. |
| 0xF754 | PlayScriptId | GM | S→C | unhandled | P2 | `u32 guid, u32 scriptId` — trigger a pre-compiled script effect. |
| 0xF755 | PlayEffect / PlayScriptType | GM | S→C | unhandled | P2 | `u32 guid, u32 effectType, f32 scale` — particle/visual overlay. |
| **0xF7B0** | **GameEvent** | GM | S→C | unhandled | P1 | The container for every "ordered" server event. Sub-opcode table in §4. |
| **0xF7B1** | **GameAction** | GM | C→S | done (partial) | P0 | acdream builds LoginComplete, MoveToState, AutonomousPosition, Jump. Sub-opcode table in §3. |
| 0xF7C1 | AccountBanned | GM | S→C | unhandled | P4 | `u32 bannedUntilUnixTime, string16L reason`. |
| 0xF7C8 | CharacterEnterWorldRequest | GM | C→S | done | P0 | Built by `Messages/CharacterEnterWorld.cs::BuildEnterWorldRequestBody`. No payload. |
| 0xF7C9 | JumpNonAutonomous | GM | bi | unhandled | P4 | Server-side legacy jump; not sent by live ACE. |
| 0xF7CA | ReceiveAccountData | GM | S→C | unhandled | P4 | Admin inspection. |
| 0xF7CB | ReceivePlayerData | GM | S→C | unhandled | P4 | Admin inspection. |
| 0xF7CC | GetServerVersion | GM | C→S | unhandled | P4 | Admin-only. |
| 0xF7CD | FriendsOld | GM | C→S | unhandled | P4 | Obsolete. |
| 0xF7D9 | CharacterRestore | GM | C→S | unhandled | P4 | Restore a deleted character within grace period. |
| 0xF7DB | UpdateObject | GM | S→C | unhandled | P1 | Heavy update — re-serializes the complete WorldObject. Used on gear swaps, morphs, level-ups. |
| 0xF7DC | AccountBoot / AccountBooted | GM | S→C | unhandled | P1 | `string16L reason` — server-initiated kick. Should transition to Failed state. |
| 0xF7DE | TurbineChat | GM | bi | unhandled | P1 | Turbine's social chat (General/Trade/LFG/Allegiance/Society). Complex nested blob, see §7.4. |
| 0xF7DF | CharacterEnterWorldServerReady | GM | S→C | done | P0 | No payload. acdream awaits it in EnterWorld as an ack that the server got our request. |
| 0xF7E0 | ServerMessage / TextboxString | GM | S→C | unhandled | P1 | `string16L text, u32 chatType`. System chat line in the main log. |
| 0xF7E1 | ServerName / WorldInfo | GM | S→C | unhandled | P0 | `u32 currentConnections, u32 maxConnections, string16L serverName`. Displayed on char-select. |
| 0xF7E2 | DDD_DataMessage | GM | bi | unhandled | P4 | Patch-stream file chunk — only triggers when dat versions mismatch. |
| 0xF7E3 | DDD_RequestDataMessage | GM | C→S | unhandled | P4 | `u32 fileType, u32 fileId` — client asks for a file. |
| 0xF7E4 | DDD_ErrorMessage | GM | S→C | unhandled | P4 | `u32 fileType, u32 fileId, u32 errorCode`. |
| **0xF7E5** | **DDD_Interrogation** | GM | S→C | done | P0 | No payload beyond opcode. Server asks "what dat versions do you have?" |
| **0xF7E6** | **DDD_InterrogationResponse** | GM | C→S | done | P0 | Built by `Messages/DddInterrogationResponse.cs` — reports language=1 English, zero known lists. |
| 0xF7E7 | DDD_BeginDDD | GM | S→C | unhandled | P4 | Server tells client patching will begin; `u32 totalIterations, u64 totalBytes, ...`. |
| 0xF7E8 | DDD_BeginPullDDD | GM | S→C | unhandled | P4 | Alternative patch entry. |
| 0xF7E9 | DDD_IterationData | GM | S→C | unhandled | P4 | One iteration record during patching. |
| 0xF7EA | DDD_EndDDD | GM | bi | unhandled | P4 | Patching finished / client acknowledges. |

**Total primary S→C opcodes:** 63. **Currently handled by acdream:** 7
(CharacterList, CharacterEnterWorldServerReady, CreateObject,
UpdateMotion, UpdatePosition, PlayerTeleport, DDD_Interrogation) plus
the PlayerCreate trigger. **Unhandled:** 56 — many of them property
updates that share a single parser.

---

## 3. GameAction sub-opcodes (C→S, inside 0xF7B1 envelope)

Wire layout of every GameAction on the outbound side:

```
u32 0xF7B1                          // GameMessage opcode (GameAction envelope)
u32 sequence                        // monotonic per-session action counter
u32 actionType                      // one of the values below
<payload bytes>                     // variable
```

ACE's `GameActionPacket.HandleGameAction` reads the sequence field and
ignores its value (`// TODO: verify sequence` in the source), but live
clients still increment it — acdream does too via
`WorldSession.NextGameActionSequence()`.

| Hex | Name | Dir | Status | Prio | Payload |
|----:|------|:---:|:------:|:----:|---------|
| 0x0005 | SetSingleCharacterOption | C→S | unhandled | P3 | `u32 optionKey, u32 value`. Appear-offline, show-cloak, etc. |
| 0x0008 | TargetedMeleeAttack | C→S | unhandled | P1 | `u32 targetGuid, u32 attackHeight, f32 powerLevel`. |
| 0x000A | TargetedMissileAttack | C→S | unhandled | P2 | `u32 targetGuid, u32 attackHeight, f32 accuracyLevel`. |
| 0x000F | SetAfkMode | C→S | unhandled | P3 | `u32 enabled`. |
| 0x0010 | SetAfkMessage | C→S | unhandled | P3 | `string16L message`. |
| 0x0015 | Talk | C→S | unhandled | P1 | `string16L message` — local-area chat. |
| 0x0017 | RemoveFriend | C→S | unhandled | P3 | `u32 guid`. |
| 0x0018 | AddFriend | C→S | unhandled | P3 | `string16L name`. |
| 0x0019 | PutItemInContainer | C→S | unhandled | P2 | `u32 itemGuid, u32 containerGuid, u32 placement`. |
| 0x001A | GetAndWieldItem | C→S | unhandled | P2 | `u32 itemGuid, u32 equipLocation`. |
| 0x001B | DropItem | C→S | unhandled | P2 | `u32 itemGuid`. |
| 0x001D | SwearAllegiance | C→S | unhandled | P3 | `u32 patronGuid`. |
| 0x001E | BreakAllegiance | C→S | unhandled | P3 | `u32 otherGuid`. |
| 0x001F | AllegianceUpdateRequest | C→S | unhandled | P3 | `u32 onOff`. |
| 0x0025 | RemoveAllFriends | C→S | unhandled | P3 | — |
| 0x0026 | TeleToPklArena | C→S | unhandled | P3 | — |
| 0x0027 | TeleToPkArena | C→S | unhandled | P3 | — |
| 0x002C | TitleSet | C→S | unhandled | P3 | `u32 titleId`. |
| 0x0030 | QueryAllegianceName | C→S | unhandled | P3 | — |
| 0x0031 | ClearAllegianceName | C→S | unhandled | P3 | — |
| 0x0032 | TalkDirect | C→S | unhandled | P1 | `string16L target, string16L message` — whisper by location/target. |
| 0x0033 | SetAllegianceName | C→S | unhandled | P3 | `string16L name`. |
| 0x0035 | UseWithTarget | C→S | unhandled | P2 | `u32 sourceGuid, u32 targetGuid`. |
| 0x0036 | Use | C→S | unhandled | P2 | `u32 guid` — click a door, Lifestone, portal, corpse, etc. |
| 0x003B–0x0042 | Allegiance officer/chat/house | C→S | unhandled | P3 | Various allegiance admin ops. |
| 0x0044 | RaiseVital | C→S | unhandled | P2 | `u32 vital, u64 xpSpent`. |
| 0x0045 | RaiseAttribute | C→S | unhandled | P2 | `u32 attr, u64 xpSpent`. |
| 0x0046 | RaiseSkill | C→S | unhandled | P2 | `u32 skillId, u64 xpSpent`. |
| 0x0047 | TrainSkill | C→S | unhandled | P2 | `u32 skillId, u32 credits`. |
| 0x0048 | CastUntargetedSpell | C→S | unhandled | P2 | `u32 spellId`. |
| 0x004A | CastTargetedSpell | C→S | unhandled | P2 | `u32 targetGuid, u32 spellId`. |
| 0x0053 | ChangeCombatMode | C→S | unhandled | P1 | `u32 combatMode` — Peace/Melee/Missile/Magic. |
| 0x0054 | StackableMerge | C→S | unhandled | P2 | `u32 mergeFromGuid, u32 mergeToGuid, u32 amount`. |
| 0x0055 | StackableSplitToContainer | C→S | unhandled | P2 | `u32 stackGuid, u32 containerGuid, u32 placement, u32 amount`. |
| 0x0056 | StackableSplitTo3D | C→S | unhandled | P2 | `u32 stackGuid, u32 amount`. |
| 0x0058 | ModifyCharacterSquelch | C→S | unhandled | P3 | `u32 guid, u32 squelchType, bool add`. |
| 0x0059 | ModifyAccountSquelch | C→S | unhandled | P3 | `string16L account, u32 squelchType, bool add`. |
| 0x005B | ModifyGlobalSquelch | C→S | unhandled | P3 | `u32 channelId, bool enable`. |
| 0x005D | Tell | C→S | unhandled | P1 | `string16L targetName, string16L message` — whisper by name. |
| 0x005F | Buy | C→S | unhandled | P2 | `u32 vendorGuid, u32 count, ItemProfile[count]`. |
| 0x0060 | Sell | C→S | unhandled | P2 | Same shape. |
| 0x0063 | TeleToLifestone | C→S | unhandled | P2 | — |
| **0x00A1** | **LoginComplete** | C→S | done | P0 | No payload. Built by `Messages/GameActionLoginComplete.cs`. |
| 0x00A2 | FellowshipCreate | C→S | unhandled | P3 | `string16L name, bool openness, bool shareXP`. |
| 0x00A3 | FellowshipQuit | C→S | unhandled | P3 | `bool disband`. |
| 0x00A4 | FellowshipDismiss | C→S | unhandled | P3 | `u32 guid`. |
| 0x00A5 | FellowshipRecruit | C→S | unhandled | P3 | `u32 guid`. |
| 0x00A6 | FellowshipUpdateRequest | C→S | unhandled | P3 | `bool open`. |
| 0x00AA–0x00AE | Book* | C→S | unhandled | P4 | Book add/modify/delete/query pages. |
| 0x00BF | SetInscription | C→S | unhandled | P3 | `u32 itemGuid, string16L text`. |
| 0x00C8 | IdentifyObject | C→S | unhandled | P1 | `u32 guid`. Assess target; server replies with 0xF7B0/0x00C9. |
| 0x00CD | GiveObjectRequest | C→S | unhandled | P2 | `u32 targetGuid, u32 itemGuid, u32 amount`. |
| 0x00D6 | AdvocateTeleport | C→S | unhandled | P4 | Admin. |
| 0x0140 | AbuseLogRequest | C→S | unhandled | P4 | — |
| 0x0145 | AddChannel | C→S | unhandled | P3 | `string16L channelName`. |
| 0x0146 | RemoveChannel | C→S | unhandled | P3 | `string16L channelName`. |
| 0x0147 | ChatChannel | C→S | unhandled | P1 | `u32 channelId, string16L message`. |
| 0x0148 | ListChannels | C→S | unhandled | P3 | — |
| 0x0149 | IndexChannels | C→S | unhandled | P3 | — |
| 0x0195 | NoLongerViewingContents | C→S | unhandled | P2 | `u32 containerGuid`. |
| 0x019B | StackableSplitToWield | C→S | unhandled | P2 | `u32 stackGuid, u32 equipLocation, u32 amount`. |
| 0x019C | AddShortCut | C→S | unhandled | P3 | `u32 slot, u32 objectType, u32 targetId`. |
| 0x019D | RemoveShortCut | C→S | unhandled | P3 | `u32 slot`. |
| 0x01A1 | SetCharacterOptions | C→S | unhandled | P3 | Client option bitmap. |
| 0x01A8 | RemoveSpellC2S | C→S | unhandled | P2 | `u32 spellId`. |
| 0x01B7 | CancelAttack | C→S | unhandled | P1 | — |
| 0x01BF | QueryHealth | C→S | unhandled | P1 | `u32 guid`. Server replies with GameEvent UpdateHealth (0x01C0). |
| 0x01C2 | QueryAge | C→S | unhandled | P4 | — |
| 0x01C4 | QueryBirth | C→S | unhandled | P4 | — |
| 0x01DF | Emote | C→S | unhandled | P2 | `string16L emote`. |
| 0x01E1 | SoulEmote | C→S | unhandled | P3 | `string16L emote`. |
| 0x01E3 | AddSpellFavorite | C→S | unhandled | P3 | `u32 spellId, u32 bar, u32 slot`. |
| 0x01E4 | RemoveSpellFavorite | C→S | unhandled | P3 | `u32 bar, u32 slot`. |
| 0x01E9 | PingRequest | C→S | unhandled | P1 | `u32 clientId`. Server replies with 0xF7B0/0x01EA. Double-duty keepalive. |
| 0x01F6 | OpenTradeNegotiations | C→S | unhandled | P3 | `u32 targetGuid`. |
| 0x01F7 | CloseTradeNegotiations | C→S | unhandled | P3 | — |
| 0x01F8 | AddToTrade | C→S | unhandled | P3 | `u32 itemGuid, u32 slotIndex`. |
| 0x01FA | AcceptTrade | C→S | unhandled | P3 | — |
| 0x01FB | DeclineTrade | C→S | unhandled | P3 | — |
| 0x0204 | ResetTrade | C→S | unhandled | P3 | — |
| 0x0216 | ClearPlayerConsentList | C→S | unhandled | P4 | — |
| 0x0217 | DisplayPlayerConsentList | C→S | unhandled | P4 | — |
| 0x0218 | RemoveFromPlayerConsentList | C→S | unhandled | P4 | `u32 guid`. |
| 0x0219 | AddPlayerPermission | C→S | unhandled | P4 | `u32 guid`. |
| 0x021A | RemovePlayerPermission | C→S | unhandled | P4 | `u32 guid`. |
| 0x021C | BuyHouse | C→S | unhandled | P3 | `u32 slumlordGuid, PackableListU32 allegianceHouseIds`. |
| 0x021E | HouseQuery | C→S | unhandled | P3 | `u32 houseGuid`. |
| 0x021F | AbandonHouse | C→S | unhandled | P3 | — |
| 0x0221 | RentHouse | C→S | unhandled | P3 | `u32 houseGuid, PackableListU32 itemIds`. |
| 0x0224 | SetDesiredComponentLevel | C→S | unhandled | P3 | `u32 level`. |
| 0x0245 | AddPermanentGuest | C→S | unhandled | P3 | `string16L name`. |
| 0x0246 | RemovePermanentGuest | C→S | unhandled | P3 | `string16L name`. |
| 0x0247 | SetOpenHouseStatus | C→S | unhandled | P3 | `bool open`. |
| 0x0249 | ChangeStoragePermission | C→S | unhandled | P3 | — |
| 0x024A | BootSpecificHouseGuest | C→S | unhandled | P3 | `string16L name`. |
| 0x024C | RemoveAllStoragePermission | C→S | unhandled | P3 | — |
| 0x024D | RequestFullGuestList | C→S | unhandled | P3 | — |
| 0x0254–0x0256 | Allegiance MOTD | C→S | unhandled | P3 | — |
| 0x0258 | QueryLord | C→S | unhandled | P3 | — |
| 0x025C | AddAllStoragePermission | C→S | unhandled | P3 | — |
| 0x025E | RemoveAllPermanentGuests | C→S | unhandled | P3 | — |
| 0x025F | BootEveryone | C→S | unhandled | P3 | — |
| 0x0262 | TeleToHouse | C→S | unhandled | P3 | — |
| 0x0263 | QueryItemMana | C→S | unhandled | P2 | `u32 guid`. |
| 0x0266 | SetHooksVisibility | C→S | unhandled | P3 | `bool visible`. |
| 0x0267 | ModifyAllegianceGuestPermission | C→S | unhandled | P3 | — |
| 0x0268 | ModifyAllegianceStoragePermission | C→S | unhandled | P3 | — |
| 0x0269–0x026E | Chess | C→S | unhandled | P4 | Chess minigame. |
| 0x0270 | ListAvailableHouses | C→S | unhandled | P3 | — |
| 0x0275 | ConfirmationResponse | C→S | unhandled | P2 | `u32 confirmationType, u32 contextId, bool accepted`. |
| 0x0277 | BreakAllegianceBoot | C→S | unhandled | P3 | `u32 otherGuid, bool accountBoot`. |
| 0x0278 | TeleToMansion | C→S | unhandled | P3 | — |
| 0x0279 | Suicide | C→S | unhandled | P3 | — |
| 0x027B | AllegianceInfoRequest | C→S | unhandled | P3 | `string16L name`. |
| 0x027D | CreateTinkeringTool | C→S | unhandled | P2 | `u32 ustGuid, u32 targetGuid`. Salvage-items-with. |
| 0x0286 | SpellbookFilter | C→S | unhandled | P3 | Filter bitmap. |
| 0x028D | TeleToMarketPlace | C→S | unhandled | P2 | — |
| 0x028F | EnterPkLite | C→S | unhandled | P3 | — |
| 0x0290 | FellowshipAssignNewLeader | C→S | unhandled | P3 | `u32 guid`. |
| 0x0291 | FellowshipChangeOpenness | C→S | unhandled | P3 | `bool open`. |
| 0x02A0–0x02A7, 0x02AB | Allegiance admin | C→S | unhandled | P3 | Chat boot / bans / officers. |
| 0x02AF, 0x02B2 | Admin plugin query responses | C→S | unhandled | P4 | — |
| 0x0311 | FinishBarber | C→S | unhandled | P3 | Full barber blob. |
| 0x0316 | AbandonContract | C→S | unhandled | P3 | `u32 contractId`. |
| **0xF61B** | **Jump** | C→S | done (partial) | P0 | Built by `Messages/JumpAction.cs`. Payload: `f32 extent, Vector3 jumpVelocity` + position/sequences. |
| **0xF61C** | **MoveToState** | C→S | done | P0 | Built by `Messages/MoveToState.cs`. Full RawMotionState + WorldPosition + 4 u16 sequences + contact byte. |
| 0xF61E | DoMovementCommand | C→S | unhandled | P4 | Legacy — live client doesn't use this path. |
| 0xF649 | TurnTo | C→S | unhandled | P4 | Legacy — unused. |
| 0xF661 | StopMovementCommand | C→S | unhandled | P4 | Legacy. |
| 0xF6EA | ForceObjectDescSend | C→S | unhandled | P2 | `u32 guid` — ask server to re-emit ObjDescEvent for this entity. Useful for reloading avatar appearance. |
| 0xF745 | ObjectCreate | C→S | unhandled | P4 | Legacy admin spawn. |
| 0xF747 | ObjectDelete | C→S | unhandled | P4 | Legacy admin despawn. |
| 0xF74C | MovementEvent | C→S | unhandled | P4 | Legacy. |
| 0xF750 | ApplySoundEffect | C→S | unhandled | P4 | Admin. |
| 0xF752 | AutonomyLevel | C→S | unhandled | P2 | `u32 level` — ack the server's autonomy level. |
| **0xF753** | **AutonomousPosition** | C→S | done | P0 | Built by `Messages/AutonomousPosition.cs`. Same body as MoveToState but without the motion command list. Heartbeat every ~200ms while moving. |
| 0xF755 | ApplyVisualEffect | C→S | unhandled | P4 | Admin. |
| 0xF7C9 | JumpNonAutonomous | C→S | unhandled | P4 | Server-controlled jump — client never sends. |

**Total GameAction C→S opcodes:** 149. **Currently handled:** 4
(LoginComplete, MoveToState, Jump, AutonomousPosition). **Unhandled:**
145 — but the vast majority are P3/P4 and unblocking only requires 5-8
P1/P2 adds (ChatChannel, Talk, Tell, Use, UseWithTarget, IdentifyObject,
QueryHealth, ChangeCombatMode, CastTargetedSpell,
CastUntargetedSpell, TargetedMeleeAttack, TargetedMissileAttack,
CancelAttack, PingRequest).

---

## 4. GameEvent sub-opcodes (S→C, inside 0xF7B0 envelope)

Wire layout of every GameEvent on the inbound side (source:
`references/ACE/Source/ACE.Server/Network/GameEvent/GameEventMessage.cs`):

```
u32 0xF7B0                          // GameMessage opcode (GameEvent envelope)
u32 guid                            // session's player guid (0 if session has no player yet)
u32 gameEventSequence               // per-session, incremented by server
u32 eventType                       // one of the values below
<payload bytes>                     // variable
```

| Hex | Name | Dir | Status | Prio | Payload |
|----:|------|:---:|:------:|:----:|---------|
| 0x0003 | AllegianceUpdateAborted | S→C | unhandled | P3 | — |
| 0x0004 | PopupString | S→C | unhandled | P1 | `string16L message` — modal dialog. |
| 0x0013 | PlayerDescription | S→C | unhandled | P0 | Large blob — full player stats, skills, attributes, vitals, spellbook, inventory, equipment, titles, contracts. Sent right after LoginComplete. Parsing this is the gate to everything UI. |
| 0x0020 | AllegianceUpdate | S→C | unhandled | P3 | Allegiance hierarchy delta. |
| 0x0021 | FriendsListUpdate | S→C | unhandled | P3 | `u32 listType, u32 count, FriendEntry[count]`. |
| 0x0022 | InventoryPutObjInContainer | S→C | unhandled | P2 | `u32 itemGuid, u32 containerGuid, u32 placement`. |
| 0x0023 | WieldObject | S→C | unhandled | P1 | `u32 guid, u32 equipLoc, u32 wielderGuid`. |
| 0x0029 | CharacterTitle | S→C | unhandled | P3 | — |
| 0x002B | UpdateTitle | S→C | unhandled | P3 | `u32 newTitleId`. |
| 0x0052 | CloseGroundContainer | S→C | unhandled | P2 | `u32 containerGuid`. |
| 0x0062 | ApproachVendor / VendorInfoEvent | S→C | unhandled | P2 | Vendor inventory blob — item list, buy/sell rates. |
| 0x0075 | StartBarber | S→C | unhandled | P3 | Barber UI trigger. |
| 0x00A0 | InventoryServerSaveFailed | S→C | unhandled | P2 | `u32 guid` — revert a local inventory op. |
| 0x00A3 | FellowshipQuit | S→C | unhandled | P3 | Echo. |
| 0x00A4 | FellowshipDismiss | S→C | unhandled | P3 | Echo. |
| 0x00B4 | BookDataResponse | S→C | unhandled | P4 | Book header + inline pages. |
| 0x00B5 | BookModifyPageResponse | S→C | unhandled | P4 | — |
| 0x00B6 | BookAddPageResponse | S→C | unhandled | P4 | — |
| 0x00B7 | BookDeletePageResponse | S→C | unhandled | P4 | — |
| 0x00B8 | BookPageDataResponse | S→C | unhandled | P4 | Text of a single page. |
| 0x00C3 | IdentifyObject/GetInscriptionResponse | S→C | unhandled | P3 | `u32 guid, string16L text`. |
| 0x00C9 | IdentifyObjectResponse | S→C | unhandled | P1 | Full AppraiseInfo — properties tables keyed by enum. Essential for target info UI. |
| 0x0147 | ChannelBroadcast | S→C | unhandled | P1 | `u32 channelId, string16L senderName, string16L message`. |
| 0x0148 | ChannelList | S→C | unhandled | P3 | `u32 count, string16L[count] names`. |
| 0x0149 | ChannelIndex | S→C | unhandled | P3 | — |
| 0x0196 | ViewContents | S→C | unhandled | P2 | `u32 containerGuid, u32 count, (u32 guid, u32 slot)[count]`. |
| 0x019A | InventoryPutObjectIn3D | S→C | unhandled | P2 | `u32 guid` — item appears on the ground. |
| 0x01A7 | AttackDone | S→C | unhandled | P1 | `u32 attackSequence, u32 weenieError`. |
| 0x01A8 | MagicRemoveSpell | S→C | unhandled | P2 | `u32 spellId`. |
| 0x01AC | VictimNotification | S→C | unhandled | P1 | `string16L attackerName, u32 attackerGuid, u32 damageType, u32 damage, u32 hitQuadrant, u32 crit, u32 attackType`. |
| 0x01AD | KillerNotification | S→C | unhandled | P1 | `string16L victimName, u32 victimGuid`. |
| 0x01B1 | AttackerNotification | S→C | unhandled | P1 | `string16L defenderName, u32 damageType, u32 damage, f32 damagePercent`. |
| 0x01B2 | DefenderNotification | S→C | unhandled | P1 | `string16L attackerName, u32 attackerGuid, u32 damageType, u32 damage, u32 hitQuadrant, u32 crit`. |
| 0x01B3 | EvasionAttackerNotification | S→C | unhandled | P1 | `string16L defenderName`. |
| 0x01B4 | EvasionDefenderNotification | S→C | unhandled | P1 | `string16L attackerName`. |
| 0x01B8 | CombatCommenceAttack | S→C | unhandled | P1 | No payload. "You swing your weapon." |
| 0x01C0 | UpdateHealth | S→C | unhandled | P1 | `u32 targetGuid, f32 healthPercent`. Reply to QueryHealth. |
| 0x01C3 | QueryAgeResponse | S→C | unhandled | P4 | — |
| 0x01C7 | UseDone | S→C | unhandled | P1 | `u32 weenieError` — the Use event's completion signal. |
| 0x01C8 | AllegianceAllegianceUpdateDone | S→C | unhandled | P3 | — |
| 0x01C9 | FellowshipFellowUpdateDone | S→C | unhandled | P3 | — |
| 0x01CA | FellowshipFellowStatsDone | S→C | unhandled | P3 | — |
| 0x01CB | ItemAppraiseDone | S→C | unhandled | P4 | Ghost — never emitted. |
| 0x01E2 | Emote | S→C | unhandled | P1 | Same as GM 0x01E0 but GameEvent subclass. |
| 0x01EA | PingResponse | S→C | unhandled | P1 | `u32 clientId` echo. |
| 0x01F4 | SetSquelchDB | S→C | unhandled | P3 | Squelch list sync. |
| 0x01FD | RegisterTrade | S→C | unhandled | P3 | — |
| 0x01FE | OpenTrade | S→C | unhandled | P3 | — |
| 0x01FF | CloseTrade | S→C | unhandled | P3 | — |
| 0x0200 | AddToTrade | S→C | unhandled | P3 | `u32 itemGuid, u32 slotIndex`. |
| 0x0201 | RemoveFromTrade | S→C | unhandled | P3 | — |
| 0x0202 | AcceptTrade | S→C | unhandled | P3 | `u32 initiatorGuid`. |
| 0x0203 | DeclineTrade | S→C | unhandled | P3 | — |
| 0x0205 | ResetTrade | S→C | unhandled | P3 | — |
| 0x0207 | TradeFailure | S→C | unhandled | P3 | `u32 errorCode`. |
| 0x0208 | ClearTradeAcceptance | S→C | unhandled | P3 | — |
| 0x021D | HouseProfile | S→C | unhandled | P3 | — |
| 0x0225 | HouseData | S→C | unhandled | P3 | — |
| 0x0226 | HouseStatus | S→C | unhandled | P3 | — |
| 0x0227 | UpdateRentTime | S→C | unhandled | P3 | — |
| 0x0228 | UpdateRentPayment | S→C | unhandled | P3 | — |
| 0x0248 | HouseUpdateRestrictions | S→C | unhandled | P3 | — |
| 0x0257 | UpdateHAR | S→C | unhandled | P3 | — |
| 0x0259 | HouseTransaction | S→C | unhandled | P3 | — |
| 0x0264 | QueryItemManaResponse | S→C | unhandled | P2 | `u32 itemGuid, f32 manaPercent`. |
| 0x0271 | AvailableHouses | S→C | unhandled | P3 | — |
| 0x0274 | CharacterConfirmationRequest | S→C | unhandled | P2 | `u32 type, u32 contextId, u32 otherGuid, string16L message`. |
| 0x0276 | CharacterConfirmationDone | S→C | unhandled | P2 | `u32 contextId, bool accepted`. |
| 0x027A | AllegianceLoginNotification | S→C | unhandled | P3 | — |
| 0x027C | AllegianceInfoResponse | S→C | unhandled | P3 | — |
| 0x0281 | JoinGameResponse | S→C | unhandled | P4 | Chess/minigame. |
| 0x0282 | StartGame | S→C | unhandled | P0 | "World finished loading" signal (duplicate of LoginComplete flow in some clients). |
| 0x0283 | MoveResponse | S→C | unhandled | P4 | Minigame. |
| 0x0284 | OpponentTurn | S→C | unhandled | P4 | Minigame. |
| 0x0285 | OpponentStalemate | S→C | unhandled | P4 | Minigame. |
| 0x028A | WeenieError | S→C | unhandled | P1 | `u32 errorCode` — generic game-logic failure (ported from `WeenieError` enum in shared models). |
| 0x028B | WeenieErrorWithString | S→C | unhandled | P1 | `u32 errorCode, string16L interpolation`. |
| 0x028C | GameOver | S→C | unhandled | P4 | Minigame. |
| 0x0295 | SetTurbineChatChannels | S→C | unhandled | P1 | `u32 count, TurbineChatChannelConfig[count]` — configures which chat rooms to show. |
| 0x02AE | AdminQueryPluginList | S→C | unhandled | P4 | — |
| 0x02B1 | AdminQueryPlugin | S→C | unhandled | P4 | — |
| 0x02B3 | AdminQueryPluginResponse | S→C | unhandled | P4 | — |
| 0x02B4 | SalvageOperationsResult | S→C | unhandled | P2 | Salvage result blob. |
| 0x02BD | Tell | S→C | unhandled | P1 | `string16L message, string16L senderName, u32 senderGuid, u32 targetGuid, u32 chatType`. |
| 0x02BE | FellowshipFullUpdate | S→C | unhandled | P3 | — |
| 0x02BF | FellowshipDisband | S→C | unhandled | P3 | — |
| 0x02C0 | FellowshipUpdateFellow | S→C | unhandled | P3 | Member delta. |
| 0x02C1 | MagicUpdateSpell | S→C | unhandled | P2 | `u32 spellId`. Adds spell to spellbook. |
| 0x02C2 | MagicUpdateEnchantment | S→C | unhandled | P1 | `Enchantment` blob — buff/debuff on player. |
| 0x02C3 | MagicRemoveEnchantment | S→C | unhandled | P1 | `u32 layerId, u32 spellId`. |
| 0x02C4 | MagicUpdateMultipleEnchantments | S→C | unhandled | P1 | `u32 count, Enchantment[count]`. |
| 0x02C5 | MagicRemoveMultipleEnchantments | S→C | unhandled | P1 | Same shape. |
| 0x02C6 | MagicPurgeEnchantments | S→C | unhandled | P1 | — |
| 0x02C7 | MagicDispelEnchantment | S→C | unhandled | P1 | Single dispel. |
| 0x02C8 | MagicDispelMultipleEnchantments | S→C | unhandled | P1 | Multi dispel. |
| 0x02C9 | PortalStormBrewing | S→C | unhandled | P3 | — |
| 0x02CA | PortalStormImminent | S→C | unhandled | P3 | — |
| 0x02CB | PortalStorm | S→C | unhandled | P3 | — |
| 0x02CC | PortalStormSubsided | S→C | unhandled | P3 | — |
| 0x02EB | CommunicationTransientString | S→C | unhandled | P1 | `string16L message, u32 chatType` — ticker-style message. |
| 0x0312 | MagicPurgeBadEnchantments | S→C | unhandled | P2 | — |
| 0x0314 | SendClientContractTrackerTable | S→C | unhandled | P3 | Full contract list. |
| 0x0315 | SendClientContractTracker | S→C | unhandled | P3 | Single contract update. |

**Total GameEvent opcodes:** 94. **Currently handled:** 0. **Unhandled:**
94 — the 0xF7B0 path is completely absent from acdream today.

---

## 5. Login-phase opcodes

### 5.1 Order (source: `WorldSession.Connect` + `EnterWorld` + holtburger
`session/handshake`):

```
  C→S: LoginRequest       (header flag 0x00010000, custom auth body on port N)
  S→C: ConnectRequest     (header flag 0x00040000, returns seeds + cookie + clientId)
       ←200ms race delay→
  C→S: ConnectResponse    (header flag 0x00080000, echo cookie — sent to port N+1)
  S→C: ServerName (GM 0xF7E1)
  S→C: CharacterList (GM 0xF658)
  C→S: CharacterEnterWorldRequest (GM 0xF7C8)
  S→C: CharacterEnterWorldServerReady (GM 0xF7DF)
  C→S: CharacterEnterWorld (GM 0xF657)
  S→C: DDD_Interrogation (GM 0xF7E5)
  C→S: DDD_InterrogationResponse (GM 0xF7E6)
  S→C: PlayerCreate (GM 0xF746) + optional UpdateObjects for initial bubble
  C→S: GameAction(LoginComplete) (GA 0x00A1)
  S→C: GameEvent(PlayerDescription) (GE 0x0013) — full stat sheet
  S→C: GameEvent(SetTurbineChatChannels) (GE 0x0295)
  S→C: many GameMessageCreateObject for the initial bubble
```

### 5.2 Timing + latency requirements

- The **200ms race delay** before ConnectResponse is required because
  the retail client's UDP flow sends the response before the server has
  finished allocating the session on port N+1. 200ms is the minimum that
  reliably works against live ACE. Shorter delays cause intermittent
  "connection refused" from the kernel.
- Every server packet with `Sequence > 0` needs an ack within ~60s
  regardless of phase (see §1.5). Failing this → `Network Timeout`.
- **LoginComplete must follow PlayerCreate, not EnterWorld.** Sending
  LoginComplete too early keeps the server in a transitional state and
  other clients see the player as a purple loading haze.
- **DDD_InterrogationResponse must be sent promptly** after receiving
  DDD_Interrogation (within a few hundred ms). If the server decides
  DATs are out of sync it will boot the account.
- If DAT patching is **enabled** on the server, DDD_Interrogation →
  DDD_BeginDDD → multiple DDD_DataMessage → DDD_EndDDD can push
  megabytes of data before LoginComplete is viable.

---

## 6. In-world opcodes — functional groups

### 6.1 Movement (the hot path)

| Opcode | Dir | Cadence | Notes |
|:------:|:---:|:-------:|-------|
| 0xF61C MoveToState | C→S | On key state change | Sent when the motion command set changes (start/stop walking, sidestep, turn). Full RawMotionState, position, rotation, sequences, contact byte. |
| 0xF753 AutonomousPosition | C→S | Every ~200ms while moving | Heartbeat confirming the client is still at position X. No motion commands — just position + sequences. |
| 0xF61B Jump | C→S | On jump key | Same structure as MoveToState but with `f32 extent, Vector3 velocity` prepended. |
| 0xF748 UpdatePosition | S→C | Per-entity, variable | Every entity in the bubble gets these as they move. We parse + fire `PositionUpdated`. |
| 0xF74C UpdateMotion | S→C | On motion change | NPC starts walking, creature enters combat, door opens, etc. |
| 0xF74E VectorUpdate | S→C | Per-tick for flying objects | Missiles, projectiles, continuous-turn casts. Unhandled today. |
| 0xF751 PlayerTeleport | S→C | On teleport | Player is being moved through portal space. acdream fires `TeleportStarted` and re-sends LoginComplete at destination. |
| 0xF753 AutonomousPosition | S→C | On server-forced snap | When the server rejects a client-reported position (collision fail, cheat detection), it pushes this to snap the client back. |

### 6.2 Object lifecycle

| Opcode | Dir | Notes |
|:------:|:---:|-------|
| 0xF745 CreateObject | S→C | Initial spawn of anything visible. 538-line parser in `Messages/CreateObject.cs`. |
| 0xF746 PlayerCreate | S→C | Special-case of CreateObject for our own player. Same body shape; different semantic. Used as the LoginComplete trigger. |
| 0xF747 ObjectDelete | S→C | `u32 guid, u16 seq`. **Unhandled** — this is the #1 "must add" gap after chat. Without it, stale entities pile up. |
| 0xF7DB UpdateObject | S→C | Full re-serialize. Used for gear/appearance changes, morphs. |
| 0xF625 ObjDescEvent | S→C | Visual-description-only re-send. Lighter than UpdateObject. |
| 0xF6EA ForceObjectDescSend | bi | Client can C→S to refresh; server sends S→C to force. |

### 6.3 Chat (primary channel)

| Opcode | Dir | Notes |
|:------:|:---:|-------|
| GA 0x0015 Talk | C→S | Local area say. |
| GA 0x005D Tell | C→S | Whisper by name. |
| GA 0x0032 TalkDirect | C→S | Whisper by target. |
| GA 0x0147 ChatChannel | C→S | Send to named channel. |
| GA 0x01DF Emote | C→S | /e text. |
| GM 0x02BB HearSpeech | S→C | Nearby chat. |
| GM 0x02BC HearRangedSpeech | S→C | Shouts. |
| GM 0x01E0 EmoteText | S→C | Environmental emote. |
| GE 0x02BD Tell | S→C | Whisper inbound. |
| GE 0x0147 ChannelBroadcast | S→C | Custom channel line. |
| GM 0xF7E0 ServerMessage | S→C | System chat. |
| GM 0xF7DE TurbineChat | bi | Turbine's social chat (General/Trade/LFG/Allegiance/Society). Nested binary blob — non-trivial parser. |
| GE 0x0295 SetTurbineChatChannels | S→C | Configure Turbine chat rooms on login. |

### 6.4 Combat

| Opcode | Dir | Notes |
|:------:|:---:|-------|
| GA 0x0008 TargetedMeleeAttack | C→S | `targetGuid, attackHeight, powerLevel`. |
| GA 0x000A TargetedMissileAttack | C→S | `targetGuid, attackHeight, accuracyLevel`. |
| GA 0x01B7 CancelAttack | C→S | — |
| GA 0x0053 ChangeCombatMode | C→S | Peace/Melee/Missile/Magic. |
| GA 0x01BF QueryHealth | C→S | Request health % for a target. |
| GE 0x01C0 UpdateHealth | S→C | Reply to QueryHealth; `f32 healthPercent`. |
| GE 0x01A7 AttackDone | S→C | End-of-swing. |
| GE 0x01AC VictimNotification | S→C | You took damage. |
| GE 0x01AD KillerNotification | S→C | You killed X. |
| GE 0x01B1 AttackerNotification | S→C | You did damage. |
| GE 0x01B2 DefenderNotification | S→C | You were attacked. |
| GE 0x01B3 EvasionAttackerNotification | S→C | Target dodged you. |
| GE 0x01B4 EvasionDefenderNotification | S→C | You dodged. |
| GE 0x01B8 CombatCommenceAttack | S→C | Swing-start flag. |
| GM 0x019E PlayerKilled | S→C | Fatal blow. |

### 6.5 Spells & enchantments

| Opcode | Dir | Notes |
|:------:|:---:|-------|
| GA 0x0048 CastUntargetedSpell | C→S | `u32 spellId`. |
| GA 0x004A CastTargetedSpell | C→S | `u32 targetGuid, u32 spellId`. |
| GA 0x01A8 RemoveSpellC2S | C→S | Un-learn a spell. |
| GA 0x01E3/0x01E4 Add/RemoveSpellFavorite | C→S | Hotbar slot management. |
| GE 0x02C1 MagicUpdateSpell | S→C | Add/refresh a spellbook entry. |
| GE 0x02C2 MagicUpdateEnchantment | S→C | Buff/debuff applied. |
| GE 0x02C3 MagicRemoveEnchantment | S→C | Buff expired/dispelled. |
| GE 0x02C4/0x02C5 MagicUpdate/RemoveMultiple | S→C | Batch variants. |
| GE 0x02C6 MagicPurgeEnchantments | S→C | Full clear. |
| GE 0x0312 MagicPurgeBadEnchantments | S→C | Clear debuffs only. |
| GE 0x02C7/0x02C8 MagicDispel[Multiple]Enchantment | S→C | Dispelled-by-player. |
| GE 0x01A8 MagicRemoveSpell | S→C | Spell removed from book. |

### 6.6 Inventory & items

| Opcode | Dir | Notes |
|:------:|:---:|-------|
| GA 0x0019 PutItemInContainer | C→S | `itemGuid, containerGuid, placement`. |
| GA 0x001A GetAndWieldItem | C→S | Pick up and equip in one step. |
| GA 0x001B DropItem | C→S | — |
| GA 0x0036 Use | C→S | — |
| GA 0x0035 UseWithTarget | C→S | — |
| GA 0x00C8 IdentifyObject | C→S | — |
| GA 0x0054/0x0055/0x0056 Stackable\* | C→S | Split / merge. |
| GA 0x005F/0x0060 Buy/Sell | C→S | — |
| GE 0x0022 InventoryPutObjInContainer | S→C | — |
| GE 0x0023 WieldObject | S→C | — |
| GE 0x019A InventoryPutObjectIn3D | S→C | Dropped to ground. |
| GE 0x0196 ViewContents | S→C | Container list. |
| GE 0x00C9 IdentifyObjectResponse | S→C | Appraise reply. |
| GE 0x0062 ApproachVendor | S→C | Vendor inventory. |
| GM 0xF74A PickupEvent | S→C | Pickup animation flag. |
| GM 0x0024 InventoryRemoveObject | S→C | — |
| GM 0x0197 SetStackSize | S→C | — |
| GM 0xF749 ParentEvent | S→C | Equip / attach. |

---

## 7. Frequency / priority

| Rank | Rate (approx, with 10 other players nearby) | Opcodes | Why |
|:----:|---------------------------------------------|---------|-----|
| **Very hot** | 2-5 Hz per player, per creature | UpdatePosition, UpdateMotion, AutonomousPosition (both directions) | Physics sync. Must not allocate on hot path. |
| **Hot** | ~0.5 Hz per player | VectorUpdate, MoveToState | Movement delta. |
| **Warm** | ~1 msg every few seconds | HearSpeech, ChannelBroadcast, Tell, EmoteText, UpdateHealth, attack notifications | Chat + combat feedback. |
| **Cool** | ~1 msg / min | ObjectCreate bursts on bubble enter, ObjectDelete on bubble exit, UpdateObject on gear swap | Bubble churn. |
| **Cold** | Once per session or event | CharacterList, DDD, LoginComplete, PlayerDescription, SetTurbineChatChannels, PlayerKilled, PlayerTeleport | Login + rare triggers. |
| **Background** | Driven by player action | Use, IdentifyObject, Buy, PingRequest, spell casting | Player explicit. |

Planning implication: the top two tiers (physics sync) must be
zero-allocation parses. acdream's current `CreateObject.TryParse` and
`UpdatePosition.TryParse` already are — they use `ReadOnlySpan<byte>`
and `BinaryPrimitives`. New parsers should match that pattern.

---

## 8. Gap analysis — what's missing for minimum viable play

Grouped by how much they unblock:

### 8.1 P0 / session health (must-have for any session to survive)

- **0xF747 ObjectDelete** — without this, stale entities pile up
  forever. High impact, ~30-line parser, emit `EntityDespawned` event.
- **0xF752 AutonomyLevel (S→C)** — parse and store. ACE live sends
  this regularly; ignoring it is fine today but we should not
  crash on unknown payloads.
- **0xF7DC AccountBoot** — transition to `Failed` with the server's
  reason string instead of a timeout.
- **0xF659 CharacterError** — surface login failures as errors
  rather than a CharacterList timeout.

### 8.2 P1 / basic in-world feedback (first thing a user will miss)

- **Chat stack**: 0x02BB HearSpeech, 0x02BC HearRangedSpeech,
  0x01E0 EmoteText, 0xF7E0 ServerMessage, 0xF7B0/0x0147
  ChannelBroadcast, 0xF7B0/0x02BD Tell, 0xF7B0/0x02EB
  CommunicationTransientString, 0xF7B0/0x0004 PopupString. Plus
  outbound 0xF7B1/0x0015 Talk, /0x005D Tell, /0x0147 ChatChannel,
  /0x01DF Emote.
- **Property updates (0x02CD..0x02EA)**: 22 opcodes, but they all
  share a compact pattern — `u32 guid, u32 propId, value`. One
  generic parser + 8 value-type branches covers everything. Fires
  per-property events.
- **GameEvent envelope (0xF7B0)**: must ship the dispatcher skeleton
  before any GameEvent can be handled.
- **Combat events (0x01AC..0x01B8)**: receiving only; one parser per
  message. Lets floating combat text + hit indicators work.
- **0x02C2/0x02C4 Magic[Multiple]UpdateEnchantment + 0x02C3/0x02C5
  remove**: buff/debuff HUD.
- **0xF625 ObjDescEvent** + **0xF7DB UpdateObject**: for seeing
  other players change gear. Critical for multiplayer immersion.
- **GameEvent PlayerDescription (0x0013)** — initial character
  sheet. Gate for inventory/spellbook UI. Biggest message in the
  protocol — ~30 KB of interleaved property tables.

### 8.3 P2 / inventory, assess, vendor

- 0x00C9 IdentifyObjectResponse + GA 0x00C8 IdentifyObject.
- Full inventory flow: GA 0x0019, 0x001A, 0x001B, 0x0054-0x0056,
  and the mirror GameEvents 0x0022, 0x0023, 0x019A, 0x0196.
- GE 0x0062 ApproachVendor + GA 0x005F Buy / 0x0060 Sell.
- GA 0x0036 Use + 0x0035 UseWithTarget + GE 0x01C7 UseDone.

### 8.4 P3 / social, housing, allegiance

Large opcode count but highly modular — each subsystem is ~15-20
opcodes. Skip until post-beta.

### 8.5 P4 / admin, minigames, barber, char-create

Zero visibility impact for combat-focused play. Park.

---

## 9. Port plan — where the WorldSession dispatcher needs to expand

### 9.1 Refactor the dispatcher skeleton first (phase D prerequisite)

Today `WorldSession.ProcessDatagram` is a long `if/else` ladder. Before
adding more handlers, split it into a dispatcher class. Layout:

```
AcDream.Core.Net/
├── Messages/
│   ├── GameMessageDispatcher.cs        // top-level opcode → parser router
│   ├── GameEventDispatcher.cs          // inside 0xF7B0
│   ├── GameActionBuilder.cs            // fluent builder for 0xF7B1 envelope
│   └── <one file per opcode group>
└── WorldSession.cs                     // becomes thin, delegates to above
```

Each dispatcher exposes `register<T>(opcode, parser)` so phase D can
bolt on new handlers without modifying the dispatcher class body.

### 9.2 Phase D — chat + session health

Scope:
- Add the GameEvent envelope dispatcher (0xF7B0).
- Ship ObjectDelete (0xF747), AutonomyLevel (0xF752), AccountBoot
  (0xF7DC), CharacterError (0xF659).
- Ship the chat group (11 opcodes) + outbound Talk/Tell/ChatChannel.
- Ship PopupString, CommunicationTransientString, SetTurbineChatChannels
  as UI sidechannels.
- Add an `IChatSurface` event set on WorldSession: `Said`, `Whispered`,
  `ChannelMessage`, `SystemMessage`, `Popup`, `Transient`.

Acceptance: log in, receive and post chat, see server announcements,
get kicked gracefully.

### 9.3 Phase E — property & stats

Scope:
- Ship the 22 property-update opcodes behind one generic
  `PropertyUpdateParser` keyed on PropertyId.
- Ship PlayerDescription (GE 0x0013) — the single biggest parser job.
- Ship UpdateHealth (GE 0x01C0), QueryHealth (GA 0x01BF).
- Ship ObjDescEvent (0xF625), UpdateObject (0xF7DB).
- Expose `IPlayer` interface that plugins can observe:
  `Attributes, Skills, Vitals, Inventory, Spellbook`.

Acceptance: stat sheet renders correctly, health bars update live,
can assess nearby NPCs.

### 9.4 Phase F — combat + spells

Scope:
- Ship combat notifications (0x01AC..0x01B8).
- Ship attack actions (GA 0x0008, 0x000A, 0x01B7, 0x0053).
- Ship enchantments (GE 0x02C1..0x02C8, 0x0312).
- Ship cast actions (GA 0x0048, 0x004A).

Acceptance: can kill a lurker, see float text + health, land a
self-buff and watch it tick.

### 9.5 Phase G — inventory

Scope:
- Ship the GA/GE inventory families.
- Ship ApproachVendor + Buy/Sell.
- Ship PickupEvent + ParentEvent.

Acceptance: loot a drudge, sell to vendor, equip a weapon, see it
render on the avatar.

### 9.6 Deferred: housing, allegiance, fellowship, books, barber, chess

All the P3/P4 tails. Ship when we need them, not before.

---

## 10. Collision + sub-type notes (the ultrathink)

- **0xF643 CharacterCreateResponse vs CharacterRestoreResponse.** Same
  opcode, two meanings. Disambiguated entirely by session state —
  if the client just sent 0xF656 CharacterCreate the reply is a create
  response; if it just sent 0xF7D9 CharacterRestore it's a restore
  response. Parsers must key on context, not opcode. ACE has a
  duplicate entry in the enum (`CharacterRestoreResponse = 0xF643,
  // This is a duplicate...`). Holtburger keeps them combined under
  `CharacterCreateResponse`.
- **0xF74C: MovementEvent and Motion are the same opcode.** ACE
  aliases `Motion = 0xF74C` and `MovementEvent = 0xF74C` — semantically
  identical, just two names. Our `UpdateMotion.cs` already handles this.
- **0xF753 AutonomousPosition goes both ways** with the **same body
  layout** but different semantics. Outbound = "I'm still here";
  inbound = "no you're not, here's where you really are." Parser can
  be shared; the client just needs to know direction to choose the
  right side-effect (`PositionUpdated` vs `ForcedResync`).
- **0x0147 ChatChannel vs ChannelBroadcast.** C→S uses 0x0147 inside
  GameAction (envelope 0xF7B1); S→C uses 0x0147 inside GameEvent
  (envelope 0xF7B0). Same wire opcode, different parser because
  different envelope. This is true for many ID collisions — the
  envelope disambiguates them.
- **0x0148/0x0149 Channel List/Index** — same C→S/S→C pairing pattern.
- **0x00A3/0x00A4 FellowshipQuit/Dismiss** — same pairing; C→S in
  GameAction, S→C in GameEvent.
- **0xF653 CharacterLogOff** — bi-directional, same opcode, no
  envelope. Client sends to request logout; server sends the echo
  before Disconnect.
- **0x01A8 MagicRemoveSpell** — C→S is GameAction, S→C is GameEvent.
- **0xF7DE TurbineChat** — bi-directional GameMessage. Blob layout
  includes a `ChatNetworkBlobType` discriminant (EVENT_BINARY=1,
  REQUEST_BINARY=3, RESPONSE_BINARY=5) + a `ChatNetworkBlobDispatchType`
  sub-discriminant (SendToRoomByID=1/2). Effectively two opcodes
  (event vs request/response) multiplexed on one wire code. Nested
  "bytes to follow" size prefixes must be back-patched after payload
  writes — non-trivial parser.
- **0xF6EA ForceObjectDescSend** — bi-directional with identical
  `u32 guid` body. The side-effect differs: server takes it as "resend
  to me"; client takes it as "apply a fresh ObjDescEvent I'm about to
  receive."

---

## 11. Source of truth ranking (per opcode category)

When the references disagree, use this priority:

- **PacketHeader + Flags + encryption**: ACE and holtburger agree on
  all bits. No disputes.
- **C→S GameAction opcodes**: holtburger's `opcodes.rs` is the most
  curated list of what a real client actually sends. ACE's
  `GameActionType.cs` is the full universe including things only
  legacy admin tools ever sent. Use holtburger when in doubt about
  which GAs are relevant; use ACE when you need the wire layout of
  a specific handler.
- **S→C GameMessage opcodes**: ACE's `GameMessageOpcode.cs` is the
  canonical enum; Chorizite's XML adds field-level comments that
  are sometimes more accurate than ACE's implementation (remember
  "If it is 0, it defaults to 256*8"). Use ACE for structure; use
  Chorizite to cross-check specific field semantics.
- **S→C GameEvent opcodes**: ACE's `GameEventType.cs` + the per-event
  classes in `Events/` are the wire ground truth.
- **RawMotionState wire**: holtburger `types.rs` is the only source
  that documents every flag bit clearly; ACE has the same structure
  but embedded in `MovementData.Pack`.
- **PositionPack (for UpdatePosition)**: ACE's `PositionPack.Write` is
  the canonical serializer; holtburger matches bit-for-bit.
- **TurbineChat nested blob**: ACE's `GameMessageTurbineChat` has a
  large comment block documenting every field layout. Holtburger's
  implementation matches.

---

## 12. Quick-reference: what to add first if you have one afternoon

Pick **four** opcodes from the P0/P1 tier and you have a meaningfully
more useful client by end-of-day:

1. **0xF747 ObjectDelete** — stop leaking entities (20 lines).
2. **0xF7B0 GameEvent envelope skeleton** — unlocks the whole event
   category (50 lines dispatcher).
3. **0x02BB HearSpeech** + **0x02BC HearRangedSpeech** — see world
   chat (same parser, different trigger; 30 lines each).
4. **0xF7E0 ServerMessage** — see system chat (20 lines).

That's ~150 lines of parser code and acdream graduates from "renders
the world" to "reads the world's feedback."