erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

refactor(app): extract typed RuntimeOptions for startup env vars (Step 1)

Browse source 
Lifts 13 startup-time environment variables out of GameWindow.cs into a
single typed AcDream.App.RuntimeOptions record read once in Program.cs.
Behavior-preservation only — no live behavior change, no visual change.
Verified end-to-end against ACE on 127.0.0.1:9000: full M1 demo loop
(walk Holtburg, click door, click NPC, portal entry) plus DEVTOOLS
ImGui panels load cleanly.

Why: GameWindow.cs is 10,304 LOC and scattered Environment.GetEnvironmentVariable
calls were one of the structural smells called out in the new
"Code Structure Rules" doc. Typed options is the safest cut to make
first because the substitution is mechanical and parsing semantics
get pinned by unit tests.

What lands:
  - CLAUDE.md: removed stale R1→R8 execution-phases line, replaced with
    pointers to the milestones doc + strategic roadmap (the actual
    source of truth). Tightened the "check ALL FOUR references"
    section to describe WB as the production rendering base, not
    just a reference. New "Code Structure Rules" section (6 rules)
    captures the discipline we're committing to.
  - docs/architecture/acdream-architecture.md: removed dangling link
    to the deleted memory/project_ui_architecture.md.
  - docs/architecture/code-structure.md (NEW, 376 LOC): rationale for
    the 6 rules + 6-step extraction sequence
    (RuntimeOptions → LiveSessionController → LiveEntityRuntime →
    SelectionInteractionController → RenderFrameOrchestrator →
    GameEntity aggregation). This PR is Step 1.
  - src/AcDream.App/RuntimeOptions.cs (NEW, 100 LOC): typed record
    with FromEnvironment(string) factory and Parse(datDir, env)
    overload for testability. Covers ACDREAM_LIVE, _TEST_HOST/PORT/
    USER/PASS, _DEVTOOLS, _DUMP_MOVE_TRUTH, _NO_AUDIO,
    _ENABLE_SKY_PES, _HIDE_PART, _RETAIL_CLOSE_DEGRADES,
    _DUMP_SCENERY_Z, _STREAM_RADIUS.
  - src/AcDream.App/Program.cs: builds RuntimeOptions once, passes
    to GameWindow.
  - src/AcDream.App/Rendering/GameWindow.cs: ctor takes RuntimeOptions;
    7 startup-cached env-var fields become expression-bodied
    properties or direct _options.X reads; TryStartLiveSession,
    audio init, legacy stream-radius branch all route through
    _options.
  - tests/AcDream.App.Tests/ (NEW project, 10 unit tests + csproj):
    pins parser semantics — default-off bools, the literal "0"
    gate for RETAIL_CLOSE_DEGRADES, the >=0 guard for
    STREAM_RADIUS, null-vs-empty for user/pass, exact-"1" check
    for diagnostic flags. Registered in AcDream.slnx.

Out of scope (per code-structure.md §4):
  - Per-call-site ACDREAM_DUMP_* / _REMOTE_VEL_DIAG diagnostic reads
    sprinkled through GameWindow (~40 sites). Rule 5 in CLAUDE.md
    commits us to migrating these opportunistically as larger
    extractions land, not in a bulk pass.
  - AcDream.Core's project-reference to Chorizite.OpenGLSDLBackend.
    Only the stateless .Lib namespace is used; tightening the project
    reference is documented as future work in code-structure.md §2.

Build: green.
Tests: AcDream.App.Tests 10/10 ✓, Core.Net.Tests 294/294 ✓,
       UI.Abstractions.Tests 419/419 ✓,
       AcDream.Core.Tests 1073/1081 (8 pre-existing failures verified
       against pre-refactor baseline by stash-and-rerun).

Visual verification: full M1 demo loop against ACE +Acdream login
including DEVTOOLS panel host load.

Next: Step 2 — extract LiveSessionController per code-structure.md §4.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik 2026-05-17 09:16:55 +02:00
parent 2950cd5740
commit eda936dc4d
9 changed files with 863 additions and 63 deletions
Download patch file Download diff file Expand all files Collapse all files

8
src/AcDream.App/Program.cs
View file

