acdream/docs/research/deepdives/00-master-synthesis.md

# acdream — Retail AC Deep-Dive Master Synthesis

**Date:** 2026-04-17
**Total research output:** ~78,000 words across 13 deep-dive slices
(plus the retail-UI set from earlier the same day — 30,000 words more).
Each slice is a self-contained 4-9 KLOC document of research +
pseudocode + C# port plan, with every claim cited to a decompiled
`FUN_` address or an ACE / DatReaderWriter / holtburger / ACViewer
reference.

This document is the navigation hub and cross-reference map. It does
NOT repeat each slice's findings; it summarizes the headline, lists
cross-system dependencies, and proposes the concrete acdream phase
sequence that falls out of the research.

---

## 1. Slice inventory

| ID  | Topic                           | File                                                         | Words | Key finding |
|-----|---------------------------------|--------------------------------------------------------------|-------|-------------|
| R1  | Spell system                    | [r01-spell-system.md](r01-spell-system.md)                   | 5.4K  | Sigmoid `1/(1+e^(-0.07·(skill-difficulty)))` fizzle curve; 8 spellbook tabs at panel offset `0x638+0x1C·tab`; spell `0x004A`/`0x0048` wire; spell book unlock via `UpdateSpell (0x02C1)` |
| R2  | Combat                          | [r02-combat-system.md](r02-combat-system.md)                 | 5.9K  | `PowerMod = Level + 0.5` melee; physical logistic at `k=0.03` / magic at `k=0.07`; 12-quadrant body table; 7 damage types × layered AL; 10%/5% base crit |
| R3  | Motion + animation              | [r03-motion-animation.md](r03-motion-animation.md)           | 8.2K  | 450+ motion commands; cycle key `(style<<16)\|(cmd & 0xFFFFFF)`; 27 hook types; no crossfade — link animations ARE the transition; `-0.65` backward factor; `1.5×` run-turn |
| R4  | VFX / particles                 | [r04-vfx-particles.md](r04-vfx-particles.md)                 | 5.8K  | 13 ParticleType motion integrators; no flipbook (chain hooks instead); PlayScript enum has 174 values; `PhysicsScriptTable` mod-selection; WorldBuilder's `ParticleBatcher` ports directly |
| R5  | Audio                           | [r05-audio-sound.md](r05-audio-sound.md)                     | 5.6K  | DirectSound 8 + WinMM MIDI; 16-voice cap; inverse-square CPU falloff (no doppler/cone/HRTF); 204 Sound IDs; motion-driven triggers via animation hooks 1/2/21 |
| R6  | Items + inventory               | [r06-items-inventory.md](r06-items-inventory.md)             | 7.4K  | ItemType is `[Flags]` 32-bit; 31 EquipMask slots; 7 property tables; `Appraise` C2S `0x00C8` / S2C `0x00C9`; burden = 150·STR + STR·bonusBurden; 2-deep pack depth |
| R7  | Character creation              | [r07-character-creation.md](r07-character-creation.md)       | 6.3K  | Dat `0xE000002 CharGen`; 13 heritages × 330 attr credits × 52 skill credits (Olthoi 68); SpecializedCost is a DELTA; `0xF656` → `0xF643` wire round-trip |
| R8  | Network protocol atlas          | [r08-network-protocol-atlas.md](r08-network-protocol-atlas.md) | 9.7K  | 63 primary GameMessages + 149 GameActions + 94 GameEvents mapped. Of GameEvents (S→C, 0xF7B0 envelope), **zero handled** today — biggest gap |
| R9  | Dungeon + portal space          | [r09-dungeon-portal-space.md](r09-dungeon-portal-space.md)   | 6.3K  | Dungeon detect = all heights 0 & NumCells>0 & no Buildings; `PlayerTeleport (0xF751)` needs LoginComplete re-send; no loading screen — "pink bubble" hides avatar |
| R10 | Quest + NPC dialogs             | [r10-quest-dialogs.md](r10-quest-dialogs.md)                 | 7.1K  | "Quests" are emote-script trees, not a first-class system; 122 EmoteType × 39 EmoteCategory; contract tracker via `0x0314/0x0315`; dialog = chat message with `<Tell:...>` markup |
| R11 | Allegiance                      | [r11-allegiance.md](r11-allegiance.md)                       | 5.4K  | Max 11 direct vassals; rank `max(lower+1, higher)` capped 10; XP passup `50+22.5·loyalty/291·(1+RT/730·IG/720)`; no swear cooldown (24h applies to name only) |
| R12 | Weather + day/night             | [r12-weather-daynight.md](r12-weather-daynight.md)           | 4.5K  | 95% client-side — server just sends Portal Year time; determinism = same sky everywhere; no `SetWeather` opcode; sky is geometry not shader ramp |
| R13 | Dynamic lighting                | [r13-dynamic-lighting.md](r13-dynamic-lighting.md)           | 4.9K  | Hard 8-light cap (fixed function D3D); NO distance attenuation inside Range then hard cutoff; terrain baked per-vertex via `AdjustPlanes`; blob shadow at `0x0600102F` |

