From 7e7d91e5b2d4443cef924164d8e2b73cdbd29e52 Mon Sep 17 00:00:00 2001 From: Soar Qin Date: Sun, 18 Oct 2026 18:10:10 +0800 Subject: [PATCH] chore: remove obsoleted docs --- docs/GameCompatibility-0.10.35.29131.md | 55 - docs/GameCompatibility-0.10.35.md | 65 - ...2026-06-23-phase5-transpiler-robustness.md | 334 ---- ...06-23-refactor-uxassist-cheate-universe.md | 1367 ----------------- 4 files changed, 1821 deletions(-) delete mode 100644 docs/GameCompatibility-0.10.35.29131.md delete mode 100644 docs/GameCompatibility-0.10.35.md delete mode 100644 docs/superpowers/plans/2026-06-23-phase5-transpiler-robustness.md delete mode 100644 docs/superpowers/plans/2026-06-23-refactor-uxassist-cheate-universe.md diff --git a/docs/GameCompatibility-0.10.35.29131.md b/docs/GameCompatibility-0.10.35.29131.md deleted file mode 100644 index 3cd1c5e..0000000 --- a/docs/GameCompatibility-0.10.35.29131.md +++ /dev/null @@ -1,55 +0,0 @@ -# DSP 0.10.35.29131 Compatibility - -## Scope and sources - -The 2026-10-12 audit compares the supplied DSP **0.10.35.29104** backup with the installed **0.10.35.29131**, Steam build **25878145**. It covers the maintained mods in `DSP_Mods.sln`, including Dustbin's preloader. The retired LabOpt projects are excluded. - -Method bodies and metadata come from the original `DSPGAME_Data/Managed/Assembly-CSharp.dll` in: - -- Previous game: `D:/Steam/steamapps/content/app_13466540/depot_1366541`. -- Current game: `D:/Steam/steamapps/common/Dyson Sphere Program`, located through Steam's registry entry and `steamapps/libraryfolders.vdf`. - -Versions come from each installation's `Updates/Versions.txt` and the installed `appmanifest_1366540.acf`. `AssemblyFromGame/Assembly-CSharp.dll` is refreshed only for compilation. - -## Findings and fixes - -The native assembly has 67 changed method bodies, 11 added fields, 3 removed fields, and two replaced method signatures. No types are added or removed. Eight changed methods are directly targeted by maintained mod patches: - -| Native methods | Change relevant to review | Result | -| --- | --- | --- | -| `BuildTool_Reform.ExecuteBrushAction` | Terrain previews cache their preparation position and soil cost; soil cost moves from a local to a field. | Expanded brush and build-range patches still match. Flatten/restore execution signatures and soil guards remain valid. | -| `BuildTool_BlueprintPaste.DetermineReforms` | A terrain calculation now divides floating-point operands. | The blueprint soil-check patch still matches the intended comparison. | -| `BuildTool_Upgrade.DeterminePreviews` | Downgrade cursor text is distinguished from upgrade text. | Cursor-size and build-range patches retain their targets. | -| `MonitorComponent.InternalUpdate` | Cargo deletion scans a locked belt buffer and adds locals and exception handling. | The stack-count patch still targets the earlier cargo query and its `Cargo` local; branch targets remain valid. | -| `PlayerAction_Rts.GameTick` | Manual order cancellation changes for mining/building commands. | Globe-view conflict checks and auto-construct postfix bindings remain valid. | -| `ProductionExtraInfoCalculator.CalculateFactory`, `UIReferenceSpeedTip.AddEntryDataWithFactory` | Ray Receiver catalyst storage and active-catalyst identification are corrected. | Mining-speed and protected-vein patches still target the mining calculations. | -| `UIBuildMenu._OnUpdate` | Native vegetation-planting buttons are hidden. | The modifier-key patch still matches the native input checks. | - -The audit also reproduces an existing UXAssist defect on **both** game versions: the Ray Receiver buffer setting is ignored. Native `GameTick_Gamma` tests `keyFrame && useIon && catalystCount < 2`, while the mod searches for a floating-point conversion followed by `20f`. The pattern is absent, so the guarded transpiler returns the original method and the configured threshold never takes effect. - -The fix replaces the integer constant in the current catalyst-count comparison with `ReceiverBufferCount`. Only that constant changes. Native key-frame and mode checks, catalyst consumption, proliferation, both input ports, photon output, and branch destinations are preserved. The missing-pattern fallback still returns the original instructions. Native input can take stacked cargo, so the setting is an intake threshold rather than a strict inventory cap. - -The bilingual help text and README now show the native threshold as **2**. UXAssist's existing **1.6.2** unreleased changelog includes the fix; mod versions are unchanged. - -A subsequent mining-speed regression check finds an existing type error in `Increase maximum power usage in Logistic Stations and Advanced Mining Machines`. A floating-point slider constant makes the injected conversion delegate return `Single`, but native `OnMaxMiningSpeedChange` stores that result in an `Int32` local and then in `MinerComponent.speed`. This invalid IL corrupts the actual speed, rather than only its displayed percentage. A check using the original handler and the pre-fix package DLL reproduces invalid integer values; the exact result of the invalid IL depends on the runtime. - -The conversion now explicitly returns `Int32`, preserves native rounding, and retains 100%–300% in 10-percentage-point steps and 400%–1,000% in 100-percentage-point steps. Its transpiler matches the complete native calculation without depending on a fixed local slot and returns the original instructions when that calculation is absent. For miners whose speed has already been corrupted, adjust the slider after installing the fix; the previous intended setting cannot be recovered reliably from the corrupted value. - -LiveStreamAssist's offline text generator also fails on both game versions because it asks the type-tree generator for the removed `CreationPartProtoSet`; the original DLL and asset script metadata contain `VehiclePartProtoSet`. Its extraction map now uses the current type while preserving the public `creationPart` dictionary group. Text and icons are regenerated from the current installation, including item 1211, technology 1509, recipe 162, signal 519, updated English guide text, and current localized vegetation names. The offline layers retain their existing behavior and make no WebSocket requests. - -## Validation - -- `dotnet build DSP_Mods.sln -c Release --no-restore`: zero warnings and zero errors. -- 217 prefix/postfix target and parameter bindings pass, including Dustbin's injected fields. -- 212 transpiler applications: 200 transformations and 12 unchanged results. No target-resolution, transpiler-execution, branch-label, or missing-operand errors occur. The 12 unchanged results also occur with the previous game DLL. -- Dustbin's actual preloader injects the two expected Boolean fields into a temporary copy of the original game assembly; its mod checks pass against that copy. -- The receiver regression check fails before the fix because configuration value 1 leaves the native threshold at 2. After the fix, 21 assertions pass on each game version, covering thresholds 1, 2, 7, and 20, below/equal/above boundaries, emitted comparison types, preservation of surrounding instructions, and missing-pattern fallback. -- 55 existing behavior assertions pass, including terrain buffer bounds, soil guards, saved brush restoration, and composition of both `ExecuteBrushAction` transpilers in either order. -- 75 mining-speed assertions pass. The check executes the original handler with the injected conversion against real game data types, replacing only the Unity text setter with a recording function. It verifies actual miner-speed assignments and displayed percentages, every slider position, rounding boundaries, reopening readback, native event/station guards, the unpatched path, and complete/partial missing-pattern fallbacks. This check covers the return/local type mismatch that the earlier structural transpiler checks did not detect. -- LiveStreamAssist's text and icon generators succeed against the current original game files; the dictionary includes 175 items and 315 technologies. Repacking the JS bundle produces no source changes. -- 42 JS client/query/text/overlay checks and the Python locale/format checks pass. The full JS suite also includes seven pre-existing dashboard failures: its `FakeQuery` omits `getClusterString`, which the unchanged dashboard calls. The same seven failures reproduce in an isolated copy of the files from `HEAD`. These tests use their own mocked text data, independent of the regenerated dictionary. -- `git diff --check` passes. - -The temporary audit harness and raw comparison outputs remain under the excluded `UXAssist/obj/game-update-29131/` directory. `MONOMOD_DMD_TYPE=cecil` is set only for the check process so the repository's older MonoMod delegate generator can run on the installed .NET runtime. No detours are installed into the game. - -These checks do not verify Unity rendering, live input, or native detour installation. In-game testing remains necessary: exercise expanded foundation/Restore Terrain brushes, monitor stack counting, globe-view movement and auto-construct, protected-vein estimates, and Ray Receiver intake with the buffer feature enabled and disabled. diff --git a/docs/GameCompatibility-0.10.35.md b/docs/GameCompatibility-0.10.35.md deleted file mode 100644 index a0f4c86..0000000 --- a/docs/GameCompatibility-0.10.35.md +++ /dev/null @@ -1,65 +0,0 @@ -# DSP 0.10.35 Compatibility - -## Scope and sources - -This update adapts UXAssist and CheatEnabler from DSP **0.10.34.28529** to the locally installed **0.10.35.29057**, Steam build **25482430**. - -The comparison uses the original `DSPGAME_Data/Managed/Assembly-CSharp.dll` from the supplied previous-version depot and the Steam installation located through the registry and `steamapps/libraryfolders.vdf`. Version history comes from each installation's `Updates/Versions.txt`. In-game terminology comes from the installed `Locale/Names`, `Locale/1033`, and `Locale/2052` tables. - -The publicized, stripped assemblies in `AssemblyFromGame/` are refreshed for compilation only. They are not used to inspect native method bodies. - -## Assembly changes - -The Assembly-CSharp metadata and IL comparison finds: - -- 69 added types and 9 removed types. -- 784 added fields and 78 removed fields. -- 663 added method signatures and 46 removed method signatures. -- 475 changed bodies among methods whose signatures remain present. - -These counts include compiler-generated members. New code includes `Blackbox*`, `CreativeTool*`, and vehicle-part infrastructure, as well as vegetation collection and terrain restoration. The presence of a type does not establish that its feature is exposed in the current game UI. - -## Compatibility changes - -| Area | Native change | Mod adaptation | -| --- | --- | --- | -| Terrain tools | `BuildTool_Reform.ReformAction` is removed. Brush input and range checks move to `ExecuteBrushAction`; execution splits into `DoFlattenExecute` and `DoRestoreExecute`. | Retarget UXAssist's range and brush-limit patches. Allocate sufficient preview buffers for 30 x 30 brushes before preparing either terrain operation. Clamp active brushes on disable and oversized saved brushes on restore when the feature is inactive. | -| Terraform anyway | Foundation placement and Restore Terrain now have separate soil deductions. | Bypass the foundation-count check in `DoFlattenExecute`. Clamp positive soil costs to the available balance in both execution methods, while retaining negative costs that award soil. Leave native terrain restoration and foundation refunds intact. | -| Globe-view actions | `EViewMode.Create` shifts subsequent enum values: Globe is now 4 and Starmap is 5. | Match and emit named enum values. Extend the movement/mining camera-conflict getter results rather than relying on local-variable positions. | -| Ray Receiver inventory | Stored catalysts move from accumulated `catalystPoint`/`catalystIncPoint` values to `catalystCount`/`catalystInc`. `catalystPoint` becomes the active catalyst's remaining lifetime. | Apply the configured buffer limit to the stored item count without multiplying by 3,600. Planet initialization returns stored catalysts and their proliferation points, matching native item take-back semantics. | -| Mineral exhaustion | `NotifyVeinExhausted` gains `hasMinerLostAllVeins` and honors the new alert preference. | Determine whether a miner loses its last vein before removing the vein. Pass that result to the notification; oil depletion passes false, as in the native implementation. | -| Handcrafting counts | Native Shift-click shortcuts bypass the old increment/decrement path. | Replace the count-button handlers while enhanced count control is enabled. Preserve normal steps of 1, Ctrl steps of 10, Shift steps of 100, Alt steps of 1,000, and the 1–1,000 bounds. | -| Soil-change tips | `Player.SetSandCount` now updates soil progression before notifying subscribers. | Suppress `UIGame.OnSandCountChanged` instead of returning early from the player setter. Native progression and other subscribers remain intact. | -| Batch technology buyout | The technology UI changes local-variable layout and adds prerequisite checks to buyout visibility. | Replace the visibility expression with a semantic predicate for locked, non-hidden, non-obsolete technologies. Preserve the native metadata toggle, sandbox exclusion, and surrounding selected/researching state handling. | - -Affected transpilers use guarded matching and return the original instructions if their required pattern is absent. The mods now target the new terrain API; this is not a dual-version compatibility layer for 0.10.34. - -## Validation - -Both projects build in Release with zero warnings and zero errors after refreshing the game references: - -```powershell -dotnet build UpdateGameDlls/UpdateGameDlls.csproj -dotnet build UXAssist/UXAssist.csproj -c Release --no-restore -dotnet build CheatEnabler/CheatEnabler.csproj -c Release --no-restore -git diff --check -``` - -An ignored standalone check harness in `obj/dsp-compat/` reads the original game DLL and uses the repository's HarmonyX/BepInEx dependencies without installing game detours. It checks: - -- 116 prefix/postfix target and parameter bindings. -- 187 transpiler applications: 183 transformations and 4 unchanged results that also occur with the previous DLL. No target, matcher, branch-label, or operand checks fail. -- 55 behavior assertions covering handcrafting modifiers, brush bounds and buffer reuse, disabled-feature save restoration, soil shortages and gains, buyout visibility, UI-only soil-tip suppression, and missing-pattern fallbacks. -- The two `ExecuteBrushAction` transpilers compose in either order; these assertions are included in the behavior count. - -These automated checks do not verify native detour installation or Unity rendering/input behavior. The user also confirmed that testing passed. Mod versions and package manifests are not changed; the changelog entries remain unreleased. - -## In-game smoke checks - -Use a disposable copy of a save for destructive reset/refund and mineral-depletion checks. - -1. Test foundation placement and Restore Terrain with brush sizes 1, 10, 11, and 30, including line drawing. Disable expanded brushes and reload a save made with a large brush. -2. Enable Terraform anyway with insufficient foundations and soil. Check foundation placement, terrain restoration, blueprint foundations, and base-pit removal. Soil must stay nonnegative, and soil gains and native refunds must remain available. -3. Feed a Ray Receiver proliferated catalysts, check the configured buffer limit, and verify stored catalyst refunds through planet initialization on the disposable save. -4. Exercise the mineral-exhaustion alert modes, globe-view movement/mining, and normal/Ctrl/Shift/Alt handcrafting count changes. -5. Check batch buyout with missing prerequisites and verify hidden, obsolete, and already-unlocked technologies remain excluded. Hide soil tips and confirm soil-related progression still advances. diff --git a/docs/superpowers/plans/2026-06-23-phase5-transpiler-robustness.md b/docs/superpowers/plans/2026-06-23-phase5-transpiler-robustness.md deleted file mode 100644 index 34ff700..0000000 --- a/docs/superpowers/plans/2026-06-23-phase5-transpiler-robustness.md +++ /dev/null @@ -1,334 +0,0 @@ -# Phase 5 — Transpiler Robustness & Code Quality Gates - -> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Make Harmony transpilers easier to diagnose on game updates, consolidate mod-compatibility reflection behind a single helper API, and add build-level quality gates. - -**Architecture:** -- A small `TranspilerGuard` helper standardizes the `CodeMatcher.IsInvalid` fallback pattern so transpilers can return original instructions and log a warning instead of producing invalid IL. -- A public `ModCompatHelper` in `UXAssist.Common.ModCompat` centralizes BepInEx plugin detection, external-type resolution, and member lookup; wrappers and DysonSphere reflection consumers migrate to it. -- A root `.editorconfig`, stricter MSBuild warning settings, and a GitHub Actions build workflow provide guardrails without blocking the existing obsolete-warning surface. - -**Tech Stack:** C# / .NET Framework 4.7.2 / BepInEx 5 / HarmonyLib / MSBuild / GitHub Actions - ---- - -## Task 1: Transpiler comments & fallback guards - -**Files:** -- Create: `UXAssist/Common/Patching/TranspilerGuard.cs` -- Modify: all files listed in `docs/TranspilerAudit.md` (26 files, 115 transpilers) - -- [ ] **Step 1.1: Create `TranspilerGuard`** - -```csharp -using System.Collections.Generic; -using System.Reflection.Emit; -using BepInEx.Logging; -using HarmonyLib; - -namespace UXAssist.Common.Patching; - -public static class TranspilerGuard -{ - public static IEnumerable Finish( - this CodeMatcher matcher, - IEnumerable originalInstructions, - ManualLogSource logger, - string transpilerName) - { - if (matcher.IsInvalid) - { - logger?.LogWarning($"Transpiler '{transpilerName}' failed to match; returning original instructions."); - return originalInstructions; - } - return matcher.InstructionEnumeration(); - } -} -``` - -- [ ] **Step 1.2: Add standardized header comments to every transpiler** - -For each transpiler method, insert a comment block immediately above the method: - -```csharp -// Harmony transpiler target: .() -// Purpose: -// Fragile matches: -// Fallback: -``` - -Use the audit in `docs/TranspilerAudit.md` (produced by exploration) to fill Fragile matches. - -- [ ] **Step 1.3: Add fallback guards where missing** - -For transpilers that currently call `matcher.InstructionEnumeration()` without checking `IsInvalid`, change the last lines to: - -```csharp -return matcher.Finish(instructions, UXAssist.Logger, nameof()); -``` - -Preserve the return type `IEnumerable`. Where a method already checks `matcher.IsInvalid`/`IsValid`, keep the existing logic and only add the comment. - -- [ ] **Step 1.4: Build after comment/guard pass** - -Run: `dotnet build DSP_Mods.sln -c Release` -Expected: 0 errors, 0 new warnings. - ---- - -## Task 2: Centralize mod-compatibility reflection - -**Files:** -- Create: `UXAssist/Common/ModCompat/ModCompatHelper.cs` -- Create: `UXAssist/Common/Utils/DysonSphereReflection.cs` -- Modify: `UXAssist/ModsCompat/AuxilaryfunctionWrapper.cs` -- Modify: `UXAssist/ModsCompat/BlueprintTweaks.cs` -- Modify: `UXAssist/ModsCompat/BulletTimeWrapper.cs` -- Modify: `UXAssist/ModsCompat/CommonAPIWrapper.cs` -- Modify: `UXAssist/ModsCompat/PlanetVeinUtilization.cs` -- Modify: `UXAssist/Patches/DysonSpherePatch.cs` -- Modify: `CheatEnabler/Functions/DysonSphere/ShellCompletionFunctions.cs` -- Modify: `CheatEnabler/Functions/DysonSphere/FrameRemovalFunctions.cs` - -- [ ] **Step 2.1: Create `ModCompatHelper`** - -```csharp -using System; -using System.Reflection; -using BepInEx; -using BepInEx.Bootstrap; - -namespace UXAssist.Common.ModCompat; - -public static class ModCompatHelper -{ - public static bool TryGetLoadedPluginInfo(string guid, out PluginInfo pluginInfo) - => Chainloader.PluginInfos.TryGetValue(guid, out pluginInfo) && pluginInfo != null; - - public static bool TryGetPluginType(PluginInfo pluginInfo, string typeName, out Type type) - { - type = null; - if (pluginInfo?.Instance == null) return false; - try - { - type = pluginInfo.Instance.GetType().Assembly.GetType(typeName, throwOnError: false); - } - catch { /* ignored */ } - return type != null; - } - - public static bool TryGetPluginType(string guid, string typeName, out Type type) - { - type = null; - return TryGetLoadedPluginInfo(guid, out var pluginInfo) && TryGetPluginType(pluginInfo, typeName, out type); - } - - public static bool TryGetFieldValue(Type type, string fieldName, object instance, out T value) - { - value = default; - if (type == null) return false; - var field = AccessTools.Field(type, fieldName); - if (field == null) return false; - try - { - var result = field.GetValue(instance); - if (result is T t) - { - value = t; - return true; - } - } - catch { /* ignored */ } - return false; - } - - public static bool TryGetMethod(Type type, string methodName, out MethodInfo method) - { - method = null; - if (type == null) return false; - method = AccessTools.Method(type, methodName); - return method != null; - } - - public static bool TryGetPropertySetter(Type type, string propertyName, out MethodInfo setter) - { - setter = null; - if (type == null) return false; - var property = AccessTools.Property(type, propertyName); - if (property == null) return false; - setter = property.GetSetMethod(nonPublic: true); - return setter != null; - } -} -``` - -- [ ] **Step 2.2: Refactor mod-compat wrappers to use `ModCompatHelper`** - -Replace the duplicated `Chainloader.PluginInfos.TryGetValue` + `pluginInfo.Instance.GetType().Assembly.GetType(...)` + `AccessTools.Field/Method/PropertySetter` patterns with calls to `ModCompatHelper`. Keep the existing public static fields (e.g., `HasBulletTime`, `ShowStationInfo`) and init timing (`Start`/`Run`). - -- [ ] **Step 2.3: Create `DysonSphereReflection`** - -```csharp -using System.Reflection; -using HarmonyLib; - -namespace UXAssist.Common.Utils; - -public static class DysonSphereReflection -{ - private static readonly FieldInfo TotalNodeSpField = AccessTools.Field(typeof(DysonSphereLayer), "totalNodeSP"); - private static readonly FieldInfo TotalFrameSpField = AccessTools.Field(typeof(DysonSphereLayer), "totalFrameSP"); - private static readonly FieldInfo TotalCpField = AccessTools.Field(typeof(DysonSphereLayer), "totalCP"); - - public static long? GetTotalNodeSP(DysonSphereLayer layer) - => layer != null && TotalNodeSpField != null ? (long?)TotalNodeSpField.GetValue(layer) : null; - - public static long? GetTotalFrameSP(DysonSphereLayer layer) - => layer != null && TotalFrameSpField != null ? (long?)TotalFrameSpField.GetValue(layer) : null; - - public static long? GetTotalCP(DysonSphereLayer layer) - => layer != null && TotalCpField != null ? (long?)TotalCpField.GetValue(layer) : null; - - public static bool IsAvailable => TotalNodeSpField != null && TotalFrameSpField != null && TotalCpField != null; -} -``` - -- [ ] **Step 2.4: Migrate DysonSphere field consumers** - -Update `UXAssist/Patches/DysonSpherePatch.cs`, `CheatEnabler/Functions/DysonSphere/ShellCompletionFunctions.cs`, and `CheatEnabler/Functions/DysonSphere/FrameRemovalFunctions.cs` to call `DysonSphereReflection` instead of resolving the fields locally. Remove duplicate `AccessTools.Field` declarations. - -- [ ] **Step 2.5: Build after reflection refactor** - -Run: `dotnet build DSP_Mods.sln -c Release` -Expected: 0 errors, 0 new warnings. - ---- - -## Task 3: Code quality gates - -**Files:** -- Create: `.editorconfig` -- Modify: `Directory.Build.props` -- Create: `.github/workflows/build.yml` - -- [ ] **Step 3.1: Add root `.editorconfig`** - -```ini -root = true - -[*] -charset = utf-8 -indent_style = space -indent_size = 4 -end_of_line = crlf -insert_final_newline = true -trim_trailing_whitespace = true - -[*.md] -trim_trailing_whitespace = false - -[*.{cs,vb}] -# Suggestion-only so existing code does not break the build -dotnet_style_qualification_for_field = false:suggestion -dotnet_style_qualification_for_property = false:suggestion -dotnet_style_qualification_for_method = false:suggestion -dotnet_style_qualification_for_event = false:suggestion -dotnet_style_require_accessibility_modifiers = for_non_interface_members:suggestion -dotnet_style_readonly_field = true:suggestion -csharp_style_var_for_built_in_types = true:suggestion -csharp_style_var_when_type_is_apparent = true:suggestion -csharp_style_var_elsewhere = true:suggestion -csharp_style_expression_bodied_methods = when_on_single_line:suggestion -csharp_style_expression_bodied_properties = true:suggestion -csharp_prefer_simple_default_expression = true:suggestion -csharp_style_pattern_local_over_anonymous_function = true:suggestion -``` - -- [ ] **Step 3.2: Harden `Directory.Build.props`** - -Add to the existing `` (do not remove existing properties): - -```xml -true -0618 -disable -none -false -``` - -`NoWarn>0618` suppresses the expected `[Obsolete]` usage warnings from the old `Util` facade; any new warning class will fail the build. - -- [ ] **Step 3.3: Add GitHub Actions build workflow** - -Create `.github/workflows/build.yml`: - -```yaml -name: Build - -on: - push: - branches: [main, master, refactor/*] - pull_request: - branches: [main, master] - -jobs: - build: - runs-on: windows-latest - steps: - - uses: actions/checkout@v4 - - - name: Setup .NET - uses: actions/setup-dotnet@v4 - with: - dotnet-version: '8.0.x' - - - name: Restore - run: dotnet restore DSP_Mods.sln - - - name: Build Release - run: dotnet build DSP_Mods.sln -c Release --no-restore - - - name: Package mods - run: dotnet build -t:ZipMod -c Release --no-restore -``` - -- [ ] **Step 3.4: Verify quality gates** - -Run: -```bash -dotnet clean DSP_Mods.sln -dotnet build DSP_Mods.sln -c Release -``` -Expected: 0 errors, 0 warnings. - -Run: -```bash -dotnet build -t:ZipMod -c Release -``` -Expected: All zips produced; no errors. - ---- - -## Task 4: Documentation & checkpoint - -**Files:** -- Modify: `AGENTS.md` - -- [ ] **Step 4.1: Update `AGENTS.md`** - -Append a "Phase 5 — Transpiler Robustness & Code Quality Gates" subsection under the project overview describing: -- `UXAssist.Common.Patching.TranspilerGuard` -- `UXAssist.Common.ModCompat.ModCompatHelper` -- `UXAssist.Common.Utils.DysonSphereReflection` -- `.editorconfig`, `TreatWarningsAsErrors`, and the GitHub Actions build workflow. - -- [ ] **Step 4.2: Tag checkpoint** - -```bash -git add -A -git commit -m "refactor: phase 5 transpiler robustness, mod-compat helpers, and build quality gates" -git tag refactor-phase5 -``` - -Expected: tag `refactor-phase5` exists on the new commit and build remains clean. diff --git a/docs/superpowers/plans/2026-06-23-refactor-uxassist-cheate-universe.md b/docs/superpowers/plans/2026-06-23-refactor-uxassist-cheate-universe.md deleted file mode 100644 index f24a9c6..0000000 --- a/docs/superpowers/plans/2026-06-23-refactor-uxassist-cheate-universe.md +++ /dev/null @@ -1,1367 +0,0 @@ -# UXAssist / CheatEnabler / UniverseGenTweaks Refactor Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Improve readability and maintainability of `UXAssist`, `CheatEnabler`, and `UniverseGenTweaks` by splitting oversized files, centralizing constants/localization, cleaning static mutable state, and hardening transpilers. Only `UXAssist.UI` and `UXAssist.Common` public APIs are treated as a stable contract; everything else may be refactored freely, and downstream projects are updated to consume the new structure. - -**Architecture:** Keep the existing BepInEx + Harmony stack. Introduce a reusable, public mod-feature lifecycle abstraction in `UXAssist.Common.ModFeatures` that replaces the current namespace-based reflection on static `Functions`/`Patches` classes. Each static feature class declares `[ModFeature]` and exposes `Init`/`Start`/`Uninit`/`OnInputUpdate`/`OnUpdate` as needed; `ModFeatureRegistry.Discover` finds and registers them, then drives their lifecycle. `CheatEnabler` and `UniverseGenTweaks` adopt the same abstraction, so they benefit from the same architecture rather than using `InternalsVisibleTo`. - -Split monolithic `Patches/*.cs` and `Functions/*.cs` files into focused classes grouped by subsystem (e.g., `UXAssist.Patches.Factory.*`). Refactor the internals of `UXAssist.UI` and `UXAssist.Common` into smaller helpers while keeping the existing public surface intact (old members become thin forwarding facades or are marked `[Obsolete]`). Introduce `ConfigProvider` helpers and `GameConstants` classes to decouple UI from patch internals. Clean static state through explicit `ResetState` callbacks registered on `GameLogic.OnGameEnd`. Add version/fallback annotations to transpilers to survive game updates. - -**Tech Stack:** C# (`net472`), BepInEx 5.x, HarmonyLib, SDK-style MSBuild, PowerShell `Compress-Archive`. - ---- - -## Phase 1 — Structural Split + Public Lifecycle Abstraction - -### Task 1: Document the public API surface that must stay stable - -**Files:** -- Create: `docs/PublicApiSurface.md` - -- [ ] **Step 1: Inventory `UXAssist.UI` and `UXAssist.Common` public members** - - Read every file under `UXAssist/UI/` and `UXAssist/Common/` and list every `public` class/struct/enum/delegate/method/property/event/field that is reachable from `CheatEnabler` or `UniverseGenTweaks`. - - At minimum, the list must include: - - `UXAssist.Common.I18N` (`Add`, `Apply`, `Translate`, `Init`, `OnInitialized`) - - `UXAssist.Common.GameLogic` (`Enable`, `OnDataLoaded`, `OnGameBegin`, `OnGameEnd`, `OnFactoryFrameBegin`) - - `UXAssist.Common.PatchImpl` and `PatchGuidAttribute` - - `UXAssist.Common.Util` (`GetTypesFiltered`, `GetTypesInNamespace`, `LoadEmbeddedResource`, `LoadEmbeddedTexture`, `LoadEmbeddedSprite`, `PluginFolder`) - - `UXAssist.UI.MyConfigWindow` (`OnUICreated`, `OnUpdateUI`, `CreateInstance`, `DestroyInstance`) - - `UXAssist.UI.MyWindow` (`InitBaseObject`, `Create`, `AddText`, `AddText2`, `AddButton`, `AddTipsButton`, `AddTipsButton2`, `Open`, `Close`, `TryClose`, `AutoFitWindowSize`) - - `UXAssist.UI.MyWindowWithTabs` (`AddTabGroup`, `AddTab`) - - `UXAssist.UI.MyCheckBox.CreateCheckBox` - - `UXAssist.UI.MySlider.CreateSlider` - - `UXAssist.UI.MyWindowManager` (`InitBaseObjects`, `Enable`) - -- [ ] **Step 2: Commit the inventory** - - ```bash - git add docs/PublicApiSurface.md - git commit -m "docs: inventory UXAssist.UI/Common public API surface" - ``` - ---- - -### Task 2: Introduce public `ModFeature` lifecycle abstraction - -**Files:** -- Create: `UXAssist/Common/ModFeatures/ModFeatureAttribute.cs` -- Create: `UXAssist/Common/ModFeatures/IModFeature.cs` -- Create: `UXAssist/Common/ModFeatures/ModFeatureRegistry.cs` -- Modify: `UXAssist/Common/Util.cs` - -- [ ] **Step 1: Add namespace-prefix reflection helper** - - In `UXAssist/Common/Util.cs`: - ```csharp - public static Type[] GetTypesInNamespacePrefix(Assembly assembly, string prefix) - { - return GetTypesFiltered(assembly, t => t.Namespace != null && t.Namespace.StartsWith(prefix, StringComparison.Ordinal)); - } - ``` - -- [ ] **Step 2: Define the attribute** - - ```csharp - namespace UXAssist.Common.ModFeatures; - - [AttributeUsage(AttributeTargets.Class, Inherited = false)] - public sealed class ModFeatureAttribute : Attribute - { - public string Name { get; } - public int Order { get; set; } - - public ModFeatureAttribute(string name = null) - { - Name = name; - } - } - ``` - -- [ ] **Step 3: Define the optional instance interface** - - ```csharp - namespace UXAssist.Common.ModFeatures; - - public interface IModFeature - { - void Init(); - void Start(); - void Uninit(); - void OnInputUpdate(); - void OnUpdate(); - } - ``` - -- [ ] **Step 4: Implement the registry** - - ```csharp - using System; - using System.Collections.Generic; - using System.Linq; - using System.Reflection; - - namespace UXAssist.Common.ModFeatures; - - public static class ModFeatureRegistry - { - private static readonly List _staticFeatures = []; - private static readonly List _instanceFeatures = []; - private static readonly HashSet _discoveredAssemblies = []; - - public static void Discover(Assembly assembly) - { - if (!_discoveredAssemblies.Add(assembly)) return; - - var staticTypes = Util.GetTypesFiltered(assembly, t => - t.IsClass && t.IsAbstract && t.IsSealed && - Attribute.IsDefined(t, typeof(ModFeatureAttribute))); - - foreach (var type in staticTypes.OrderBy(GetOrder)) - { - if (!_staticFeatures.Contains(type)) - _staticFeatures.Add(type); - } - } - - public static void Register() where T : class, IModFeature, new() - { - var instance = new T(); - _instanceFeatures.Add(instance); - } - - public static void InitAll() - { - ForEachStatic("Init"); - foreach (var f in _instanceFeatures) f.Init(); - } - - public static void StartAll() - { - ForEachStatic("Start"); - foreach (var f in _instanceFeatures) f.Start(); - } - - public static void UninitAll() - { - ForEachStatic("Uninit"); - foreach (var f in _instanceFeatures) f.Uninit(); - } - - public static void OnInputUpdateAll() - { - ForEachStatic("OnInputUpdate"); - foreach (var f in _instanceFeatures) f.OnInputUpdate(); - } - - public static void OnUpdateAll() - { - ForEachStatic("OnUpdate"); - foreach (var f in _instanceFeatures) f.OnUpdate(); - } - - private static void ForEachStatic(string methodName) - { - foreach (var type in _staticFeatures) - { - var method = type.GetMethod(methodName, - BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static); - method?.Invoke(null, null); - } - } - - private static int GetOrder(Type type) - { - return type.GetCustomAttribute()?.Order ?? 0; - } - } - ``` - -- [ ] **Step 5: Build UXAssist** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - ``` - Expected: 0 errors. - -- [ ] **Step 6: Commit** - - ```bash - git add UXAssist/Common/ModFeatures/ UXAssist/Common/Util.cs - git commit -m "feat(UXAssist): public ModFeature lifecycle registry" - ``` - ---- - -### Task 3: Split `UXAssist/Patches/FactoryPatch.cs` and mark features - -**Files:** -- Create: `UXAssist/Patches/Factory/FactoryPatch.cs` (config coordinator) -- Create: `UXAssist/Patches/Factory/ImmediateBuildPatch.cs` -- Create: `UXAssist/Patches/Factory/ArchitectModePatch.cs` -- Create: `UXAssist/Patches/Factory/BuildToolPatch.cs` -- Create: `UXAssist/Patches/Factory/BeltSignalPatch.cs` -- Create: `UXAssist/Patches/Factory/BuildingBufferPatch.cs` -- Create: `UXAssist/Patches/Factory/VeinProtectionPatch.cs` -- Create: `UXAssist/Patches/Factory/PowerGenerationPatch.cs` -- Create: `UXAssist/Patches/Factory/RenderingPatch.cs` -- Delete: `UXAssist/Patches/FactoryPatch.cs` - -- [ ] **Step 1: Move nested patch classes to new files** - - Use `git mv` semantics: copy the contents of each nested `PatchImpl` class from the old file into a new file under `UXAssist/Patches/Factory/`. Keep each class `internal` unless it must be public. Use namespace `UXAssist.Patches.Factory`. - -- [ ] **Step 2: Create the coordinator `FactoryPatch`** - - Mark it as a mod feature and expose the public `ConfigEntry` fields: - ```csharp - using UXAssist.Common.ModFeatures; - - namespace UXAssist.Patches.Factory; - - [ModFeature("Factory", Order = 10)] - public static class FactoryPatch - { - public static ConfigEntry UnlimitInteractiveEnabled { get; internal set; } - // ... all other public ConfigEntry fields from the original file - - public static void Init() - { - ImmediateBuildPatch.Init(); - ArchitectModePatch.Init(); - // ... - } - - public static void Start() - { - ImmediateBuildPatch.Start(); - // ... - } - - public static void Uninit() - { - ImmediateBuildPatch.Uninit(); - // ... - } - - public static void OnInputUpdate() => BeltSignalPatch.OnInputUpdate(); - public static void Export(BinaryWriter w) => BeltSignalPatch.Export(w); - public static void Import(BinaryReader r) => BeltSignalPatch.Import(r); - } - ``` - - `Awake()` in `UXAssist.cs` already assigns every `ConfigEntry`; leave those assignments untouched. - -- [ ] **Step 3: Build UXAssist** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - ``` - -- [ ] **Step 4: Commit** - - ```bash - git add UXAssist/Patches/Factory/ - git rm UXAssist/Patches/FactoryPatch.cs - git commit -m "refactor(UXAssist): split FactoryPatch into focused classes" - ``` - ---- - -### Task 4: Split `UXAssist/Patches/LogisticsPatch.cs` and mark features - -**Files:** -- Create: `UXAssist/Patches/Logistics/LogisticsPatch.cs` -- Create: `UXAssist/Patches/Logistics/AutoConfigPatch.cs` -- Create: `UXAssist/Patches/Logistics/CapacityPatch.cs` -- Create: `UXAssist/Patches/Logistics/OverflowPatch.cs` -- Create: `UXAssist/Patches/Logistics/RealtimeInfoPanelPatch.cs` -- Delete: `UXAssist/Patches/LogisticsPatch.cs` - -- [ ] **Step 1: Move nested classes and create coordinator** - - Same pattern as Task 3. Coordinator is marked `[ModFeature("Logistics", Order = 11)]` and forwards `OnInputUpdate` / `OnUpdate` to sub-classes. - -- [ ] **Step 2: Build UXAssist** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - ``` - -- [ ] **Step 3: Commit** - - ```bash - git add UXAssist/Patches/Logistics/ - git rm UXAssist/Patches/LogisticsPatch.cs - git commit -m "refactor(UXAssist): split LogisticsPatch into focused classes" - ``` - ---- - -### Task 5: Split `UXAssist/Functions/UIFunctions.cs` and mark features - -**Files:** -- Create: `UXAssist/Functions/UI/StarmapFilterUI.cs` -- Create: `UXAssist/Functions/UI/MilkyWayUI.cs` -- Create: `UXAssist/Functions/UI/AutoCruiseUI.cs` -- Create: `UXAssist/Functions/UI/MenuButtonUI.cs` -- Modify: `UXAssist/Functions/UIFunctions.cs` (coordinator, marked `[ModFeature("UI", Order = 12)]`) -- Modify: `UXAssist/UXAssist.cs` - -- [ ] **Step 1: Move features to sub-files** - - Namespace `UXAssist.Functions.UI`. Keep `internal` where possible. Keep public `ConfigEntry` fields on `UIFunctions` if bound in `UXAssist.Awake()`. - -- [ ] **Step 2: Update `UXAssist.Awake()` export/import calls** - - Replace `UIFunctions.ExportClusterUploadResults(w)` with a coordinator call or direct `MilkyWayUI.Export(w)`. - -- [ ] **Step 3: Build UXAssist** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - ``` - -- [ ] **Step 4: Commit** - - ```bash - git add UXAssist/Functions/UI/ UXAssist/Functions/UIFunctions.cs UXAssist/UXAssist.cs - git commit -m "refactor(UXAssist): split UIFunctions into UI sub-features" - ``` - ---- - -### Task 6: Update `UXAssist.cs` to drive features through `ModFeatureRegistry` - -**Files:** -- Modify: `UXAssist/UXAssist.cs` - -- [ ] **Step 1: Discover features from UXAssist assembly** - - In `Awake()`, after config binding: - ```csharp - ModFeatureRegistry.Discover(Assembly.GetExecutingAssembly()); - ModFeatureRegistry.InitAll(); - ``` - -- [ ] **Step 2: Replace lifecycle calls** - - In `Start()`: - ```csharp - ModFeatureRegistry.StartAll(); - ``` - - In `OnDestroy()`: - ```csharp - ModFeatureRegistry.UninitAll(); - ``` - -- [ ] **Step 3: Replace hard-coded update calls** - - In `Update()`: - ```csharp - if (VFInput.inputing) return; - if (DSPGame.IsMenuDemo) - { - ModFeatureRegistry.OnInputUpdateAll(); - return; - } - ModFeatureRegistry.OnInputUpdateAll(); - ModFeatureRegistry.OnUpdateAll(); - ``` - - Remove the explicit per-class calls (`LogisticsPatch.OnInputUpdate()`, `UIFunctions.OnInputUpdate()`, `GamePatch.OnInputUpdate()`, `FactoryPatch.OnInputUpdate()`, `PlayerPatch.OnInputUpdate()`, `LogisticsPatch.OnUpdate()`). - -- [ ] **Step 4: Keep compat initialization separate** - - Keep the `ModsCompat` scan in `Awake()` and `Start()`; compat wrappers are not mod features because they receive a `Harmony` argument. - -- [ ] **Step 5: Centralize save participants** - - Add a simple registry in `UXAssist.cs`: - ```csharp - private static readonly List> _exporters = []; - private static readonly List> _importers = []; - - public static void RegisterExporter(Action e) => _exporters.Add(e); - public static void RegisterImporter(Action i) => _importers.Add(i); - ``` - - Update `Export`/`Import` to iterate `_exporters`/`_importers`. Remove direct `FactoryPatch.Export` / `UIFunctions.ExportClusterUploadResults` calls; the coordinators register themselves during `Init`. - -- [ ] **Step 6: Build UXAssist** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - ``` - -- [ ] **Step 7: Commit** - - ```bash - git add UXAssist/UXAssist.cs - git commit -m "refactor(UXAssist): drive lifecycle via ModFeatureRegistry" - ``` - ---- - -### Task 7: Decouple `UXAssist.UIConfigWindow` from patch internals - -**Files:** -- Create: `UXAssist/Common/Config/FactoryConfigProvider.cs` -- Create: `UXAssist/Common/Config/LogisticsConfigProvider.cs` -- Modify: `UXAssist/UIConfigWindow.cs` - -- [ ] **Step 1: Create config providers** - - Each provider exposes only the `ConfigEntry` references that the UI needs: - ```csharp - public static class FactoryConfigProvider - { - public static ConfigEntry NightLightEnabled => Factory.FactoryPatch.NightLightEnabled; - // ... - } - ``` - -- [ ] **Step 2: Update `UIConfigWindow.cs`** - - Replace direct references like `FactoryPatch.NightLightEnabled` with `FactoryConfigProvider.NightLightEnabled`. - -- [ ] **Step 3: Build UXAssist** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - ``` - -- [ ] **Step 4: Commit** - - ```bash - git add UXAssist/Common/Config/ UXAssist/UIConfigWindow.cs - git commit -m "refactor(UXAssist): introduce config providers between UI and patches" - ``` - ---- - -### Task 8: Adopt `ModFeatureRegistry` in `CheatEnabler` - -**Files:** -- Modify: `CheatEnabler/CheatEnabler.cs` - -- [ ] **Step 1: Replace exact-namespace reflection with feature discovery** - - In `Awake()`: - ```csharp - ModFeatureRegistry.Discover(Assembly.GetExecutingAssembly()); - ModFeatureRegistry.InitAll(); - ``` - - In `Start()`: - ```csharp - ModFeatureRegistry.StartAll(); - ``` - - In `OnDestroy()`: - ```csharp - ModFeatureRegistry.UninitAll(); - ``` - - In `Update()`: - ```csharp - if (VFInput.inputing) return; - ModFeatureRegistry.OnInputUpdateAll(); - ``` - - Remove `_patches` and the reflection-based `Init`/`Start`/`Uninit` loop. - -- [ ] **Step 2: Build CheatEnabler** - - ```bash - dotnet build CheatEnabler/CheatEnabler.csproj -c Release - ``` - -- [ ] **Step 3: Commit** - - ```bash - git add CheatEnabler/CheatEnabler.cs - git commit -m "refactor(CheatEnabler): adopt ModFeatureRegistry from UXAssist" - ``` - ---- - -### Task 9: Split `CheatEnabler/Patches/FactoryPatch.cs` - -**Files:** -- Create: `CheatEnabler/Patches/Factory/FactoryPatch.cs` -- Create: `CheatEnabler/Patches/Factory/ImmediateBuildPatch.cs` -- Create: `CheatEnabler/Patches/Factory/ArchitectModePatch.cs` -- Create: `CheatEnabler/Patches/Factory/BeltSignalPatch.cs` -- Create: `CheatEnabler/Patches/Factory/PowerBoostPatch.cs` -- Create: `CheatEnabler/Patches/Factory/LogisticsControlPatch.cs` -- Delete: `CheatEnabler/Patches/FactoryPatch.cs` - -- [ ] **Step 1: Apply the coordinator pattern and `[ModFeature]`** - - Namespace `CheatEnabler.Patches.Factory`. Coordinator exposes the public `ConfigEntry` fields so `CheatEnabler.Awake()` continues to compile without changes. Mark coordinator `[ModFeature("CheatFactory", Order = 10)]`. - -- [ ] **Step 2: Build CheatEnabler** - - ```bash - dotnet build CheatEnabler/CheatEnabler.csproj -c Release - ``` - -- [ ] **Step 3: Commit** - - ```bash - git add CheatEnabler/Patches/Factory/ - git rm CheatEnabler/Patches/FactoryPatch.cs - git commit -m "refactor(CheatEnabler): split FactoryPatch into focused classes" - ``` - ---- - -### Task 10: Split `CheatEnabler/Functions/DysonSphereFunctions.cs` - -**Files:** -- Create: `CheatEnabler/Functions/DysonSphere/DysonSphereResolver.cs` -- Create: `CheatEnabler/Functions/DysonSphere/ShellCompletionFunctions.cs` -- Create: `CheatEnabler/Functions/DysonSphere/FrameRemovalFunctions.cs` -- Create: `CheatEnabler/Functions/DysonSphere/IllegalShellFunctions.cs` -- Create: `CheatEnabler/Functions/DysonSphere/GeometryHelpers.cs` -- Modify: `CheatEnabler/Functions/DysonSphereFunctions.cs` (coordinator, or delete if empty) -- Modify: `CheatEnabler/Patches/DysonSpherePatch.cs` if it calls helpers - -- [ ] **Step 1: Extract repeated "current sphere / star" logic** - - ```csharp - [ModFeature("DysonSphereResolver")] - public static class DysonSphereResolver - { - public static (DysonSphere sphere, StarData star)? ResolveCurrent() - { - var star = GameMain.localStar; - if (star == null) return null; - var sphere = GameMain.data.dysonSpheres[star.index]; - if (sphere == null) return null; - return (sphere, star); - } - } - ``` - -- [ ] **Step 2: Move shell actions to dedicated files** - - Replace duplicated cleanup blocks with a shared helper: - ```csharp - public static void NotifyShellChanged(DysonSphere sphere, DysonSphereLayer layer) - { - layer?.RecalculateModels(); - sphere?.swarm?.RecalculateModels(); - } - ``` - -- [ ] **Step 3: Build CheatEnabler** - - ```bash - dotnet build CheatEnabler/CheatEnabler.csproj -c Release - ``` - -- [ ] **Step 4: Commit** - - ```bash - git add CheatEnabler/Functions/DysonSphere/ - git rm CheatEnabler/Functions/DysonSphereFunctions.cs - git commit -m "refactor(CheatEnabler): split DysonSphereFunctions into focused helpers" - ``` - ---- - -### Task 11: Adopt `ModFeatureRegistry` in `UniverseGenTweaks` - -**Files:** -- Modify: `UniverseGenTweaks/UniverseGenTweaks.cs` - -- [ ] **Step 1: Replace explicit Init/Uninit with feature discovery** - - In `Awake()`: - ```csharp - ModFeatureRegistry.Discover(Assembly.GetExecutingAssembly()); - ModFeatureRegistry.InitAll(); - ``` - - In `OnDestroy()`: - ```csharp - ModFeatureRegistry.UninitAll(); - ``` - - Remove explicit `MoreSettings.Init()`, `EpicDifficulty.Init()`, `BirthPlanetPatch.Init()` and their `Uninit()` counterparts. - -- [ ] **Step 2: Build UniverseGenTweaks** - - ```bash - dotnet build UniverseGenTweaks/UniverseGenTweaks.csproj -c Release - ``` - -- [ ] **Step 3: Commit** - - ```bash - git add UniverseGenTweaks/UniverseGenTweaks.cs - git commit -m "refactor(UniverseGenTweaks): adopt ModFeatureRegistry from UXAssist" - ``` - ---- - -### Task 12: Split `UniverseGenTweaks/MoreSettings.cs` - -**Files:** -- Create: `UniverseGenTweaks/Patches/GalaxyGenSettingsPatch.cs` -- Create: `UniverseGenTweaks/Patches/GalaxySelectUIPatch.cs` -- Create: `UniverseGenTweaks/Patches/CombatSettingsPatch.cs` -- Create: `UniverseGenTweaks/Functions/GalaxyGenSave.cs` -- Modify: `UniverseGenTweaks/MoreSettings.cs` (coordinator, or delete) - -- [ ] **Step 1: Move UI construction to `GalaxySelectUIPatch`** - - Mark it `[ModFeature("GalaxySelectUI")]`. Keep slider/text creation helpers there. - -- [ ] **Step 2: Move transpilers to `GalaxyGenSettingsPatch`** - - Mark it `[ModFeature("GalaxyGenSettings")]`. Keep the `Init()`/`Uninit()` pattern and the `Harmony` instance local to this class. - -- [ ] **Step 3: Move combat settings to `CombatSettingsPatch`** - - Mark it `[ModFeature("CombatSettings")]`. Replace the seven near-identical slider-changed prefix methods with a table-driven mapper. - -- [ ] **Step 4: Move save serialization to `GalaxyGenSave`** - - Mark it `[ModFeature("GalaxyGenSave")]`. Implement `Export(BinaryWriter)` / `Import(BinaryReader)` and call them from `UniverseGenTweaks.Export`/`Import`. - -- [ ] **Step 5: Build UniverseGenTweaks** - - ```bash - dotnet build UniverseGenTweaks/UniverseGenTweaks.csproj -c Release - ``` - -- [ ] **Step 6: Commit** - - ```bash - git add UniverseGenTweaks/Patches/ UniverseGenTweaks/Functions/ - git rm UniverseGenTweaks/MoreSettings.cs - git commit -m "refactor(UniverseGenTweaks): split MoreSettings into focused classes" - ``` - ---- - -### Task 13: Phase 1 cross-project build verification - -- [ ] **Step 1: Clean and build all three projects** - - ```bash - dotnet clean UXAssist/UXAssist.csproj -c Release - dotnet clean CheatEnabler/CheatEnabler.csproj -c Release - dotnet clean UniverseGenTweaks/UniverseGenTweaks.csproj -c Release - dotnet build UXAssist/UXAssist.csproj -c Release - dotnet build CheatEnabler/CheatEnabler.csproj -c Release - dotnet build UniverseGenTweaks/UniverseGenTweaks.csproj -c Release - ``` - - Expected: all three succeed with no compilation errors. - -- [ ] **Step 2: Produce packages** - - ```bash - dotnet build -t:ZipMod -c Release - dotnet build -t:CopyToParentPackage -c Release - ``` - - Expected: `UXAssist/package/`, `CheatEnabler/package/`, `UniverseGenTweaks/package/`, and `Dustbin/package/patchers/` (if building the full solution) are generated. - -- [ ] **Step 3: Public API diff check** - - Use `dotnet build` output or `ildasm` to verify that every member listed in `docs/PublicApiSurface.md` still exists with the same signature. - -- [ ] **Step 4: Commit a Phase 1 checkpoint tag** - - ```bash - git tag refactor-phase1 - ``` - ---- - -## Phase 2 — UI / Common Internal Refactoring (public surface preserved) - -### Task 14: Split `UXAssist/Common/Util.cs` into focused helpers - -**Files:** -- Create: `UXAssist/Common/Util/ReflectionUtil.cs` -- Create: `UXAssist/Common/Util/ResourceUtil.cs` -- Create: `UXAssist/Common/Util/PathUtil.cs` -- Modify: `UXAssist/Common/Util.cs` - -- [ ] **Step 1: Move implementations to focused helpers** - - `ReflectionUtil.cs`: - ```csharp - public static class ReflectionUtil - { - public static Type[] GetTypesFiltered(Assembly assembly, Func predicate) { ... } - public static Type[] GetTypesInNamespace(Assembly assembly, string nameSpace) { ... } - public static Type[] GetTypesInNamespacePrefix(Assembly assembly, string prefix) { ... } - } - ``` - - `ResourceUtil.cs`: - ```csharp - public static class ResourceUtil - { - public static byte[] LoadEmbeddedResource(...) { ... } - public static Texture2D LoadEmbeddedTexture(...) { ... } - public static Sprite LoadEmbeddedSprite(...) { ... } - } - ``` - - `PathUtil.cs`: - ```csharp - public static class PathUtil - { - public static string PluginFolder(Assembly assembly = null) { ... } - } - ``` - -- [ ] **Step 2: Keep `Util` as a public forwarding facade** - - ```csharp - public static class Util - { - [Obsolete("Use ReflectionUtil.GetTypesFiltered")] - public static Type[] GetTypesFiltered(Assembly assembly, Func predicate) - => ReflectionUtil.GetTypesFiltered(assembly, predicate); - - [Obsolete("Use ReflectionUtil.GetTypesInNamespace")] - public static Type[] GetTypesInNamespace(Assembly assembly, string nameSpace) - => ReflectionUtil.GetTypesInNamespace(assembly, nameSpace); - - [Obsolete("Use ResourceUtil.LoadEmbeddedResource")] - public static byte[] LoadEmbeddedResource(string path, Assembly assembly = null) - => ResourceUtil.LoadEmbeddedResource(path, assembly); - - // ... forward all other existing methods - } - ``` - - New code inside UXAssist may call `ReflectionUtil`/`ResourceUtil`/`PathUtil` directly. - -- [ ] **Step 3: Build UXAssist** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - ``` - -- [ ] **Step 4: Commit** - - ```bash - git add UXAssist/Common/Util/ - git commit -m "refactor(UXAssist): split Util into focused helpers with forwarding facade" - ``` - ---- - -### Task 15: Refactor `UXAssist/Common/GameLogic.cs` event invocation - -**Files:** -- Create: `UXAssist/Common/GameEvent.cs` -- Modify: `UXAssist/Common/GameLogic.cs` - -- [ ] **Step 1: Introduce a small safe-event wrapper** - - ```csharp - public static class GameEvent - { - public static void InvokeSafe(this Action action, ManualLogSource logger, string name) - { - if (action == null) return; - foreach (var d in action.GetInvocationList()) - { - try { d.DynamicInvoke(); } - catch (Exception ex) { logger?.LogWarning($"GameEvent '{name}' handler failed: {ex}"); } - } - } - } - ``` - -- [ ] **Step 2: Use the wrapper inside `GameLogic`** - - Keep the public event fields unchanged. Replace manual invocation loops with `OnDataLoaded.InvokeSafe(UXAssist.Logger, nameof(OnDataLoaded));`. - -- [ ] **Step 3: Add XML documentation to all public members** - -- [ ] **Step 4: Build UXAssist** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - ``` - -- [ ] **Step 5: Commit** - - ```bash - git add UXAssist/Common/GameEvent.cs UXAssist/Common/GameLogic.cs - git commit -m "refactor(UXAssist): safe GameEvent wrapper and XML docs" - ``` - ---- - -### Task 16: Refactor `UXAssist/Common/I18N.cs` internals - -**Files:** -- Modify: `UXAssist/Common/I18N.cs` - -- [ ] **Step 1: Preserve public API** - - Keep `Add`, `Apply`, `Translate`, `Init`, `OnInitialized` signatures exactly as they are. - -- [ ] **Step 2: Internal cleanup** - - Split the internal storage into a private `LocalizedString` record and a dictionary keyed by the English key. Add a public convenience overload: - ```csharp - public static void Add(string key, string en, string zh) - ``` - (this is the existing signature; keep it). - -- [ ] **Step 3: Build UXAssist** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - ``` - -- [ ] **Step 4: Commit** - - ```bash - git add UXAssist/Common/I18N.cs - git commit -m "refactor(UXAssist): clean up I18N internals without changing public API" - ``` - ---- - -### Task 17: Extract layout helpers from `UXAssist/UI/MyWindow.cs` - -**Files:** -- Create: `UXAssist/UI/LayoutHelper.cs` -- Modify: `UXAssist/UI/MyWindow.cs` - -- [ ] **Step 1: Move static layout helpers** - - Move `AddText`, `AddTipsButton`, `AddButton` (static overloads), and `AddElement` into `LayoutHelper`. - - ```csharp - public static class LayoutHelper - { - public static Text AddText(float x, float y, RectTransform parent, string label, int fontSize = 14, string objName = "label") { ... } - public static UIButton AddTipsButton(...) { ... } - public static UIButton AddButton(...) { ... } - } - ``` - -- [ ] **Step 2: Keep `MyWindow` instance methods as forwarding facades** - - ```csharp - public Text AddText2(float x, float y, RectTransform parent, string label, int fontSize = 14, string objName = "label") - { - var text = LayoutHelper.AddText(x, y, parent, label, fontSize, objName); - _maxX = Math.Max(_maxX, x + text.rectTransform.sizeDelta.x); - MaxY = Math.Max(MaxY, y + text.rectTransform.sizeDelta.y); - return text; - } - ``` - - Mark the public static helpers on `MyWindow` as `[Obsolete("Use LayoutHelper")]` if desired, but keep them working. - -- [ ] **Step 3: Build UXAssist** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - ``` - -- [ ] **Step 4: Commit** - - ```bash - git add UXAssist/UI/LayoutHelper.cs UXAssist/UI/MyWindow.cs - git commit -m "refactor(UXAssist): extract UI layout helpers from MyWindow" - ``` - ---- - -### Task 18: Refactor `UXAssist/UI/MyConfigWindow.cs` tab management - -**Files:** -- Create: `UXAssist/UI/ConfigTabGroup.cs` -- Modify: `UXAssist/UI/MyConfigWindow.cs` -- Modify: `UXAssist/UI/MyWindowWithTabs.cs` - -- [ ] **Step 1: Extract tab group logic** - - Move the data structure that tracks tab groups into `ConfigTabGroup` so `MyConfigWindow` does not mix tab state with window lifecycle. - -- [ ] **Step 2: Preserve public events and methods** - - Keep `OnUICreated`, `OnUpdateUI`, `CreateInstance`, and `DestroyInstance` on `MyConfigWindow` with identical signatures. - -- [ ] **Step 3: Build UXAssist** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - ``` - -- [ ] **Step 4: Commit** - - ```bash - git add UXAssist/UI/ConfigTabGroup.cs UXAssist/UI/MyConfigWindow.cs UXAssist/UI/MyWindowWithTabs.cs - git commit -m "refactor(UXAssist): split tab management out of MyConfigWindow" - ``` - ---- - -### Task 19: Phase 2 cross-project build verification - -- [ ] **Step 1: Build all three projects** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - dotnet build CheatEnabler/CheatEnabler.csproj -c Release - dotnet build UniverseGenTweaks/UniverseGenTweaks.csproj -c Release - ``` - -- [ ] **Step 2: Public API diff check** - - Confirm every member in `docs/PublicApiSurface.md` still exists with the same signature. New `[Obsolete]` facades are acceptable. - -- [ ] **Step 3: Commit a Phase 2 checkpoint tag** - - ```bash - git tag refactor-phase2 - ``` - ---- - -## Phase 3 — Constants & Localization - -### Task 20: Create centralized constants files - -**Files:** -- Create: `UXAssist/Common/GameConstants/ItemIds.cs` -- Create: `UXAssist/Common/GameConstants/TechIds.cs` -- Create: `UXAssist/Common/GameConstants/LogisticsConstants.cs` -- Create: `UXAssist/Common/GameConstants/DysonSphereConstants.cs` -- Create: `UXAssist/Common/GameConstants/UniverseGenConstants.cs` - -- [ ] **Step 1: Extract item IDs** - - From `CheatEnabler/Patches/Factory/*.cs` and `UXAssist/Patches/Factory/BeltSignalPatch.cs`, collect hard-coded item IDs: - ```csharp - public static class ItemIds - { - public const int IronOre = 1001; - public const int CopperOre = 1002; - // ... - } - ``` - -- [ ] **Step 2: Extract tech IDs** - - From `UXAssist/Patches/TechPatch.cs`: - ```csharp - public static class TechIds - { - public const int SorterCargoStacking = 3608; - public static readonly HashSet CombatTechs = [3301, 3302, ...]; - } - ``` - -- [ ] **Step 3: Extract logistics constants** - - From `UXAssist/Patches/Logistics/CapacityPatch.cs`: - ```csharp - public static class LogisticsConstants - { - public const int DefaultLocalStorageMax = 5000; - public const int DefaultRemoteStorageMax = 10000; - } - ``` - -- [ ] **Step 4: Build UXAssist** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - ``` - -- [ ] **Step 5: Commit** - - ```bash - git add UXAssist/Common/GameConstants/ - git commit -m "refactor: centralize game constants" - ``` - ---- - -### Task 21: Replace magic numbers in UXAssist - -**Files:** -- Modify: `UXAssist/Patches/Factory/*.cs` -- Modify: `UXAssist/Patches/Logistics/*.cs` -- Modify: `UXAssist/Patches/TechPatch.cs` -- Modify: `UXAssist/Patches/DysonSpherePatch.cs` - -- [ ] **Step 1: Replace literal IDs and capacities with constants** - - For example, change: - ```csharp - if (itemId == 1001) { ... } - ``` - to: - ```csharp - if (itemId == ItemIds.IronOre) { ... } - ``` - -- [ ] **Step 2: Build UXAssist** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - ``` - -- [ ] **Step 3: Commit** - - ```bash - git add UXAssist/Patches/ - git commit -m "refactor(UXAssist): replace magic numbers with constants" - ``` - ---- - -### Task 22: Replace magic numbers in CheatEnabler and UniverseGenTweaks - -**Files:** -- Modify: `CheatEnabler/Patches/Factory/*.cs` -- Modify: `CheatEnabler/Functions/DysonSphere/*.cs` -- Modify: `CheatEnabler/Functions/PlanetFunctions.cs` -- Modify: `UniverseGenTweaks/Patches/GalaxyGenSettingsPatch.cs` -- Modify: `UniverseGenTweaks/Patches/CombatSettingsPatch.cs` -- Modify: `UniverseGenTweaks/BirthPlanetPatch.cs` - -- [ ] **Step 1: Reference UXAssist constants where appropriate** - - CheatEnabler/UniverseGenTweaks already reference `UXAssist.csproj`, so they can use `UXAssist.Common.GameConstants.ItemIds`, etc. - -- [ ] **Step 2: Build both projects** - - ```bash - dotnet build CheatEnabler/CheatEnabler.csproj -c Release - dotnet build UniverseGenTweaks/UniverseGenTweaks.csproj -c Release - ``` - -- [ ] **Step 3: Commit** - - ```bash - git add CheatEnabler/ UniverseGenTweaks/ - git commit -m "refactor(CheatEnabler/UniverseGen): consume centralized constants" - ``` - ---- - -### Task 23: Localization key governance - -**Files:** -- Modify: `UXAssist/UIConfigWindow.cs` -- Modify: `CheatEnabler/UIConfigWindow.cs` -- Modify: `UniverseGenTweaks/UIConfigWindow.cs` -- Modify: `CheatEnabler/Functions/PlayerFunctions.cs` -- Modify: `UXAssist/Patches/Factory/BeltSignalPatch.cs` - -- [ ] **Step 1: Replace hard-coded Chinese `.Translate()` keys with `I18N.Add` entries** - - Example: - ```csharp - // Before - var btn = MyWindow.AddButton(..., "确定", ...); - // After - I18N.Add("OK", "OK", "确定"); - var btn = MyWindow.AddButton(..., "OK", ...); - ``` - -- [ ] **Step 2: Translate Chinese comments to English** - - Run a search for `// ` followed by CJK characters and translate or delete stale comments. - - ```bash - grep -RInP '//.*[\x{4e00}-\x{9fff}]' UXAssist/ CheatEnabler/ UniverseGenTweaks/ --include='*.cs' || true - ``` - -- [ ] **Step 3: Build all three projects** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - dotnet build CheatEnabler/CheatEnabler.csproj -c Release - dotnet build UniverseGenTweaks/UniverseGenTweaks.csproj -c Release - ``` - -- [ ] **Step 4: Commit** - - ```bash - git add UXAssist/ CheatEnabler/ UniverseGenTweaks/ - git commit -m "refactor: localize hard-coded strings and translate comments" - ``` - ---- - -## Phase 4 — Static State & Lifecycle Cleanup - -### Task 24: Inventory static mutable state - -**Files:** -- Create: `docs/StaticStateInventory.md` - -- [ ] **Step 1: List all static mutable fields in the three projects** - - Search: - ```bash - grep -RInP 'private static (?!readonly)\S+' UXAssist/Patches/ UXAssist/Functions/ CheatEnabler/Patches/ CheatEnabler/Functions/ UniverseGenTweaks/ --include='*.cs' > docs/StaticStateInventory.md - grep -RInP 'public static (?!readonly)\S+' UXAssist/Patches/ UXAssist/Functions/ CheatEnabler/Patches/ CheatEnabler/Functions/ UniverseGenTweaks/ --include='*.cs' >> docs/StaticStateInventory.md - ``` - -- [ ] **Step 2: Classify each field by subsystem** - - Mark each as: - - `LifecycleSafe` — read-only after `Awake` - - `NeedsReset` — must be cleared on `GameLogic.OnGameEnd` - - `CandidateForInstancing` — should be owned by a per-game context class - -- [ ] **Step 3: Commit** - - ```bash - git add docs/StaticStateInventory.md - git commit -m "docs: inventory static mutable state" - ``` - ---- - -### Task 25: Add lifecycle reset callbacks - -**Files:** -- Modify: `UXAssist/Patches/Factory/BeltSignalPatch.cs` -- Modify: `UXAssist/Patches/Factory/VeinProtectionPatch.cs` -- Modify: `UXAssist/Patches/DysonSpherePatch.cs` -- Modify: `UXAssist/Functions/UI/MilkyWayUI.cs` -- Modify: `CheatEnabler/Patches/Factory/BeltSignalPatch.cs` -- Modify: `UniverseGenTweaks/Patches/GalaxySelectUIPatch.cs` - -- [ ] **Step 1: Add `ResetState` methods** - - Example: - ```csharp - internal static void ResetState() - { - _signalBelts = null; - _someCache.Clear(); - } - ``` - -- [ ] **Step 2: Register resets in `Init`** - - ```csharp - public static void Init() - { - GameLogic.OnGameEnd += ResetState; - // ... - } - ``` - -- [ ] **Step 3: Build all three projects** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - dotnet build CheatEnabler/CheatEnabler.csproj -c Release - dotnet build UniverseGenTweaks/UniverseGenTweaks.csproj -c Release - ``` - -- [ ] **Step 4: Commit** - - ```bash - git add UXAssist/ CheatEnabler/ UniverseGenTweaks/ - git commit -m "refactor: register static-state resets on game end" - ``` - ---- - -## Phase 5 — Transpiler Robustness & Quality Gates - -### Task 26: Annotate transpilers with target version and fallback - -**Files:** -- Modify: all `*Transpiler` methods in `UXAssist/Patches/`, `CheatEnabler/Patches/`, `UniverseGenTweaks/Patches/` - -- [ ] **Step 1: Add header comments** - - ```csharp - // Target game version: 0.10.34.28505 - // Patches: EjectorComponent.InternalUpdate - // Falls back to original IL if the pattern is not matched. - private static IEnumerable ... - ``` - -- [ ] **Step 2: Wrap `CodeMatcher` finalization** - - Replace bare `.InstructionEnumeration()` with: - ```csharp - return matcher.ReportFailure(original, Logger)?.InstructionEnumeration() ?? instructions; - ``` - - Implement extension: - ```csharp - public static CodeMatcher ReportFailure(this CodeMatcher matcher, MethodBase original, ManualLogSource logger) - { - if (matcher.IsValid) return matcher; - logger?.LogWarning($"Transpiler failed for {original.DeclaringType?.Name}.{original.Name}"); - return null; - } - ``` - -- [ ] **Step 3: Build all three projects** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - dotnet build CheatEnabler/CheatEnabler.csproj -c Release - dotnet build UniverseGenTweaks/UniverseGenTweaks.csproj -c Release - ``` - -- [ ] **Step 4: Commit** - - ```bash - git add UXAssist/ CheatEnabler/ UniverseGenTweaks/ - git commit -m "refactor: add transpiler version/fallback annotations" - ``` - ---- - -### Task 27: Centralize third-party compat reflection targets - -**Files:** -- Create: `UXAssist/ModsCompat/CompatTargets.cs` -- Modify: `UXAssist/ModsCompat/AuxilaryfunctionWrapper.cs` -- Modify: `UXAssist/ModsCompat/BulletTimeWrapper.cs` -- Modify: `UXAssist/ModsCompat/BlueprintTweaks.cs` - -- [ ] **Step 1: Extract magic strings** - - ```csharp - internal static class CompatTargets - { - public const string Auxilaryfunction = "auxilaryfunction.Auxilaryfunction"; - public const string SpeedUpPatch = "Auxilaryfunction.SpeedUpPatch"; - // ... - } - ``` - -- [ ] **Step 2: Replace literal strings with constants** - -- [ ] **Step 3: Build UXAssist** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - ``` - -- [ ] **Step 4: Commit** - - ```bash - git add UXAssist/ModsCompat/ - git commit -m "refactor(UXAssist): centralize compat reflection targets" - ``` - ---- - -### Task 28: Add `.editorconfig` and run `dotnet format` - -**Files:** -- Create: `.editorconfig` -- Modify: all touched `.cs` files (format-only changes) - -- [ ] **Step 1: Create `.editorconfig`** - - Minimal content: - ```ini - root = true - - [*.cs] - indent_style = space - indent_size = 4 - charset = utf-8-bom - end_of_line = crlf - insert_final_newline = true - dotnet_sort_system_directives_first = true - dotnet_separate_import_directive_groups = false - ``` - -- [ ] **Step 2: Run format** - - ```bash - dotnet format UXAssist/UXAssist.csproj - dotnet format CheatEnabler/CheatEnabler.csproj - dotnet format UniverseGenTweaks/UniverseGenTweaks.csproj - ``` - -- [ ] **Step 3: Build all three projects** - - ```bash - dotnet build UXAssist/UXAssist.csproj -c Release - dotnet build CheatEnabler/CheatEnabler.csproj -c Release - dotnet build UniverseGenTweaks/UniverseGenTweaks.csproj -c Release - ``` - -- [ ] **Step 4: Commit** - - ```bash - git add .editorconfig - git add -u UXAssist/ CheatEnabler/ UniverseGenTweaks/ - git commit -m "style: add editorconfig and run dotnet format" - ``` - ---- - -## Final Verification - -- [ ] **Step 1: Full solution build** - - ```bash - dotnet build DSP_Mods.sln -c Release - ``` - - Expected: 0 errors. - -- [ ] **Step 2: Package all mods** - - ```bash - dotnet build -t:ZipMod -c Release - dotnet build -t:CopyToParentPackage -c Release - ``` - - Expected: all `package/` outputs generated. - -- [ ] **Step 3: Public API verification** - - Re-run the `docs/PublicApiSurface.md` checklist and confirm every listed member still exists. - -- [ ] **Step 4: Update `AGENTS.md`** - - If any project conventions changed (e.g., new folder structure, naming rules, `.editorconfig`), update `AGENTS.md` accordingly. - -- [ ] **Step 5: Final commit / tag** - - ```bash - git tag refactor-complete - ``` - ---- - -## Self-Review Checklist - -- [ ] Every task references exact file paths. -- [ ] No `TODO`, `TBD`, or placeholder steps remain. -- [ ] Public API contract (`UXAssist.UI` + `UXAssist.Common`) is preserved throughout. -- [ ] `CheatEnabler` and `UniverseGenTweaks` compile after each phase. -- [ ] Code snippets use types/methods defined in earlier tasks.