@ -1,3 +1,4 @@
using AcDream.App;
using AcDream.App.Plugins;
using AcDream.App.Rendering;
using AcDream.Core.Plugins;
@ -15,6 +16,11 @@ if (string.IsNullOrWhiteSpace(datDir))
return 2;
}
// Single read of the startup-time process environment. Every downstream
// consumer (GameWindow + collaborators) reads the typed bundle, not the
// raw env vars. See docs/architecture/code-structure.md §2 Rule 4.
var runtimeOptions = RuntimeOptions.FromEnvironment(datDir);
var worldGameState = new AcDream.Core.Plugins.WorldGameState();
var worldEvents = new AcDream.Core.Plugins.WorldEvents();
var host = new AppPluginHost(new SerilogAdapter(Log.Logger), worldGameState, worldEvents);
@ -50,7 +56,7 @@ try
catch (Exception ex) { Log.Error(ex, "plugin enable failed: {Id}", plugin.Manifest.Id); }
}
using var window = new GameWindow(datDir, worldGameState, worldEvents);
using var window = new GameWindow(runtimeOptions, worldGameState, worldEvents);
window.Run();
}
finally

69
src/AcDream.App/Rendering/GameWindow.cs
View file

@ -12,6 +12,7 @@ public sealed class GameWindow : IDisposable
{
private readonly record struct SkyPesKey(int ObjectIndex, uint PesObjectId, bool PostScene);
private readonly AcDream.App.RuntimeOptions _options;
private readonly string _datDir;
private readonly WorldGameState _worldGameState;
private readonly WorldEvents _worldEvents;
@ -219,12 +220,10 @@ public sealed class GameWindow : IDisposable
// Retail GameSky copies SkyObject.PesObjectId into CelestialPosition but
// never consumes it in CreateDeletePhysicsObjects/MakeObject/UseTime.
// Keep the experimental path available for DAT archaeology only.
private readonly bool _enableSkyPesDebug =
string.Equals(Environment.GetEnvironmentVariable("ACDREAM_ENABLE_SKY_PES"), "1", StringComparison.Ordinal);
// Backed by ACDREAM_ENABLE_SKY_PES via RuntimeOptions.EnableSkyPesDebug.
// Diagnostic: hide a specific humanoid part (>=10 parts) at render.
private static readonly int s_hidePartIndex =
int.TryParse(Environment.GetEnvironmentVariable("ACDREAM_HIDE_PART"), out var hp) ? hp : -1;
// Backed by ACDREAM_HIDE_PART via RuntimeOptions.HidePartIndex.
// Issue #47 — use retail's close-detail GfxObj selection on
// humanoid setups. When enabled, every per-part GfxObj id (after
@ -233,8 +232,7 @@ public sealed class GameWindow : IDisposable
// for the full retail-decomp citation. Default-on after visual
// confirmation; set ACDREAM_RETAIL_CLOSE_DEGRADES=0 only for
// diagnostic before/after comparisons.
private static readonly bool s_retailCloseDegrades =
!string.Equals(Environment.GetEnvironmentVariable("ACDREAM_RETAIL_CLOSE_DEGRADES"), "0", StringComparison.Ordinal);
// Backed by ACDREAM_RETAIL_CLOSE_DEGRADES via RuntimeOptions.RetailCloseDegrades.
// Issue #48 diagnostic — dump per-scenery-spawn placement evidence
// (rendered gfx id, sample source physics-vs-bilinear, ground/baseLoc/finalZ,
@ -242,8 +240,7 @@ public sealed class GameWindow : IDisposable
// the user identify a floating tree by its world coordinates and tell
// whether the cause is BaseLoc.Z addition (H1), bilinear-fallback drift
// (H2), or DIDDegrade selection (H3). Diagnostic-first per CLAUDE.md.
private static readonly bool s_dumpSceneryZ =
string.Equals(Environment.GetEnvironmentVariable("ACDREAM_DUMP_SCENERY_Z"), "1", StringComparison.Ordinal);
// Backed by ACDREAM_DUMP_SCENERY_Z via RuntimeOptions.DumpSceneryZ.
/// <summary>
/// Issue #47 humanoid-setup detector. Matches Aluvian Male
@ -575,10 +572,11 @@ public sealed class GameWindow : IDisposable
// _panelHost does. Self-subscribes to CombatState in its ctor, so
// disposing isn't required (panel host holds the only ref).
private AcDream.UI.Abstractions.Panels.Debug.DebugVM? _debugVm;
private static readonly bool DevToolsEnabled =
Environment.GetEnvironmentVariable("ACDREAM_DEVTOOLS") == "1";
private static readonly bool DumpMoveTruthEnabled =
Environment.GetEnvironmentVariable("ACDREAM_DUMP_MOVE_TRUTH") == "1";
// DevToolsEnabled + DumpMoveTruthEnabled now read through _options
// (RuntimeOptions.DevTools / DumpMoveTruth). Kept the same names for
// local readability via expression-bodied properties.
private bool DevToolsEnabled => _options.DevTools;
private bool DumpMoveTruthEnabled => _options.DumpMoveTruth;
// Phase I.3 — real ICommandBus for live sessions. Constructed when
// the live session spins up (so SendChatCmd handlers can close over
@ -748,8 +746,8 @@ public sealed class GameWindow : IDisposable
// K-fix1 (2026-04-26): cached at startup so per-frame branches are
// single-flag reads instead of env-var lookups. True iff
// ACDREAM_LIVE=1 was set when the window came up.
private static readonly bool LiveModeEnabled =
Environment.GetEnvironmentVariable("ACDREAM_LIVE") == "1";
// Backed by RuntimeOptions.LiveMode via the _options field.
private bool LiveModeEnabled => _options.LiveMode;
/// <summary>
/// K-fix1 (2026-04-26): true iff live mode is configured AND we have
@ -814,9 +812,10 @@ public sealed class GameWindow : IDisposable
private int _liveAnimRejectSingleFrame;
private int _liveAnimRejectPartFrames;
public GameWindow(string datDir, WorldGameState worldGameState, WorldEvents worldEvents)
public GameWindow(AcDream.App.RuntimeOptions options, WorldGameState worldGameState, WorldEvents worldEvents)
{
_datDir = datDir;
_options = options ?? throw new System.ArgumentNullException(nameof(options));
_datDir = options.DatDir;
_worldGameState = worldGameState;
_worldEvents = worldEvents;
SpellBook = new AcDream.Core.Spells.Spellbook(SpellTable);
@ -1104,7 +1103,7 @@ public sealed class GameWindow : IDisposable
// Phase E.2 audio: init OpenAL + hook sink. Suppressible via
// ACDREAM_NO_AUDIO=1 for headless tests / broken audio drivers.
if (Environment.GetEnvironmentVariable("ACDREAM_NO_AUDIO") != "1")
if (!_options.NoAudio)
{
try
{
@ -1749,15 +1748,13 @@ public sealed class GameWindow : IDisposable
_farRadius = _resolvedQuality.FarRadius;
// Legacy override: ACDREAM_STREAM_RADIUS acts as nearRadius and
// ensures farRadius >= streamRadius.
// ensures farRadius >= streamRadius. Parsed once into
// RuntimeOptions.LegacyStreamRadius (null when unset or invalid).
if (_options.LegacyStreamRadius is { } sr)
{
var legacyEnv = Environment.GetEnvironmentVariable("ACDREAM_STREAM_RADIUS");
if (int.TryParse(legacyEnv, out var sr) && sr >= 0)
{
_nearRadius = sr;
_streamingRadius = sr; // keep debug overlay in sync
_farRadius = System.Math.Max(sr, _farRadius);
}
_nearRadius = sr;
_streamingRadius = sr; // keep debug overlay in sync
_farRadius = System.Math.Max(sr, _farRadius);
}
Console.WriteLine(
$"streaming: nearRadius={_nearRadius} (window={2*_nearRadius+1}x{2*_nearRadius+1})" +
@ -1822,12 +1819,12 @@ public sealed class GameWindow : IDisposable
private void TryStartLiveSession()
{
if (Environment.GetEnvironmentVariable("ACDREAM_LIVE") != "1") return;
if (!_options.LiveMode) return;
var host = Environment.GetEnvironmentVariable("ACDREAM_TEST_HOST") ?? "127.0.0.1";
var portStr = Environment.GetEnvironmentVariable("ACDREAM_TEST_PORT") ?? "9000";
var user = Environment.GetEnvironmentVariable("ACDREAM_TEST_USER");
var pass = Environment.GetEnvironmentVariable("ACDREAM_TEST_PASS");
var host = _options.LiveHost;
var port = _options.LivePort;
var user = _options.LiveUser;
var pass = _options.LivePass;
if (string.IsNullOrEmpty(user) || string.IsNullOrEmpty(pass))
{
Console.WriteLine("live: ACDREAM_LIVE set but TEST_USER/TEST_PASS missing; skipping");
@ -1850,7 +1847,7 @@ public sealed class GameWindow : IDisposable
$"DNS resolved no addresses for '{host}'"));
Console.WriteLine($"live: resolved {host} → {ip}");
}
var endpoint = new System.Net.IPEndPoint(ip, int.Parse(portStr));
var endpoint = new System.Net.IPEndPoint(ip, port);
Console.WriteLine($"live: connecting to {endpoint} as {user}");
_liveSession = new AcDream.Core.Net.WorldSession(endpoint);
_liveSession.EntitySpawned += OnLiveEntitySpawned;
@ -2123,7 +2120,7 @@ public sealed class GameWindow : IDisposable
_liveSession.VitalCurrentUpdated += v =>
LocalPlayer.OnVitalCurrent(v.VitalId, v.Current);
Chat.OnSystemMessage($"connecting to {host}:{portStr} as {user}", chatType: 1);
Chat.OnSystemMessage($"connecting to {host}:{port} as {user}", chatType: 1);
_liveSession.Connect(user, pass);
Chat.OnSystemMessage("connected — character list received", chatType: 1);
@ -2480,7 +2477,7 @@ public sealed class GameWindow : IDisposable
// changes resolve (which match against the resolved mesh's
// surfaces) and BEFORE the GfxObjMesh.Build / texture upload
// path consumes the part list.
if (s_retailCloseDegrades && IsIssue47HumanoidSetup(setup))
if (_options.RetailCloseDegrades && IsIssue47HumanoidSetup(setup))
{
for (int partIdx = 0; partIdx < parts.Count; partIdx++)
{
@ -5210,7 +5207,7 @@ public sealed class GameWindow : IDisposable
// (physics-vs-bilinear sampler drift), and H3 (DIDDegrade slot 0).
// User identifies a floating tree visually, finds the matching
// line by world coords + gfx id, the data picks the hypothesis.
if (s_dumpSceneryZ)
if (_options.DumpSceneryZ)
{
string source = maybePhysicsZ.HasValue ? "physics" : "bilinear";
foreach (var mr in meshRefs)
@ -6798,7 +6795,7 @@ public sealed class GameWindow : IDisposable
// retail decomp confirms SkyObject.PesObjectId is copied by
// SkyDesc::GetSky but ignored by GameSky, so the sky-PES path is
// debug-only and disabled for normal retail rendering.
if (_enableSkyPesDebug)
if (_options.EnableSkyPesDebug)
UpdateSkyPes((float)WorldTime.DayFraction, _activeDayGroup, camPos, cameraInsideCell);
_scriptRunner?.Tick((float)deltaSeconds);
_particleSystem?.Tick((float)deltaSeconds);
@ -7978,7 +7975,7 @@ public sealed class GameWindow : IDisposable
partTransform = partTransform * scaleMat;
var template = ae.PartTemplate[i];
if (s_hidePartIndex >= 0 && i == s_hidePartIndex && partCount >= 10)
if (_options.HidePartIndex >= 0 && i == _options.HidePartIndex && partCount >= 10)
{
continue;
}

100
src/AcDream.App/RuntimeOptions.cs Normal file
View file

@ -0,0 +1,100 @@
using System;
using System.Globalization;
namespace AcDream.App;
/// <summary>
/// Typed bundle of startup-time configuration read from the process
/// environment. Built once in <c>Program.cs</c> and passed to
/// <c>GameWindow</c> so the rest of the app reads its config through
/// strongly-typed fields instead of scattered
/// <c>Environment.GetEnvironmentVariable</c> calls.
/// </summary>
/// <remarks>
/// <para>
/// <strong>Scope:</strong> startup-time only — values that don't change
/// once the window is up. Runtime diagnostic toggles
/// (e.g. <c>ACDREAM_DUMP_MOTION</c>, <c>ACDREAM_PROBE_*</c>) belong in
/// diagnostic owner classes (see <c>AcDream.Core.Physics.PhysicsDiagnostics</c>
/// for the template), not here.
/// </para>
/// <para>
/// See <c>docs/architecture/code-structure.md</c> §2 Rule 4 for the
/// rule that drove this extraction, and §4 Step 1 for the broader
/// extraction sequence this is the first cut of.
/// </para>
/// </remarks>
public sealed record RuntimeOptions(
string DatDir,
bool LiveMode,
string LiveHost,
int LivePort,
string? LiveUser,
string? LivePass,
bool DevTools,
bool DumpMoveTruth,
bool NoAudio,
bool EnableSkyPesDebug,
int HidePartIndex,
bool RetailCloseDegrades,
bool DumpSceneryZ,
int? LegacyStreamRadius)
{
/// <summary>
/// Build options from the process environment. Used by
/// <c>Program.cs</c> at startup.
/// </summary>
public static RuntimeOptions FromEnvironment(string datDir)
=> Parse(datDir, Environment.GetEnvironmentVariable);
/// <summary>
/// Build options from a custom environment getter. Used by tests to
/// inject controlled env values without touching the process
/// environment.
/// </summary>
/// <param name="datDir">Resolved dat-file directory.</param>
/// <param name="env">Function returning the value for an env-var
/// name, or <c>null</c> when unset.</param>
public static RuntimeOptions Parse(string datDir, Func<string, string?> env)
{
if (datDir is null) throw new ArgumentNullException(nameof(datDir));
if (env is null) throw new ArgumentNullException(nameof(env));
return new RuntimeOptions(
DatDir: datDir,
LiveMode: IsExactlyOne(env("ACDREAM_LIVE")),
LiveHost: env("ACDREAM_TEST_HOST") ?? "127.0.0.1",
LivePort: TryParseInt(env("ACDREAM_TEST_PORT")) ?? 9000,
LiveUser: NullIfEmpty(env("ACDREAM_TEST_USER")),
LivePass: NullIfEmpty(env("ACDREAM_TEST_PASS")),
DevTools: IsExactlyOne(env("ACDREAM_DEVTOOLS")),
DumpMoveTruth: IsExactlyOne(env("ACDREAM_DUMP_MOVE_TRUTH")),
NoAudio: IsExactlyOne(env("ACDREAM_NO_AUDIO")),
EnableSkyPesDebug: IsExactlyOne(env("ACDREAM_ENABLE_SKY_PES")),
HidePartIndex: TryParseInt(env("ACDREAM_HIDE_PART")) ?? -1,
// Default-on: any value other than the literal string "0" enables
// retail close-detail degrades. Set ACDREAM_RETAIL_CLOSE_DEGRADES=0
// only for before/after diagnostic comparisons.
RetailCloseDegrades: !string.Equals(env("ACDREAM_RETAIL_CLOSE_DEGRADES"), "0", StringComparison.Ordinal),
DumpSceneryZ: IsExactlyOne(env("ACDREAM_DUMP_SCENERY_Z")),
// Legacy override for ACDREAM_STREAM_RADIUS. Caller applies it on
// top of the quality preset's radii. Null when unset or invalid.
LegacyStreamRadius: TryParseNonNegativeInt(env("ACDREAM_STREAM_RADIUS")));
}
/// <summary>True iff live-mode credentials are present and valid for connecting.</summary>
public bool HasLiveCredentials =>
LiveMode && !string.IsNullOrEmpty(LiveUser) && !string.IsNullOrEmpty(LivePass);
private static bool IsExactlyOne(string? s)
=> string.Equals(s, "1", StringComparison.Ordinal);
private static string? NullIfEmpty(string? s)
=> string.IsNullOrEmpty(s) ? null : s;
private static int? TryParseInt(string? s)
=> int.TryParse(s, NumberStyles.Integer, CultureInfo.InvariantCulture, out var v) ? v : null;
private static int? TryParseNonNegativeInt(string? s)
=> TryParseInt(s) is { } v && v >= 0 ? v : null;
}