**Grand total: 82,500 words of grounded, citation-backed research.**

---

## 2. The big picture — how the systems wire together

```
┌─────────────────────────────────────────────────────────────────┐
│                    ACE (Asheron's Call Emulator)                │
│                     — server authority                          │
└────┬────────────────────────────────────────────────────────────┘
     │  UDP packets (ISAAC, fragmented, ack'd)
     │
┌────▼────────────────────────────────────────────────────────────┐
│  WorldSession (R8 atlas)                                        │
│  • Login (4 msg), CharList, EnterWorld, CreateObject stream     │
│  • Dispatch of 63 + 94 + 149 opcodes                            │
└────┬──────────────┬──────────────┬──────────────┬───────────────┘
     │              │              │              │
     │CreateObject  │UpdateMotion  │UpdateHealth  │UpdateSpell
     │  items       │  anim        │  combat      │  buff/debuff
     ▼              ▼              ▼              ▼
┌──────────┐  ┌───────────┐  ┌──────────┐  ┌───────────┐
│ Inventory│  │ Motion    │  │  Combat  │  │  Spell    │
│ (R6)     │  │ (R3)      │  │  (R2)    │  │  (R1)     │
│          │  │           │  │          │  │           │
│ItemInst  │──│ DoMotion  │──│ Damage   │──│ ActiveBuf │
│Container │  │ MotionTbl │  │ fromCmd  │  │ Fizzle    │
│Burden    │  │ Hooks ────┼──┤ FootStep │  │ Recall    │
└────┬─────┘  └─┬────┬────┘  └────┬─────┘  └────┬──────┘
     │          │    │            │             │
     │          │    └────hooks──►│             │
     │          │                 │             │
     └──────────┴───────►┌────────▼─────────────▼──┐
                         │   Audio (R5) +          │
                         │   VFX/Particles (R4)    │
                         │   — cosmetic layer       │
                         └──────────────┬──────────┘
                                        │
                                        ▼
                        ┌───────────────────────────────┐
                        │  UI (retail-ui set) + HUD     │
                        │  AttrPanel + SpellBar + Chat  │
                        │  VitalOrbs + Radar + Compass  │
                        │  (all behind UiRoot scaffold) │
                        └───────────────────────────────┘

    ┌─ World lifecycle
    │
┌───▼─────────────────────┐
│ Streaming (existing)    │
├─────────────────────────┤
│ + Dungeon / portal (R9) │
│ + Weather sky (R12)     │
│ + Dynamic lights (R13)  │
└─────────────────────────┘

┌─ Social / progression
│
┌──────────────────┐   ┌─────────────────┐
│ Allegiance (R11) │   │ Quest + dialog  │
│ • Tree + ranks   │   │ (R10)           │
│ • XP passup       │  │ • Emote scripts │
│ • Chat channels  │   │ • Contract tkr  │
└──────────────────┘   └─────────────────┘

┌─ Game entry
│
┌──────────────────┐
│ CharCreate (R7)  │
│ • Heritage + skl │
│ • Appearance     │
│ • Starting town  │
└──────────────────┘
```

---

## 3. Critical cross-system dependencies

These are the places where one system MUST be built before another can
land cleanly. They define the port sequence.

### 3.1 Motion (R3) blocks three other systems

- **Audio (R5)** — footstep/swing/cast sounds are triggered by
  AnimationHooks (types 1=Sound, 2=SoundTable, 21=SoundTweaked). Without
  the hook dispatcher expanded (R3 port plan), audio has no trigger
  source beyond server-pushed `PlaySound (0xF750)`.
- **VFX (R4)** — spell release, weapon trail, footstep dust attach at
  specific animation hook frames (`CreateParticleHook`, hook type 18).
- **Combat (R2)** — the damage application frame is an `AttackFrame`
  hook (type 20) inside the attack animation. Without R3 hook
  dispatch, combat math has to guess timing.

**Implication:** R3 motion-hook expansion is a blocker for R2, R4, R5
to feel retail-faithful. It's a prerequisite for "the game feels
alive".

### 3.2 Inventory (R6) blocks three UI panels

- **Paperdoll** — drops items into slots; requires `ItemInstance` model.
- **Spellbook (R1)** — items like scarabs are consumed via R6 burden rules.
- **Quest turn-in (R10)** — emote's "Give" trigger needs item ID +
  property bundle to validate.

**Implication:** R6 is the data-model foundation for any gameplay UI.

### 3.3 Network (R8) is the permanent bottleneck

Of 94 GameEvents (0xF7B0 envelope), **zero are handled today**. These
include:
- `PlayerDescription (0x0013)` — full character at login
- `AllegianceInfoResponse (0x007E)`
- `Fellowship*` events (5 opcodes)
- `Identify/Appraise response (0x00C9)`
- `SendClientContractTracker (0x0315)`

**Implication:** R8 Phase D (chat + session health) is the unlocking
step for the whole social/quest/inventory stack.

### 3.4 CharCreate (R7) needs CharGen dat + at least one class

The CharGen `0xE000002` dat has every heritage + template + appearance
config. But we also need:
- `ObjDesc` application pipeline (already in our StaticObjectManager)
- At least one working panel to host the UI (R7 uses our UiRoot scaffold)
- Appearance preview renderer — already works for outdoor characters

**Implication:** R7 is the smallest unblocker for "user makes a char
in acdream instead of using ACE admin tools".

### 3.5 Dungeon (R9) extends existing streaming

R9's `EnvCellStreamer` + `PortalVisibility` + `TeleportController` are
additive to `StreamingController`. Risk is low.

### 3.6 Weather (R12) and Lighting (R13) share a scene-state UBO

Both write sun direction + ambient color + fog. A single
`SceneLightingState` UBO fed to `terrain.frag` and `mesh.frag`
consolidates them. R13 reads it; R12 produces it.

### 3.7 VFX (R4) + Audio (R5) share PhysicsScript/PlayScript

Retail's `PlayEffect (0xF755)` bundles both particle + sound. Our
`PhysicsScript` dispatcher should fire both R4 and R5 hooks atomically.

---

## 4. Proposed phase sequence

Based on the dependency graph + what unlocks the most gameplay fastest:

### Phase E — Core gameplay loop (highest value)

| Step | What                                                               | Research | Unblocks |
|------|--------------------------------------------------------------------|----------|----------|
| E.1  | R3 Motion hooks expansion                                          | R3       | E.2-E.4  |
| E.2  | R5 Audio engine + motion-hook wiring                               | R5       | immediate feel |
| E.3  | R4 Particle system + motion-hook wiring + PlayScript dispatcher    | R4       | immediate feel |
| E.4  | R2 Combat math + server-broadcast damage/health                    | R2, R8   | can actually fight |
| E.5  | R1 Spell cast state machine (buffs + recalls first, projectiles later) | R1, R8 | can cast spells |

**Acceptance:** player swings a sword, hears the whoosh, sees the
contact spark, damage number floats up, HP bar drops on the target,
monster dies with footstep/impact sounds. Spell buff lands with
glowing aura + cast sound.

### Phase F — Inventory + UI panels

| Step | What                                                               | Research | Unblocks |
|------|--------------------------------------------------------------------|----------|----------|
| F.1  | R8 GameEvent envelope (0xF7B0) dispatcher                          | R8       | F.2+     |
| F.2  | R6 Item model (`ItemInstance`, `PropertyBundle`)                   | R6       | F.3-F.5  |
| F.3  | Attributes panel (UI slice 05 + R8 `PlayerDescription`)            | UI05, R8 | char sheet |
| F.4  | Paperdoll + Inventory panel (drag-drop from UI slice 04)           | R6, UI04 | gearing up |
| F.5  | Spellbook panel (R1 tabs + icons)                                  | R1, UI05 | cast via UI |

**Acceptance:** opens all core panels, drags items between inventory
+ paperdoll, casts spells by clicking icons.

### Phase G — World systems

| Step | What                                                               | Research |
|------|--------------------------------------------------------------------|----------|
| G.1  | R12 Sky / weather / day-night                                      | R12      |
| G.2  | R13 Dynamic lighting (8-light fixed pipeline)                      | R13      |
| G.3  | R9 Dungeon streaming + portal transition                           | R9       |

**Acceptance:** walk out of Holtburg at dusk, sky gradient rolls,
torches cast light, enter a dungeon via teleport, see the dungeon
interior.

### Phase H — Social + progression

| Step | What                                           | Research |
|------|------------------------------------------------|----------|
| H.1  | Chat window (UI slice 05) + all 6 wire ops     | UI05, R8 |
| H.2  | R11 Allegiance panel + XP passup display       | R11      |
| H.3  | R10 Quest/emote/dialog system                  | R10      |
| H.4  | R7 Character creation panel                    | R7       |

**Acceptance:** talk to an NPC, get a quest, complete it, gain XP,
allegiance MOTD shows in chat.

---

## 5. What's already shipped vs what R-slices unlock

| Domain                  | Shipped                                                   | Next from deep-dives |
|-------------------------|-----------------------------------------------------------|----------------------|
| World rendering         | Terrain + static meshes + scenery + animation + chase cam | R12 sky / R13 lights |
| Streaming               | 5×5 landblock window + EnvCell walker                     | R9 dungeons          |
| Login + wire transport  | LoginRequest → EnterWorld → CreateObject stream           | R8 GameEvent envelope|
| Physics / collision     | Retail-faithful BSP + cylinder + sphere-sweep + scenery   | R3 motion hooks      |
| Input / UI              | UI framework (retail-ui set) + debug overlay              | R4 VFX + R5 audio panels |
| Movement                | WASD + chase cam + jump + autonomous-position sync        | R3 motion commands   |
| Character appearance    | ObjDesc + creature palette + hair/skin/clothing           | R7 char-create panel |
| **Everything else**     | —                                                         | R1/R2/R6/R10/R11     |

---

## 6. Consolidated dat-ID catalog (cross-slice)

Every dat range touched by the 13 slices, de-duplicated:

