b9455259f0
Introduces `docs/ISSUES.md` as the tactical rolling list of known bugs + small deferred features. Scope is strict: anything fitting in one-to-two commits lives here; anything larger gets promoted to a Phase in the roadmap. Complement, not replacement, of the strategic roadmap. Schema per issue: - Sequential integer ID (#1, #2, ...) - Status (OPEN / IN-PROGRESS / DONE) - Severity (HIGH / MEDIUM / LOW) - Filed date, component, description, root cause, files, research, acceptance - DONE items move to "Recently closed" at the bottom with commit SHA Four seeded issues from the 2026-04-24 sky-debug session: #1 — Rain falls only to horizon, not to player (weather/particles) #2 — Lightning visual not wired (dat-baked PES triggers; research done) #3 — Client clock drifts from retail after ~10 min (periodic TimeSync) #4 — Sky horizon-glow disabled (fog-mix skipped on sky meshes) CLAUDE.md adds an "Issue tracking" section right after roadmap discipline with the four maintenance rules: (1) scan OPEN at session start, (2) add/close at session end, (3) reference IDs in commit messages, (4) promote to a Phase if an issue grows. Calls out the strategic-vs-tactical split so future sessions know when to reach for the roadmap vs the issues file. README.md gets one line pointing at `docs/ISSUES.md` below the existing roadmap link for first-class discoverability. No code changes; doc-only.
175 lines
7.3 KiB
Markdown
175 lines
7.3 KiB
Markdown
# acdream
|
||
|
||
A modern open-source C# / .NET 10 Asheron's Call client.
|
||
|
||
Faithful port of the retail client's behaviour to Silk.NET with a modern,
|
||
plugin-friendly architecture. The code is modern; the behaviour is retail.
|
||
|
||
**Status:** playable pre-alpha. You can log in to an ACE server, walk and
|
||
run through Dereth, see other players animate correctly, watch the
|
||
day-night cycle, hear ambient audio, and take weapons out. Many systems
|
||
are still stubbed or in-progress — see roadmap.
|
||
|
||
## Stack
|
||
|
||
- **Language:** C# .NET 10
|
||
- **Graphics:** [Silk.NET](https://github.com/dotnet/Silk.NET) (OpenGL 4.3)
|
||
- **Audio:** OpenAL via Silk.NET
|
||
- **Dat parsing:** [Chorizite.DatReaderWriter](https://github.com/Chorizite/DatReaderWriter)
|
||
- **Networking:** Custom UDP + ISAAC cipher + game-message layer, wire-compatible
|
||
with ACEmulator server
|
||
|
||
## What works
|
||
|
||
- Connecting to a local ACEmulator (ACE) server on `127.0.0.1:9000`
|
||
- Character selection and login
|
||
- Rendering Dereth terrain with retail-correct texture blending,
|
||
per-vertex lighting, and road overlays
|
||
- Static scenery (buildings, trees, scenery objects) via EnvCell walker
|
||
- Animated characters (own + remote) with walk / run / strafe / jump /
|
||
turn / attack motions sourced from the retail motion tables
|
||
- Network sync with remote players — you can watch other characters
|
||
animate correctly, including speeds and directional motion
|
||
- Day-night cycle driven from the retail Region dat (0x13000000) —
|
||
correct DayGroup picking via the retail LCG, correct keyframe
|
||
interpolation, correct per-keyframe sky-object replace
|
||
- Weather (rain/snow particles synced from the server via the retail
|
||
DayGroup name)
|
||
- Sky dome, stars, moon, clouds, sun — each rendered from the retail
|
||
Region's SkyObjects with texture scrolling and alpha fade
|
||
- Plugin host with live event replay-on-subscribe
|
||
|
||
## What's stubbed or in-progress
|
||
|
||
- Indoor transitions (building interiors) — disabled, Phase B.3 pending
|
||
- Combat — animation works, damage math not wired
|
||
- Lightning visual — the retail PhysicsScript-driven flash is researched
|
||
but not wired (see `docs/research/2026-04-23-lightning-real.md`)
|
||
- TimeSync drift — we only sync calendar on login, not periodically,
|
||
so acdream's in-game clock gradually drifts from retail's
|
||
- Landscape draw distance — currently `ACDREAM_STREAM_RADIUS=2` (~400m)
|
||
vs retail's several kilometres
|
||
|
||
See `docs/plans/2026-04-11-roadmap.md` for the ordered phase list.
|
||
See `docs/ISSUES.md` for the rolling list of known bugs + small deferred
|
||
features (tactical, bug-level; the roadmap is strategic, phase-level).
|
||
|
||
## Building + running
|
||
|
||
**Requires:**
|
||
- .NET 10 SDK
|
||
- A retail Asheron's Call dat directory (Turbine/Microsoft property —
|
||
supply your own). Contains `client_portal.dat`, `client_cell_1.dat`,
|
||
`client_highres.dat`, `client_local_English.dat`.
|
||
- A running ACE (ACEmulator) server on `127.0.0.1:9000` (or override
|
||
via env var)
|
||
|
||
**Launch (PowerShell on Windows — bash has trouble with the apostrophe
|
||
in "Asheron's Call"):**
|
||
|
||
```powershell
|
||
$env:ACDREAM_DAT_DIR = "$env:USERPROFILE\Documents\Asheron's Call"
|
||
$env:ACDREAM_LIVE = "1"
|
||
$env:ACDREAM_TEST_HOST = "127.0.0.1"
|
||
$env:ACDREAM_TEST_PORT = "9000"
|
||
$env:ACDREAM_TEST_USER = "testaccount"
|
||
$env:ACDREAM_TEST_PASS = "testpassword"
|
||
dotnet run --project src\AcDream.App\AcDream.App.csproj -c Debug
|
||
```
|
||
|
||
Offline CLI dat inspector (no server needed):
|
||
|
||
```
|
||
dotnet run --project src/AcDream.Cli -- "C:\path\to\Asheron's Call"
|
||
```
|
||
|
||
## Diagnostic env vars
|
||
|
||
| Variable | Effect |
|
||
|---|---|
|
||
| `ACDREAM_DUMP_SKY=1` | Per-second dump of the interpolated `SkyKeyframe` values + per-SkyObject draw info + texture alpha histograms |
|
||
| `ACDREAM_DUMP_MOTION=1` | Dump every inbound `UpdateMotion` + resulting `SetCycle` |
|
||
| `ACDREAM_STREAM_RADIUS=N` | Tune landblock visible-window radius (default 2 = 5×5) |
|
||
| `ACDREAM_NO_AUDIO=1` | Suppress OpenAL init |
|
||
| `ACDREAM_DAY_GROUP=N` | Force a specific DayGroup index for A/B-testing weather presets |
|
||
| `ACDREAM_RUN_SKILL=N` / `ACDREAM_JUMP_SKILL=N` | Client-side run/jump skill (default 200) |
|
||
|
||
## Layout
|
||
|
||
```
|
||
src/
|
||
AcDream.App/ rendering + audio + main loop (Silk.NET)
|
||
AcDream.Core/ game state, meshing, physics, sky, weather, lighting
|
||
AcDream.Core.Net/ UDP + ISAAC + game-message layer
|
||
AcDream.Cli/ offline dat-inspector console app
|
||
AcDream.Plugin.Abstractions/ plugin host interfaces
|
||
AcDream.Plugins.Smoke/ example plugin
|
||
|
||
tests/
|
||
AcDream.Core.Tests/ xUnit tests (742 passing)
|
||
AcDream.Core.Net.Tests/ network-layer tests
|
||
|
||
tools/
|
||
RetailTimeProbe/ Win32 P/Invoke ReadProcessMemory probe of
|
||
the live retail acclient.exe — dumps
|
||
TimeOfDay + sky-lighting globals so we
|
||
can compare against acdream's state
|
||
SkyObjectInspect/ dat-inspector for Region sky objects
|
||
|
||
references/ vendored read-only reference code — ACE,
|
||
ACViewer, WorldBuilder, holtburger,
|
||
AC2D, Chorizite, DatReaderWriter.
|
||
Gitignored.
|
||
|
||
docs/
|
||
architecture/ single-source-of-truth architecture doc
|
||
plans/ phase roadmaps + per-phase specs
|
||
research/ decompile-derived research, per-phase
|
||
findings, deep-dive agent reports
|
||
audit/ phase-completion audits
|
||
```
|
||
|
||
## Development workflow
|
||
|
||
All AC-specific behaviour is ported from the decompiled retail client
|
||
(`docs/research/decompiled/`). The workflow is:
|
||
|
||
1. **Decompile first.** Find the matching function in the decompiled
|
||
client.
|
||
2. **Cross-reference.** Check against ACE's C# port and ACViewer /
|
||
WorldBuilder.
|
||
3. **Write pseudocode.** Translate C to readable pseudocode first.
|
||
4. **Port faithfully.** Translate line-by-line, preserving variable
|
||
names and control flow.
|
||
5. **Conformance test.** Add tests using golden values from retail.
|
||
6. **Integrate surgically.** Minimise churn in the surrounding pipeline.
|
||
|
||
Guessing at AC-specific algorithms is explicitly forbidden — see
|
||
`CLAUDE.md` for the full workflow rationale and the list of failure
|
||
modes we've paid for in the past.
|
||
|
||
## Reference repos
|
||
|
||
We cross-reference five external projects for every retail behaviour:
|
||
|
||
- **ACE** (ACEmulator) — authoritative server-side protocol
|
||
- **ACViewer** — MonoGame dat viewer; good for character appearance
|
||
- **WorldBuilder** — Silk.NET dat editor; matches our stack
|
||
- **Chorizite.ACProtocol** — clean-room C# protocol library
|
||
- **holtburger** — most complete non-retail client; Rust TUI, full
|
||
client-side behaviour
|
||
- **AC2D** — C++ AC-client emulator; has the real terrain split
|
||
formula and 0xF61C movement packet format
|
||
|
||
See `CLAUDE.md` for which reference is authoritative for which domain.
|
||
|
||
## Licence
|
||
|
||
Not yet chosen. All external reference code is vendored under its own
|
||
licence; see `references/*/LICENSE`. The acdream source code itself is
|
||
unreleased — not yet distributed to the public. Once the licence
|
||
choice is made it will go in a top-level `LICENSE` file.
|
||
|
||
The AC dat files and the game's intellectual property remain the
|
||
property of Microsoft / Turbine. This project does not distribute any
|
||
of those files or assets — you must supply your own retail install.
|