From b9455259f02151baa0fbe07febace0fb5ded841d Mon Sep 17 00:00:00 2001 From: Erik Date: Sat, 25 Apr 2026 00:08:15 +0200 Subject: [PATCH] docs: add docs/ISSUES.md tactical issue tracker + CLAUDE.md rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- CLAUDE.md | 21 +++++++ README.md | 2 + docs/ISSUES.md | 153 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 176 insertions(+) create mode 100644 docs/ISSUES.md diff --git a/CLAUDE.md b/CLAUDE.md index c5889c1..84c1d80 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -229,6 +229,27 @@ acdream's plan lives in two files committed to the repo: The roadmap is not sacred — it changes. It IS the source of truth at any given moment. When it's wrong, fix it. When it's right, follow it. +## Issue tracking — `docs/ISSUES.md` + +Tactical rolling list of known bugs + small deferred features. Scope: +anything that fits in one-to-two commits; larger work stays as a Phase +in the roadmap. Maintenance rules: + +1. **Start-of-session:** scan OPEN issues in `docs/ISSUES.md` — any of + them in the area you're about to touch? Plan accordingly. +2. **End-of-session:** if this session observed a defect and didn't fix + it inline, add an issue. If this session fixed an OPEN issue, move + it to **Recently closed** with the commit SHA. +3. **Commit messages:** reference issue IDs when a commit closes one + (`fix #3: periodic TimeSync parsing`). Makes `git log --grep='#3'` + return the full fix history. +4. **Promotion:** if an issue grows into multi-commit work, promote it + to a Phase in the roadmap. Close the issue as + `DONE (promoted to Phase X)` and reference the roadmap commit. + +The roadmap is strategic (month-scale, phase-level). ISSUES is tactical +(week-scale, bug-level). They reference each other but don't duplicate. + ## Running the client against the live server The user runs a **local ACE (Asheron's Call Emulator) server on diff --git a/README.md b/README.md index 47a5330..56fa126 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,8 @@ are still stubbed or in-progress — see roadmap. 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 diff --git a/docs/ISSUES.md b/docs/ISSUES.md new file mode 100644 index 0000000..38d52ec --- /dev/null +++ b/docs/ISSUES.md @@ -0,0 +1,153 @@ +# acdream — known issues + small deferred features + +Rolling tactical list. What goes here: + +- **Bugs**: user-visible defects we've observed but haven't fixed yet. +- **Small deferred features**: work that fits in one or two commits. + Anything larger should be a named Phase in the [roadmap](plans/2026-04-11-roadmap.md). + +What does NOT go here: + +- Large multi-commit work → add a Phase to the roadmap instead. +- Ideas / wishlist → `docs/plans/`. +- Design questions → open a `docs/research/*.md` note. + +## Conventions + +- Sequential integer IDs (`#1`, `#2`, …). Commits that close an issue reference the ID in the message (e.g. `fix #3: periodic TimeSync parsing`). +- `Status` is `OPEN`, `IN-PROGRESS`, or `DONE`. DONE items move to the **Recently closed** section at the bottom with closed-date + commit SHA. +- Every session: scan OPEN issues at start; promote/close anything we touched during the session before ending. +- Promoting to a Phase: mark as `DONE (promoted to Phase X)` + commit SHA where the Phase entry landed. + +## Template + +Copy this block when adding a new issue: + +``` +## #NN — Short title + +**Status:** OPEN +**Severity:** HIGH | MEDIUM | LOW +**Filed:** YYYY-MM-DD +**Component:** e.g. sky, physics, net, ui + +**Description:** One paragraph — what's wrong or what's missing. + +**Root cause / status:** What we know so far. Empty if unknown. + +**Files:** Path references with approximate line numbers. + +**Research:** Links to `docs/research/*.md` if applicable. + +**Acceptance:** How we'll know it's fixed. +``` + +--- + +# Active issues + +## #1 — Rain falls only to horizon, not to the player's feet + +**Status:** OPEN +**Severity:** MEDIUM +**Filed:** 2026-04-25 +**Component:** weather / particles + +**Description:** During Rainy DayGroups, rain particles are visible in the upper sky band but fade out before reaching the camera / ground level. Retail's rain falls all the way past the camera to the terrain. + +**Root cause / status:** Unknown. Likely one of: (a) particle emitter volume too short in Z, (b) particle lifetime shorter than the time it takes to traverse emitter-top → ground, (c) emitter anchored in world-space so particles escape the player's reference frame as they fall, (d) camera-relative spawn origin is offset too high above the player. + +**Files:** +- `src/AcDream.App/Rendering/GameWindow.cs` — `UpdateWeatherParticles` (~line 4591) +- `src/AcDream.Core/Vfx/ParticleSystem.cs` — emitter spawn config + lifetime integration + +**Research:** `docs/research/deepdives/r12-weather-daynight.md` (rain mechanism — but does not pin volume / lifetime values). + +**Acceptance:** Standing at 9,115 in Holtburg during a Rainy DayGroup, rain drops visibly fall all the way from the sky band past the camera to the ground level. + +--- + +## #2 — Lightning visual not wired (dat-baked PES triggers) + +**Status:** OPEN +**Severity:** MEDIUM +**Filed:** 2026-04-25 +**Component:** weather / sky / vfx + +**Description:** Retail's Rainy DayGroup in the Dereth Region dat contains 12+ `SkyObject` entries with non-zero `PesObjectId` and narrow visibility windows (5–70 ms at keyframe-boundary moments) that drive PhysicsScript-authored flash + thunder effects. We render the sky meshes but ignore the PES path, so no lightning flashes appear during storms. The fragment-shader flash bump on `uFogParams.z` is already wired in `sky.frag` — only the CPU-side PES→runner wire is missing. + +**Root cause / status:** Research complete. Implementation is: in `SkyRenderer.Render`, detect visibility-window entry on any SkyObject with `obj.PesObjectId != 0`, call `PhysicsScriptRunner.Play(pesObjectId, ownerId: sky-owner, anchorPos: camera)`, and route any `SetFlash` / `Sound` hooks from the script into `uFogParams.z` + audio. + +**Files:** +- `src/AcDream.App/Rendering/Sky/SkyRenderer.cs` — add per-SkyObject PES dispatch inside the visibility loop +- `src/AcDream.Core/Vfx/PhysicsScriptRunner.cs` — already shipped (Phase 6a); exposes `Play(scriptId, entityId, anchorWorldPos)` +- `src/AcDream.Core/Lighting/SceneLightingUbo.cs` — `FogParams.Z` is the flash slot; needs a sink that bumps it and decays +- `src/AcDream.App/Rendering/Shaders/sky.frag` — flash bump already wired (`rgb += flash * vec3(1.5, 1.5, 1.8)`) + +**Research:** +- `docs/research/2026-04-23-lightning-real.md` (decompile trace + dat discovery) +- `docs/research/2026-04-23-physicsscript.md` (runtime semantics) +- `docs/research/2026-04-23-lightning-crossfade.md` (crossfade mechanism) + +**Acceptance:** During a Rainy DayGroup's storm window, visible flashes appear in the sky at the dat-scripted moments, the fragment-shader flash bump briefly brightens the scene, and (later, once thunder audio is wired) a thunder clap plays with a short propagation delay. + +--- + +## #3 — Client clock drifts from retail after ~10 minutes (periodic TimeSync missing) + +**Status:** OPEN +**Severity:** MEDIUM +**Filed:** 2026-04-25 +**Component:** net / sky + +**Description:** Our `WorldTimeService.DayFraction` syncs with the server once at login via `ConnectRequest + TimeSync`, then advances from the local wall-clock. Retail receives periodic `TimeSync` refreshes (header flag `0x1000000`) carrying a fresh `PortalYearTicks double` and re-anchors its clock. Without those, acdream's keyframe state drifts from retail's over 10+ minutes — observed during the 2026-04-24 sky-color debug sessions where retail was at DayFraction 0.976 while acdream was at 0.634. + +**Root cause / status:** Mechanism is well-understood (see research). `WorldTimeService.SyncFromServer(double)` already exists — we just need to detect the periodic flag in the packet header and call it whenever a fresh tick arrives. + +**Files:** +- `src/AcDream.Core.Net/WorldSession.cs` — header-flag parsing; currently only the initial sync is consumed +- `src/AcDream.Core/World/WorldTimeService.cs` — `SyncFromServer(double ticks)` ready; needs caller wiring + +**Research:** `docs/research/deepdives/r12-weather-daynight.md` §TimeSync (line ~563). References retail packet-header flag `0x1000000` carrying `PortalYearTicks double`. + +**Acceptance:** Probe retail via `tools/RetailTimeProbe` and acdream's ACDREAM_DUMP_SKY log at the same wall-clock moment after a 20-minute session without re-login; `abs(acdream.DayFraction - retail.DayFraction) < 0.01`. + +--- + +## #4 — Sky horizon-glow disabled (fog-mix skipped on sky meshes) + +**Status:** OPEN +**Severity:** LOW (aesthetic feature-parity, not regression from pre-session state) +**Filed:** 2026-04-25 +**Component:** sky + +**Description:** Phase 8.1 (commit `593b76f`) disabled the fog-mix on sky meshes to fix the "entire dome swallowed by fog color" regression. Dereth's keyframe `FogEnd` values (0–2400 m) are calibrated for terrain; sky meshes are authored at radii 1050–14271 m so every sky pixel was past `FogEnd`, saturated to `uFogColor`, destroying stars / moon / dome texture. Disabling the mix restored visibility but we lost retail's horizon-glow effect (gradient from clear zenith to fog-tinted horizon band at dusk/dawn). + +**Root cause / status:** Three competing hypotheses, none pinned down: (a) retail uses a **different** fog range for sky than terrain; (b) retail applies fog with an **elevation-angle** weighting rather than linear distance; (c) retail's sky meshes **don't participate** in the global fog and the "horizon glow" comes from a different atmospheric-scatter path. Need to identify retail's actual sky-fog behaviour before re-enabling with correct parameters. + +**Files:** +- `src/AcDream.App/Rendering/Shaders/sky.frag` — line ~55, `rgb = mix(uFogColor.rgb, rgb, vFogFactor)` currently commented out +- `src/AcDream.App/Rendering/Shaders/sky.vert` — lines 109-114, `vFogFactor` computation + +**Research:** `docs/research/2026-04-23-sky-fog.md`. Partial; doesn't pin the sky-specific fog path. + +**Acceptance:** At dusk in Holtburg, the sky dome shows a clear zenith and a warm fog-tinted horizon band that matches retail's appearance, with stars / moon / sun / clouds all still visible at their correct brightnesses elsewhere in the frame. + +--- + +# Recently closed + +*(none yet — move DONE items here with closed-date + commit SHA)* + +