| Range                       | DBObjType         | Source slices |
|-----------------------------|-------------------|---------------|
| `0x02xxxxxx`                | Setup             | (existing)    |
| `0x04xxxxxx`                | Palette           | UI04          |
| `0x05xxxxxx`                | PaletteSet        | UI04          |
| `0x06000000..0x06FFFFFF`    | RenderSurface     | UI03/UI06, R13 blob shadow `0x0600102F` |
| `0x07xxxxxx`                | RenderSurface     | UI04          |
| `0x08xxxxxx`                | Surface           | UI04          |
| `0x09xxxxxx`                | SurfaceTexture    | (existing)    |
| `0x0A000000..0x0A00FFFF`    | Wave              | **R5 audio**  |
| `0x0E000002`                | CharGen           | **R7 chargen**|
| `0x0F000000..0x0FFFFFFF`    | SurfaceMaterial   | UI04          |
| `0x13000000`                | Region            | (existing) + R12 sky + R13 lights |
| `0x14xxxxxx`                | MasterInputMap    | UI06          |
| `0x20000000..0x2000FFFF`    | SoundTable        | **R5 audio**  |
| `0x21xxxxxx`                | LayoutDesc        | UI06          |
| `0x23/0x24xxxxxx`           | StringTable       | UI06          |
| `0x2Fxxxxxx`                | SpellTable        | **R1 spell**  |
| `0x30xxxxxx`                | SpellComponents   | **R1 spell**  |
| `0x33xxxxxx`                | MotionTable       | (existing) + R3 |
| `0x34000000..0x34000FFF`    | Animation         | (existing) + R3 |
| `0x40000000..0x40000FFF`    | Font              | UI03          |
| `0x41xxxxxx`                | LanguageInfo      | UI06          |

---

## 7. Consolidated opcode quick-reference (cross-slice)

Every opcode mentioned in any slice, for rapid grep-back:

```
Login flow
  0x0001   LoginRequest
  0xF7B1   GameAction envelope (C→S)      ← 149 sub-opcodes
  0xF7B0   GameEvent envelope (S→C)       ← 94 sub-opcodes
  0xF657   CharacterList
  0xF656   Character_SendCharGenResult     (R7)
  0xF643   CharGenResponseType / CharacterError (R7)

Movement (B.3 already ported)
  0xF74C   MoveToState / UpdatePosition    (partial overlap)
  0xF753   Jump / bi-directional
  0xF748   UpdateMotion                    (R3)
  0xF751   PlayerTeleport                  (R9)

Combat (R2)
  0x0008   AttackTargetRequest
  0x000A   CombatStyleRequest
  0x0053   TargetAttack
  0x01B7   MissileAttack
  0xF7xx   UpdateHealth / UpdateVital      (R2, R6 vitals)

Spells (R1)
  0x0048   Magic_CastUntargetedSpell       (R1)
  0x004A   Magic_CastTargetedSpell         (R1)
  0x02C1   UpdateSpell (spellbook add)     (R1)
  0x02C2-0x02C8  Enchantment lifecycle    (R1)
  0x02BB   HearSpeech (chatType 0x11 = syllables) (R1)

Inventory / items (R6)
  0x00C8   AppraiseRequest                 (R6)
  0x00C9   IdentifyResponse                (R6)
  0xF7xx   InventoryMove / Give / Drop / Pickup

Chat (UI05)
  0xF7B0   GameEventChannelBroadcast (0x0147 / envelope)
  0xF7B0   GameEventTell (0x02BD)
  0xF7E0   GameMessageSystemChat
  0x02BB   GameMessageHearSpeech
  0x02BC   GameMessageHearRangedSpeech
  0xF7DE   GameMessageTurbineChat
  0x0295   GameEventSetTurbineChatChannels

Allegiance (R11)
  0x001D   Swear
  0x001E   Break
  0x007E   AllegianceInfoResponse
  0x00DD   AllegianceMotd
  0x02AB   AllegianceRecall action

Quest / contracts (R10)
  0x0314   SendClientContractTrackerTable
  0x0315   SendClientContractTracker
  0xF751   TeleportToPoi (quest-driven recall)

Audio (R5)
  0xF750   PlaySound
  0xF755   PlayEffect (R4 + R5 bundle)

Dungeon / portal (R9)
  0xF751   PlayerTeleport                  (R9)
  0x00A1   LoginComplete (re-send after teleport)

Attributes (UI05)
  0x02E3   PrivateUpdateAttribute
  0x02E7   PrivateUpdateVital
  0x02E9   PrivateUpdateAttribute2ndLevel

Admin / world
  0xEA60   AdminEnvirons (colored-fog override) (R12)
```

