# acdream — project instructions for Claude

## Goal

Build **acdream**, a modern open-source C# .NET 10 Asheron's Call client. The
end state is a working client that:

- Loads the retail AC dat files and renders the world (terrain, static meshes,
  dynamic entities, characters)
- Connects to an ACE server and plays as a character
- Exposes a **first-class plugin API** so players can write native scripts and
  macros to automate gameplay — this is a core architectural requirement, not
  a bolt-on

The codebase is organized by phase. Current phase state lives in memory
(`memory/project_phase_*_state.md`), current phase plans live in `docs/plans/`,
and the long-term vision lives in `memory/project_acdream.md`.

## How to operate

**Function as the lead developer on this project.** Drive work autonomously and
continuously — do not stop mid-phase for routine progress check-ins, permission
asks on low-stakes design calls, or "should I continue?" confirmations. Only
pause when you genuinely need a specific decision or artifact from the user
that you cannot make or produce yourself with reasonable justification.

Things to still stop and ask for:

- Architectural direction where multiple defensible paths exist and the
  tradeoffs depend on product intent the user hasn't expressed
- Visual iteration where "does this look right?" is the actual acceptance test
- Destructive or hard-to-reverse actions outside the normal commit workflow
- When memory or commit history clearly indicates the user has a preference
  you should ask about before diverging from

Things you should just do without asking:

- Continue to the next planned sub-step of a phase after the previous one
  lands clean
- Pick between two roughly equivalent implementations; justify the choice in
  the commit message
- Refactor small amounts of surrounding code when genuinely needed to land a
  change cleanly (but not "while I'm here" scope creep)
- Run the test suite, build the project, commit to main with co-author
  attribution — the project's established workflow is direct-to-main and the
  user has repeatedly authorized it

Before claiming a phase or sub-step is done: run `dotnet build` and
`dotnet test` green, commit with a message that explains the "why", update
memory if there's a durable lesson, and move to the next todo item.

## Reference repos: check ALL FOUR, not just one

When researching a protocol detail, dat format, rendering algorithm, or
any "how does AC do X" question, **check all four of the vendored
references in `references/`** before committing to an approach. Do not
settle on the first hit and move on — cross-reference at least two of
these, ideally all four:

- **`references/ACE/`** — ACEmulator server. Authority on the wire
  protocol (packet framing, ISAAC, game message opcodes, serialization
  order). The things a server has to know to parse and produce bytes.
- **`references/ACViewer/`** — MonoGame-based dat viewer that actually
  renders characters + world. Authority on the client-side visual
  pipeline: ObjDesc application, palette overlays, texture decoding
  for the palette-indexed formats. See
  `ACViewer/Render/TextureCache.cs::IndexToColor` for the canonical
  subpalette overlay algorithm.
- **`references/WorldBuilder/`** — C# + Silk.NET dat editor. Exact-stack
  match to acdream for rendering approaches: terrain blending, texture
  atlases, shader patterns. Most useful for "how do I do this GL thing
  with Silk.NET on net10 idiomatically?" Less useful for protocol or
  character appearance (dat editor, not game client).
- **`references/Chorizite.ACProtocol/`** — clean-room C# protocol
  library generated from a protocol XML description. Useful sanity check
  on field order, packed-dword conventions, type-prefix handling. The
  generated Types/*.cs files have accurate field comments (e.g. "If
  it is 0, it defaults to 256*8") that ACE's server-side code doesn't.
- **`references/holtburger/`** — Rust AC client crate. Cross-references
  handshake quirks, race delays, and per-message encoding decisions
  that ACE doesn't document because it's server-side.

Pattern: when you encounter an unknown behavior, grep all four for the
relevant term, read each hit, and compose a multi-source understanding
BEFORE writing acdream code. A single reference can be misleading; the
intersection of all four is almost always the truth. The user has
repeatedly had to remind me about this when I narrowly searched one ref
and missed obvious answers in another.