docs: reconcile project status and navigation
Add a canonical documentation map, modernize the public README, and align milestone, roadmap, architecture, issue, divergence, and session guidance with the July 20 baseline. Correct the far-teleport residual to issue #153, close visually accepted indicator and terrain-tiling work, record the remaining detail-overlay and build-warning debt, and deprecate the duplicate legacy bug ledger. Co-authored-by: OpenAI Codex <codex@openai.com>
This commit is contained in:
Erik
parent
a755b764bf
commit
6c3bd4ce4b
11 changed files with 429 additions and 155 deletions
125
README.md
125
README.md
|
|
@ -5,54 +5,64 @@ 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.
|
||||
**Status:** playable pre-alpha; M3 ("Cast a spell") is active. The connected
|
||||
client supports the complete M2 combat/loot/inventory loop plus retained
|
||||
spellbook, component-book, favorite-spell, enchantment, portal-space, radar,
|
||||
chat, character, and inventory UI. Current work is verification and retail
|
||||
conformance, not a first-playable bring-up.
|
||||
|
||||
Start at the [documentation map](docs/README.md) for the current milestone,
|
||||
roadmap, tactical issues, architecture, retail-divergence register, research,
|
||||
and durable memory.
|
||||
|
||||
## Stack
|
||||
|
||||
- **Language:** C# .NET 10
|
||||
- **Graphics:** [Silk.NET](https://github.com/dotnet/Silk.NET) (OpenGL 4.3)
|
||||
- **Graphics:** [Silk.NET](https://github.com/dotnet/Silk.NET) (OpenGL 4.3
|
||||
context; `GL_ARB_bindless_texture` and `GL_ARB_shader_draw_parameters` are
|
||||
mandatory)
|
||||
- **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
|
||||
## What works today
|
||||
|
||||
- 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
|
||||
- ACE login, character selection, world entry, chat, client commands, and
|
||||
graceful logout.
|
||||
- Outdoor, building, cellar, and dungeon streaming with portal-space travel,
|
||||
terrain/scenery/EnvCell rendering, collision, lighting, sky, fog, audio, and
|
||||
day/night presentation.
|
||||
- Local and observed player/NPC/monster movement, animation, selection, radar,
|
||||
combat stances, melee and missile presentation, death, corpses, chests, and
|
||||
looting.
|
||||
- Inventory bags, stack splitting, paperdoll/equipment, weapon switching,
|
||||
quick bars, item use, giving items to NPCs, and server-authoritative item
|
||||
movement.
|
||||
- Retained retail-style gameplay UI for vitals, chat, toolbar, inventory,
|
||||
character/skills, spellbook/components, helpful/harmful effects, combat and
|
||||
spell bars, radar/compass, indicator pages, and confirmation dialogs.
|
||||
- Spell catalog, learned/favorite spells, component preflight, connected casts,
|
||||
enchantments, DAT-driven missiles/effects, recall, Hidden/UnHide, and portal
|
||||
materialization presentation.
|
||||
- Plugin host, shared input/command abstractions, and permanent ImGui developer
|
||||
tools behind `ACDREAM_DEVTOOLS=1`.
|
||||
|
||||
## What's stubbed or in-progress
|
||||
## Active gaps
|
||||
|
||||
- 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
|
||||
- R6's complete object-frame update path still needs the next local visual
|
||||
comparison; the final M3 gate is a two-client portal-out/materialization
|
||||
observer comparison.
|
||||
- Issue `#225` still needs the lifestone/particle alpha-order visual check,
|
||||
although its connected lifetime/performance gates pass.
|
||||
- Narrow behavior debt remains in issue `#153` (an unstreamed far-teleport
|
||||
edge case), issue `#116` (slide feel), and registered TS-50/TS-51 effect
|
||||
timing.
|
||||
- Many later retail systems remain roadmap work: advanced social/vendor/trade/
|
||||
crafting UI, full weather/lightning parity, deeper combat/stat systems,
|
||||
graphical Linux, and a true headless multi-session bot host.
|
||||
|
||||
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).
|
||||
See [docs/README.md](docs/README.md) for document authority and current links.
|
||||
|
||||
## Building + running
|
||||
|
||||
|
|
@ -74,7 +84,8 @@ $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
|
||||
$env:ACDREAM_RETAIL_UI = "1"
|
||||
dotnet run --project src\AcDream.App\AcDream.App.csproj -c Release
|
||||
```
|
||||
|
||||
Offline CLI dat inspector (no server needed):
|
||||
|
|
@ -89,8 +100,11 @@ dotnet run --project src/AcDream.Cli -- "C:\path\to\Asheron's Call"
|
|||
|---|---|
|
||||
| `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_STREAM_RADIUS=N` | Legacy override for the configured two-tier streaming radii |
|
||||
| `ACDREAM_NO_AUDIO=1` | Suppress OpenAL init |
|
||||
| `ACDREAM_RETAIL_UI=1` | Enable retained retail gameplay UI |
|
||||
| `ACDREAM_DEVTOOLS=1` | Enable ImGui developer tools |
|
||||
| `ACDREAM_UNCAPPED_RENDER=1` | Disable normal presentation pacing for throughput measurement |
|
||||
| `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) |
|
||||
|
||||
|
|
@ -98,16 +112,20 @@ dotnet run --project src/AcDream.Cli -- "C:\path\to\Asheron's Call"
|
|||
|
||||
```
|
||||
src/
|
||||
AcDream.App/ rendering + audio + main loop (Silk.NET)
|
||||
AcDream.Core/ game state, meshing, physics, sky, weather, lighting
|
||||
AcDream.App/ window, retained UI, rendering, audio, runtime wiring
|
||||
AcDream.Content/ GL-free DAT mesh/texture extraction
|
||||
AcDream.Core/ game state, physics, movement, world, gameplay logic
|
||||
AcDream.Core.Net/ UDP + ISAAC + game-message layer
|
||||
AcDream.UI.Abstractions/ shared UI/input ViewModels, commands, contracts
|
||||
AcDream.UI.ImGui/ permanent developer-tool renderer
|
||||
AcDream.Cli/ offline dat-inspector console app
|
||||
AcDream.Bake/ offline content bake tooling
|
||||
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
|
||||
AcDream.*.Tests/ layer-matched xUnit projects (6,452 passing,
|
||||
5 intentional skips at the 2026-07-20 baseline)
|
||||
|
||||
tools/
|
||||
RetailTimeProbe/ Win32 P/Invoke ReadProcessMemory probe of
|
||||
|
|
@ -122,7 +140,8 @@ references/ vendored read-only reference code — ACE,
|
|||
Gitignored.
|
||||
|
||||
docs/
|
||||
architecture/ single-source-of-truth architecture doc
|
||||
README.md documentation map + authority order
|
||||
architecture/ architecture, structure, divergence, WB inventory
|
||||
plans/ phase roadmaps + per-phase specs
|
||||
research/ decompile-derived research, per-phase
|
||||
findings, deep-dive agent reports
|
||||
|
|
@ -131,18 +150,20 @@ docs/
|
|||
|
||||
## Development workflow
|
||||
|
||||
All AC-specific behaviour is ported from the decompiled retail client
|
||||
(`docs/research/decompiled/`). The workflow is:
|
||||
All AC-specific behaviour is ported from the named retail client oracle
|
||||
(`docs/research/named-retail/`). 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 /
|
||||
1. **Grep named retail first.** Find the matching `class::method` in the
|
||||
Sept 2013 named pseudo-C and headers.
|
||||
2. **Decompile only as fallback.** Use the older Ghidra chunks when the named
|
||||
oracle lacks the function.
|
||||
3. **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
|
||||
4. **Write pseudocode.** Translate C to readable pseudocode first.
|
||||
5. **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.
|
||||
6. **Conformance test.** Add tests using golden values from retail.
|
||||
7. **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
|
||||
|
|
@ -150,7 +171,7 @@ modes we've paid for in the past.
|
|||
|
||||
## Reference repos
|
||||
|
||||
We cross-reference five external projects for every retail behaviour:
|
||||
We cross-reference six external projects for retail behavior:
|
||||
|
||||
- **ACE** (ACEmulator) — authoritative server-side protocol
|
||||
- **ACViewer** — MonoGame dat viewer; good for character appearance
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue