Commit graph

9 commits

Author SHA1 Message Date
Erik
3f913f1999 docs+feat: 13 retail-AC deep-dives (R1-R13) + C# port scaffolds + roadmap E-H
78,000 words of grounded, citation-backed research across 13 major AC
subsystems, produced by 13 parallel Opus-4.7 high-effort agents. Plus
compact C# port scaffolds for the top-5 systems and a phase-E-through-H
roadmap update sequencing the work.

Research (docs/research/deepdives/):
- 00-master-synthesis.md          (navigation hub + dependency graph)
- r01-spell-system.md        5.4K words (fizzle sigmoid, 8 tabs, 0x004A wire)
- r02-combat-system.md       5.9K words (damage formula, crit, body table)
- r03-motion-animation.md    8.2K words (450+ commands, 27 hook types)
- r04-vfx-particles.md       5.8K words (13 ParticleType, PhysicsScript)
- r05-audio-sound.md         5.6K words (DirectSound 8, CPU falloff)
- r06-items-inventory.md     7.4K words (ItemType flags, EquipMask 31 slots)
- r07-character-creation.md  6.3K words (CharGen dat, 13 heritages)
- r08-network-protocol-atlas 9.7K words (63+149+94 opcodes mapped)
- r09-dungeon-portal-space.md 6.3K words (EnvCell, PlayerTeleport flow)
- r10-quest-dialogs.md       7.1K words (emote-script VM, 122 actions)
- r11-allegiance.md          5.4K words (tree + XP passup + 5 channels)
- r12-weather-daynight.md    4.5K words (deterministic client-side)
- r13-dynamic-lighting.md    4.9K words (8-light cap, hard Range cutoff)

Every claim cites a FUN_ address, ACE file path, DatReaderWriter type,
or holtburger/ACViewer reference. The master synthesis ties them into a
dependency graph and phase sequence.

Key architectural finding: of 94 GameEvents in the 0xF7B0 envelope,
ZERO are handled today — that's the largest network-protocol gap and
blocks F.2 (items) + F.5 (panels) + H.1 (chat).

C# scaffolds (src/AcDream.Core/):
- Items/ItemInstance.cs    — ItemType/EquipMask enums, ItemInstance,
                             Container, PropertyBundle, BurdenMath
- Spells/SpellModel.cs      — SpellDatEntry, SpellComponentEntry,
                             SpellCastStateMachine, ActiveBuff,
                             SpellMath (fizzle sigmoid + mana cost)
- Combat/CombatModel.cs     — CombatMode/AttackType/DamageType/BodyPart,
                             DamageEvent record, CombatMath (hit-chance
                             sigmoids, power/accuracy mods, damage formula),
                             ArmorBuild
- Audio/AudioModel.cs       — SoundId enum, SoundEntry, WaveData,
                             IAudioEngine / ISoundCache contracts,
                             AudioFalloff (inverse-square)
- Vfx/VfxModel.cs           — 13 ParticleType integrators, EmitterDesc,
                             PhysicsScript + hooks, Particle struct,
                             ParticleEmitter, IParticleSystem contract

All Core-layer data models; platform-backed engines live in AcDream.App.
Compiles clean; 470 tests still pass.

Roadmap (docs/plans/2026-04-11-roadmap.md):
- Phase E — "Feel alive": motion-hooks + audio + VFX
- Phase F — Fight + cast + gear: GameEvent dispatch, inventory,
            combat, spell, core panels
- Phase G — World systems: sky/weather, dynamic lighting, dungeons
- Phase H — Social + progression: chat, allegiance, quests, char creation
- Phase J — Long-tail (renumbered from old Phase E)

Quick-lookup table updated with 10+ new rows mapping observations to
new phase letters.
2026-04-18 10:32:44 +02:00
Erik
7230c1590f docs+feat(ui): retail UI deep-dive research + C# port scaffold
Deep investigation of the retail AC client's GUI subsystem, driven by 6
parallel Opus research agents, plus the first cut of a retail-faithful
retained-mode widget toolkit that scaffolds Phase D.

