mirror of
https://github.com/soarqin/DSP_Mods.git
synced 2026-11-19 17:05:20 +08:00
Clear auto-construction orders on teardown and planet changes without overwriting manual orders, and reject auto-cruise startup while native autopilot is active. Reduce AGENTS.md to durable project guidance.
7.8 KiB
7.8 KiB
Agent Guidelines
Rules
- Update
AGENTS.mdafter completing every task; edit its current guidance directly rather than keeping a changelog. - Write all documentation and code comments in English.
- Inspect the original DSP game DLL, never the stripped publicized copy in
AssemblyFromGame/, when method bodies are required. Locate DSP using the Steam registry andsteamapps/libraryfolders.vdfasUpdateGameDlls.ps1does, then decompile<game_root>/DSPGAME_Data/Managed/Assembly-CSharp.dll. - Resolve in-game terminology from
<game_root>/Locale/:Namescontains keys,1033is English, and2052is Simplified Chinese.
Project
- This repository contains independent BepInEx 5.x C# mods for Dyson Sphere Program. HarmonyLib patches game methods at runtime;
UXAssistis the shared library used directly byCheatEnablerandUniverseGenTweaks. - Projects target
net472ornetstandard2.1with SDK-style.csprojfiles. Compile-time game references live inAssemblyFromGame/. DustbinPreloaderandLabOptPreloaderare Mono.Cecil preloaders; their main mods consume the injected fields without reflection.
Build
Directory.Build.propssupplies common frameworks, BepInEx packages, game references, warning policy, and theUpdateGameDllsdependency.Directory.Build.targetsdefinesZipModandCopyToParentPackage.- Normal validation:
dotnet build <project>/<project>.csproj -c Release --no-restore. - Refresh game references explicitly with
dotnet build UpdateGameDlls/UpdateGameDlls.csproj; the script compares timestamps and usesassembly-publicizer --strip --overwrite. Missing DSP or the publicizer is a warning, not a build failure. - Package main mods with
dotnet build -t:ZipMod -c Release; package preloaders withdotnet build -t:CopyToParentPackage -c Release. The mod.csproj<Version>is the single version source and packaging synchronizespackage/manifest.json. - Treat warnings as errors except the intentional obsolete API warning
0618; do not weaken this policy to hide new warnings.
Architecture
ModFeatureRegistrydiscovers dependent-mod features duringAwake; feature initialization is eager, while UXAssist alone drives the deferred start, input, update, and uninitialization lifecycle. Keep dispatchers internal and idempotent.- Register localization keys through each project registration class and use
.Translate()with keys. Do not add Chinese literals at call sites. - Prefer
UXAssist/Common/GameConstantsfor item, tech, logistics, and Dyson sphere constants instead of inline literals. - Persist mod data through
IModCanSavefrom DSPModSave. - Use
ModCompatHelperfor external plugin/type/member resolution and preserve legacy public type identities when refactoring reflection targets. UseDysonSphereReflectionfor DSPOptimizations-compatible Dyson sphere fields. - Performance-sensitive Harmony transpilers must include the standard target/fallback header and use
TranspilerGuardwhen a matcher can fail; returning original instructions is the fallback. PatchImpl<T>.Enable(true)must remain fail-soft: log, unpatch, and leave the patch unset if Harmony application fails so config delegate chains remain consistent.- Overlay UI state must converge from actual game state on periodic updates, not depend only on one-shot event or patch callbacks. Cloned controls must reset runtime state while retaining source styles; use
UXAssist.UI.Util.GetPreferredWidthfor dynamic text andResetButtonfor cloned buttons.
Verified Game Facts
- In the original
Assembly-CSharp.dll,PlanetFactory.prebuildCountisprebuildCursor - prebuildRecycleCursor - 1; investigate planet, factory, preview state, and UI refreshes before replacing it with a pool scan. ProductStat.cursorhas 12 rings: indices0..5are production and6..11are consumption. Production-panel reference rate comes fromrefProductSpeed, which the extra-info calculator may leave stale or zero until it runs.PlanetATField.physicsArgsis null until the first physics-shape recalculation. Immediate completion of the first Planetary Shield Generator must restore that invariant before shield UI reads it; Signal Towers do not share this race.- Estimated Dyson shell geometry can differ at numerical boundaries from the final rasterized polygon. If
QuickAddDysonShellrejects a candidate, try the next candidate rather than trusting the estimate.
Automation Invariants
Auto-construct
AutoConstructEnabledcontrols patch activation;AutoConstructButtonEnabledcontrols only button visibility. Never couple them.- Keep planning bounded and allocation-free: use the native 120-target construction capacity, fixed candidate limits, actual construction hash entries, and the same material-delivery and enemy-proximity eligibility rules as
ConstructionModuleComponent.GameTick. - Prebuild and player positions are planet-local. Derive angular fan axes in the planet-local frame, use great-circle surface distances, and preserve the game's surface-direction arrival semantics.
- Select a nearest local cluster before falling back to the nearest candidate; refine destinations from scanned ghosts. In the approach corridor, retain the closest route-prefix ghost so nearer work cannot be bypassed. When at most eight eligible ghosts remain, route directly to the nearest one; the existing scan caps the final-pass count at nine.
- A site is held only while its initial drone wave is below capacity and its throughput is competitive. Replan before the site empties when the remaining workload no longer covers the next flight.
- Normal route changes settle residual flight speed before issuing the new route. Recovery detours and their continuation/final routes bypass settling so they can take over while the mecha is stuck. Detours use collider footprint bounds and resume the construction route after completion.
- Clear the active auto
MoveToorder before resetting planner state during disable and planet changes, but clear it only when it is still the auto order so user orders are preserved.
Auto-cruise
PlayerPatch.AutoNavigationis the only auto-cruise implementation. Its Harmony patches followAutoCruiseEnabled; all user-facing terminology is auto-cruise /自动巡航, not the game's自动导航autopilot terminology.- Yield to
player.navigation.navigating. Starting requires a resolvable target and must reject an already-running native autopilot before showing a started notification. Reset target state and reusable obstacle data through one navigation lifecycle path. - Sail velocity uses the game's planet-frame blend
Clamp01((600 - altitude) / 450). Apply the same blend tovisual_uvel; do not writeuRotationfrom the sail postfix because the game recomputes it afterward. - Apply braking directly using the game's decay behavior. Fixed targets need an approach speed cap below the 75 m/s fly handoff threshold, and warp must release early enough for braking; manual warp speed input takes precedence.
- Preserve native flight input signs:
input0.y = 1is forward thrust,input1.y = 1is upward thrust, andinput0.zis the walk jump/takeoff axis. - Satellite routing uses a parent-body corridor and current-heading tangent selection. Null-check
SpaceSector.dfHives, which is absent in saves without hive data.
Input Timing
- Dispatch UXAssist shortcuts from the postfix of
VFInput.OnUpdate, after DSP refreshes modifier and UI state. Keep typing/menu guards and per-frame registry guards; do not poll from an independentUpdate()or logic-tick callback.
Review Standard
- Fix root causes with minimal focused changes. Do not alter unrelated behavior, add copyright headers, commit changes, or create branches unless requested.
- Before handoff, run the narrowest relevant build or test, then
git diff --check. Mention unrelated pre-existing failures instead of changing them.