**Full table in `r08-network-protocol-atlas.md`.**

---

## 8. Open questions that surfaced

1. **keystone.dll** — blocking for truly retail-faithful widget layout.
   Would need a second decompile pass. (UI slice 02)
2. **Launcher / patcher** — similarly binary-only. (out of scope)
3. **Retail fizzle mana** — R1 flagged "5 points lost on fizzle" as
   tentative; would benefit from retail packet capture.
4. **Power bar timing** — R2 notes the power bar fills over some
   seconds, but exact seconds unclear in decompile.
5. **Doppler on / off** — R5 says off, but this is inferred from no
   `SetFrequency` on 3D buffers. Verify with retail binary trace if
   audio fidelity matters later.
6. **Sky replace animation** — R12 notes `SkyObjReplace` governs dawn
   mesh swap but keyframe interp unclear.
7. **Contract tracker reward delivery** — R10 notes the
   `SendClientContractTrackerTable` format but quest rewards come via
   a separate emote path.
8. **Allegiance passup IG/RT decay** — R11 has the XP formula but the
   "generation tax" (grandpatron vs direct patron) needs a golden-value
   conformance test against ACE.

---

## 9. Risk assessment for each slice's port

Low (data models + straightforward translation):
- R6 Inventory (well-typed properties + containers)
- R7 CharCreate (one dat object, one wire roundtrip)
- R8 Protocol atlas (additive handlers; Phase-F work)
- R11 Allegiance (data + math, no renderer work)
- R12 Weather (deterministic from clock)

Medium (has math or subtle corner cases):
- R1 Spell (sigmoid fizzle, mana conversion, enchant stacking)
- R2 Combat (damage formula sensitivity, crit tables, body-part)
- R3 Motion hooks (27 types, delivery during frame advance)
- R5 Audio (inverse-square falloff, 16-voice eviction)
- R9 Dungeon (portal visibility + teleport state machine)
- R13 Lighting (8-light selection + attenuation curve fidelity)

High (novel systems for us):
- R4 VFX particle systems (new renderer subsystem)
- R10 Quest / emote scripts (mini-VM with 122 action types)

---

## 10. Port sequencing recommendation

If the user wants one-and-only-one focus per week:

- **Week 1 — "Feel alive":** R3 motion hooks → R5 audio → R4 VFX.
  Ship: footsteps, swing sounds, impact particles, spell aura particle.
- **Week 2 — "Fight":** R2 combat math + R8 GameEvent envelope
  dispatcher (a few critical events). Ship: actual damage flow, HP
  updates, death.
- **Week 3 — "Cast":** R1 spell cast state machine (buffs + recall
  first, projectile spells later). Ship: heal spell works, buff spell
  works, recall spell works.
- **Week 4 — "Have gear":** R6 inventory + Attributes + Paperdoll
  panels. Ship: equip weapon, see stats, manage pack contents.
- **Week 5 — "World":** R12 sky + R13 lights + R9 dungeon.
  Ship: enter a dungeon, see torch lights, day/night outside.
- **Week 6 — "Social":** Chat + R11 allegiance + R10 quest +
  R7 char-create. Ship: complete the loop.

If the user wants parallel work: R3/R5/R4 triad can be one stream;
R6/R8 infra can be a parallel stream; R12/R13 visual can be a third.

---

## 11. Plugin API implications

The deep-dives surfaced several places where acdream's plugin API
needs to expose state (R6 item, R1 spell, R11 allegiance, R10 quest).
These are all pure data + event streams, no 3D rendering hooks. The
current `IWorldGameState` + `IEvents` architecture scales to all of
them — each system adds a new read-only interface + an event stream.

Deferred to a separate phase (plugin-api-expansion) once the core
systems land.