Research (docs/research/retail-ui/):
- 00-master-synthesis.md        — cross-slice synthesis + port plan
- 01-architecture-and-init.md   — WinMain, CreateMainWindow, frame loop,
                                  Keystone bring-up (7 globals mapped)
- 02-class-hierarchy.md         — key finding: UI lives in keystone.dll,
                                  not acclient.exe; CUIManager + CUIListener
                                  MI pattern, CFont + CSurface + CString
- 03-rendering.md               — 24-byte XYZRHW+UV verts, per-font
                                  256x256 atlas baked from RenderSurface,
                                  TEXTUREFACTOR coloring, DrawPrimitiveUP
- 04-input-events.md            — Win32 WndProc → Device (DAT_00837ff4)
                                  → widget OnEvent(+0x128); full event-type
                                  table (0x01 click, 0x07 tooltip ~1000ms,
                                  0x15 drag-begin, 0x21 enter, 0x3E drop)
- 05-panels.md                  — chat, attributes, skills, spells, paperdoll
                                  (25-slot layout), inventory, fellowship,
                                  allegiance — with wire-message bindings
- 06-hud-and-assets.md          — vital orbs (scissor fill), radar
                                  (0x06001388/0x06004CC1, 1.18× shrink),
                                  compass strip, dat asset catalog

Key insight: keystone.dll owns the actual widget toolkit — we cannot
port a class hierarchy from the decompile because it's not there.
Instead we implement our own retained-mode toolkit with retail-faithful
behavior (event codes, focus/modal/capture, drag-drop state machine)
and will consume the same portal.dat fonts + sprites so the visual
identity is preserved.

C# scaffold (src/AcDream.App/UI/):
- UiEvent          — 24-byte event struct + retail event-type constants
                     (0x01 click, 0x15 drag-begin, 0x201 WM_LBUTTONDOWN,
                     etc.) matching retail decompile switches
- UiElement        — base widget: children, ZOrder, focus/capture flags,
                     virtual OnDraw/OnEvent/OnHitTest/OnTick; children-
                     first hit test + back-to-front composite
- UiPanel          — panel, label, button primitives
- UiRenderContext  — 2D draw context with translate stack
- UiRoot           — top-of-tree + Device responsibilities (mouse/
                     keyboard state, focus, modal, capture, drag-drop,
                     tooltip timer); WorldMouseFallThrough/
                     WorldKeyFallThrough preserves existing camera
                     controls when no widget consumes
- UiHost           — packages UiRoot + TextRenderer + input wiring
                     helpers for one-line integration into GameWindow
- README.md        — orientation for future agents

Roadmap (docs/plans/2026-04-11-roadmap.md):
- D.1 marked shipped (debug overlay from 2026-04-17)
- D.2 expanded to include the retail UI framework landed here
- D.3-D.7 added: AcFont, dat sprites, core panels, HUD, CursorManager
- D.8 remains sound

All existing 470 tests pass. 0 warnings, 0 errors.
2026-04-17 19:13:02 +02:00
Erik
8b4d69fa8d docs(roadmap): mark Phase B.2 (player movement) as shipped
Tab-toggled WASD walking on collision-resolved outdoor terrain with
walk/run/idle animations, third-person chase camera, and outbound
MoveToState + AutonomousPosition server messages. Portal entry works.
Outdoor-only MVP (indoor transition disabled until Phase E portal
detection). 265 tests green.

Phase B status: B.1 ✓, B.2 ✓, B.3 ✓, B.4 pending, B.5 pending.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-12 15:29:28 +02:00
Erik
0aaededdd7 docs(roadmap): mark Phase B.1 + B.3 as shipped
B.1 (ack pump) was already shipped as Phase 4.9 — updated the
roadmap entry to reflect this. B.3 (physics collision engine)
shipped with 4 commits (TerrainSurface, CellSurface, PhysicsEngine,
GameWindow integration). 243 tests green.

Next: B.2 (player movement mode — wire WASD to collision engine
+ outbound server message).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-12 09:59:10 +02:00
Erik
0a20090eba docs(roadmap): mark Phase A.3 (background net receive thread) as shipped
All Foundation sub-pieces now shipped:
  A.1 ✓ Streaming landblock loader
  A.2 ✓ Frustum culling (~160fps)
  A.3 ✓ Background net receive thread
  A.4   Folded into A.1 (deferred — DatCollection not thread-safe)

Phase A (Foundation) is complete. Next: Phase B (Gameplay).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-12 09:24:59 +02:00
Erik
e8c4ac25ba docs(roadmap): mark Phase A.2 (frustum culling) as shipped
~160fps uncapped at 5×5 radius with per-landblock AABB culling.
Perf overlay in window title shows visible/total landblock ratio
so the culling impact is visible at a glance.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-12 09:13:05 +02:00
Erik
bb9ff774dc docs(roadmap): mark Phase A.1 (streaming) shipped; note sync-loader caveat
Move A.1 from "ahead" to "shipped" per the roadmap discipline rule.
The shipped row notes that the loader currently runs synchronously
(the original async-worker design hit DatCollection's lack of thread
safety) and that the Channel-based outbox API is preserved so async
loading can return cleanly when Phase A.3 lands a thread-safe dat
wrapper. Pending-spawn list in GpuWorldState handles live spawn /
streaming races without dropping data.

Quick-lookup table updated:
- "Can't walk past the loaded 3×3 window" → A.1 FIXED ✓
- "Frame hitch crossing landblock boundary" → Phase A.3
  (synchronous loader for now; async returns when DatCollection is
  thread-safe)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-11 23:31:20 +02:00
Erik
2c1c784c8c docs: refresh strategic roadmap + Foundation phase design spec
Output of a brainstorming session after Phase 6/7.1/9.1/9.2 shipped
and the lifestone crystal bug was isolated. Two documents:

1. docs/plans/2026-04-11-roadmap.md — strategic roadmap replacing
   the stale post-Phase-5 version. Reflects what's actually shipped,
   reorganizes upcoming work into Phases A (Foundation), B (Gameplay),
   C (Polish — includes VFX/particles, dynamic lights, palette tuning,
   double-sided translucents), D (UI + Sound), and E (long-tail).
   Updates the "when will my complaint be fixed" quick-lookup with
   the correct phase for portals (VFX, not shader tricks as previously
   claimed), smoke, fireplace fire, and everything we fixed this
   session. Phase ordering: A → B → (C/D in parallel) → E.

2. docs/superpowers/specs/2026-04-11-foundation-phase-design.md —
   detailed implementation spec for Phase A only. Covers the four
   sub-pieces (streaming landblock loader, frustum culling, net I/O
   thread, async dat decoding folded into the streaming worker),
   their components, data flow, error handling, testing strategy,
   and commit-point ordering. Includes non-goals to prevent scope
   creep.

No code changes yet. The spec goes to user review next, then into
the writing-plans skill for a detailed implementation plan.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-11 21:43:33 +02:00
Erik
ac2af96b15 docs(plan): roadmap with every observed defect mapped to a phase
Captures all the "this looks wrong" findings from the Phase 5 visual
verification and assigns each to a future phase. Top-of-document is
phases done, then phases ahead in suggested order, then a quick
lookup table that maps user complaints to their owning phase.

Phases ahead:
  6  Animation system (creature poses, walk/attack motions, breathe-idle)
  7  Multi-floor interiors + dungeons (second floors, foundry interior,
     subterranean rooms)
  8  Player input → server (movement, interact, ack pump, combat)
  9  Visual polish (portals, mesh-origin offsets, exact palette ranges,
     lighting/shadows)
 10  UI / HUD (chat, inventory, character panel, spellbook, minimap)
 11  Sound (SoundTable, audio engine, 3D positional audio)
 12  Streaming + perf (chunked landblock loading, frustum culling, LOD,
     background net thread)

Each phase entry has: what it owns, what it requires, references in the
existing references/ tree, and rough effort estimate.

Document is intentionally a living roadmap — updated whenever a phase
lands or when a new defect is observed that doesn't fit the existing
buckets.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-11 18:30:55 +02:00