mirror of
https://github.com/soarqin/DSP_Mods.git
synced 2026-11-19 17:05:20 +08:00
docs: consolidate production documentation
Move the blueprint description notes to the unreleased 1.6.3 entry and limit them to user-visible behavior, list the feature in the README, condense the production guidance in AGENTS.md to durable rules, and remove the completed planning documents that duplicated the architecture reference.
This commit is contained in:
1 parent
2ddf91ceab
commit
402d4008fb
5 files changed
+6
-384
No files matched your search
@@ -30,12 +30,8 @@
|
||||
|
||||
## Architecture
|
||||
|
||||
- Fixed-building UXAssist power reports include each selected logistics station, distributor, or battle base at its captured configured charging maximum in watts, not its transient draw. Keep factory and logistics consumption independently usable when the other category is unknown; retain the original total-power API and never display an incomplete category as zero. Keep charging power separate from accumulator exchange and do not double-count advanced miners or gas collectors. Blueprint and prebuild capture use native stored settings or prefab defaults when no charging setting is applied.
|
||||
- UXAssist production calculations must use immutable snapshots captured from loaded Proto, PrefabDesc, and Cargo data on the game thread. Keep the planner and fixed-building analyzer pure-managed, express material rates in double items per minute and power in watts, and report unknown material and power results independently with structured diagnostics. Convert native ticks, fixed-point speeds, and per-second rates explicitly. Use native facility-specific production and power rules; keep generation, accumulator charging and discharging, and Dyson-sphere demand separate. Require explicit resource and operating settings when they cannot be captured, and never capture transient runtime throttles such as the miner output damper. Treat a stored sandbox boost mode as applied only through an explicit or live-captured `BoostEnabled` state. Verify native rules against the original DLL, compile affected mods, and keep the synthetic `UXAssist/tools/ProductionCheck` checks passing; leave in-game validation to a person rather than automated gameplay or save parsing. See [production architecture](UXAssist/docs/ProductionArchitecture.md).
|
||||
- Production catalog synthetic recipe IDs are calculation-only negative output item IDs; never pass them to native recipe lookups or setters. Rebuild the catalog on game begin after preload mutations, and invalidate derived caches on `ProductionCatalogService.Changed`, including catalog clearing. Preserve accumulator coating through exchange and bound spray reuse by same-item output and demand. Live-selection operating overrides use signed object IDs; blueprint overrides use blueprint indices. Keep renewable generation at ideal rated conditions and do not count gas collectors' self-fueling as grid consumption.
|
||||
- Black-box material classification must use process net flows while retaining gross production and consumption. Attribute redundant whole-building output using one stable shared material budget that preserves final-product capacity and does not worsen internal shortages; derive coproduct surplus from retained whole buildings required by other products, crediting internal net consumption first. Do not relabel limiting-product or single-product headroom as a coproduct or change the original full-load report. Derive separate steady-state external inputs by throttling surplus upstream processes together with all their outputs and inputs, including fractional and multi-stage headroom; preserve independently known rated final outputs and do not worsen shortages. For incomplete materials, still cap independently known upstream inputs against known demand, but protect potential consumers of unresolved processes rather than treating their demand as zero. A blueprint research-mode lab protects all native matrices manufactured in the selection from upstream reduction; classify their positive net production after other buildings' known consumption as final research products without falsely reporting excess or adding fictitious gross consumption. Leave other uncertain overbuild, coproduct, and final-product conclusions unknown.
|
||||
- Blueprint auto-description reads only the current blueprint's buildings on button click. Keep the proliferation checkbox to the right of the button on one compact row above all description boxes. Shift the first native inspector group down once and the following groups after every refresh, restoring the original layout on disable. Replace the main description with nonempty Missing, Excess, Input, Output, and Research lines; group each warning category under one prefix, omit the per-minute suffix without changing rate units, and use only an optional power custom field with absent consumption categories omitted. Format material inputs from the separate steady-state estimate without altering full-load ledgers or power. Budget every research-mode lab at full prefab working power for conservative blueprint power capacity, even if current research is idle or technology is missing or invalid; apply a supported proliferation multiplier. Blueprint research treats one lab as an outlet for all six native matrix types actually manufactured within the selected buildings; capture their IDs independently of technology requirements and do not infer matrix demand, research speed, hashes, or external inputs from the current save. Display positive net matrix output only on Research, not ordinary Output; keep precise technology-dependent research requirements for callers without this blueprint assumption. Treat research power as independently complete when no other power category is unknown. Synchronize pending native field edits; update or remove exact bilingual power fields without changing any other custom fields, including fields titled Input or Output. Check the native description and field limits before writing, use native field escaping and item tags, and refresh the inspector without automatic saving or changes to native rendering or validation. Keep Spray Coater defaults and manual proliferation overrides scoped to the editing session; keep text formatting and field updates pure-managed under `ProductionCheck`. See [production architecture](UXAssist/docs/ProductionArchitecture.md).
|
||||
- CheatEnabler belt-signal upstream statistics use the shared production planner's independent production and consumption ledgers. Cache per-item material results by catalog and spray settings, keep separate per-belt fractional accumulators, and never run the solver in the logic tick. Missing data must not interrupt item generation.
|
||||
- UXAssist production calculations (catalog, planner, fixed-building analyzer, blueprint capture, and blueprint descriptions) are described in [production architecture](UXAssist/docs/ProductionArchitecture.md). Capture immutable Proto, PrefabDesc, and Cargo snapshots on the game thread and keep the calculation core pure-managed; report unknown material and power results independently instead of as zero. Verify special-building rules against the original DLL and update `UXAssist/tools/ProductionCheck` expectations with any rule change. Synthetic recipe IDs are calculation-only and must never reach native recipe lookups or setters.
|
||||
- CheatEnabler belt-signal upstream statistics use cached `ProductionPlanner` reports; never run the solver in the logic tick, and missing production data must not interrupt item generation.
|
||||
- UXAssist Dark Fog buy-out belt signals keep each item ID, per-Metaverse rate, localization key, and embedded icon path in one definition. Name embedded icon files after the current English item names and synchronize resource includes and loader paths when renaming them. Preserve the legacy signal and saved-stock order. Rates represent equivalent single-material value: a native bundle of 10 Silicon-based Neurons, 10 Negentropy Singularities, and 10 Matter Recombinators per Metaverse corresponds to 30 of any one selected material per Metaverse.
|
||||
- Tech downgrades must validate the full dependency cascade and capacity reductions before changing game state. Recompute non-invertible bonuses from native defaults and surviving levels; replaying unrelated unlock side effects can corrupt inventory geometry and station limits.
|
||||
- Custom critical-warning text must participate in both `WarningSystem.hasCriticalWarning` and `WarningSystem.UpdateCriticalWarningText`; preserve native warnings and use one shared display priority.
|
||||
|
||||
@@ -6,6 +6,7 @@
|
||||
* 1.6.3 - Unreleased
|
||||
* `Sunlight at night`: Base lighting on the camera and the viewed surface instead of Icarus's facing direction, including planet view. Keep building, terrain, solar-panel, and belt lighting directions synchronized, recover when the active light or planet changes, and restore native lighting when sailing, disabling the feature, or using white rendering mode.
|
||||
* `Quick build Mining Machines`: Add a Factory-tab button that searches dense layouts at the nearest solid vein group using native collision shapes, including interleaving feet, joint placement of nearby miners, and a final pass to fill remaining compatible positions. `Allow restoring/burying veins` is off by default: uses only visible nodes and skips all restoration and burial calculations. When enabled, restores available buried nodes and may bury unused nodes to improve coverage. Optimizes summed vein coverage, requires at least 3 covered nodes per miner after any burial, and places the full ordinary miner layout regardless of stock, leaving ghosts awaiting missing materials. Accelerates layout searches with up to 4 background workers, capped at half the available logical processors. Writes replayable JSON snapshots during feature tuning and keeps the completion tip visible for about 8 seconds.
|
||||
* `Blueprint descriptions`: Add an `Auto-fill description` button and a `Proliferation` checkbox above the description boxes in the blueprint browser, copy, and paste panels. The button replaces the main description with the blueprint's full-load material flows per minute on separate `Missing`, `Excess`, `Input`, `Output`, and `Research` lines, and writes factory and logistics power demand to a `Power` custom field. Inputs are limited to what downstream buildings can use, matrices made in a blueprint with a research-mode lab are listed under `Research`, and research-mode labs are budgeted at full working power. The checkbox defaults to on when the blueprint contains a Spray Coater. Unknown values are marked instead of shown as zero, other custom fields are preserved, and nothing is saved automatically.
|
||||
* 1.6.2
|
||||
* `Increase maximum power usage in Logistic Stations and Advanced Mining Machines`: Fix zero or corrupted mining speeds when adjusting an Advanced Mining Machine's speed slider with the option enabled.
|
||||
* `Tweak building buffers`: Restore the Ray Receiver Graviton Lens buffer setting on DSP 0.10.35.29104 and later, and correct the displayed native buffer value to 2.
|
||||
@@ -18,7 +19,6 @@
|
||||
* `Belt signals for buy out dark fog items automatically`: Use the current in-game material names and retain the original exchange ratios.
|
||||
* `Initialize This Planet`: Fix an occasional array index error after initializing a planet with Holo Beacons.
|
||||
* `Planet vein utilization`: Restore the original vertical alignment of vein-group counts and keep resource names in their original positions.
|
||||
* `Blueprint descriptions`: Add a row with an Auto-fill description button and a right-hand Proliferation checkbox above all description boxes in the browser, copy, and paste inspectors. Replace the main description with wrapping, nonempty Missing, Excess, Input, Output, and Research lines: group each warning category under one label and omit the per-minute suffix while keeping per-minute rates. Cap upstream inputs at sustainable downstream throughput even when unrelated parameters are unknown, without assuming unknown downstream demand is zero; keep independently known rated outputs and power. Budget every research-mode lab at full working power, and treat one selected lab as an outlet for all six matrix types made within the blueprint, regardless of the save's technology or research speed. Display positive net matrix output only under Research, after other buildings' known matrix use; keep unrelated final products under Output. Do not invent matrix consumption rates or imports, and do not flag the accepted output as excess. Keep Power as the only optional generated custom field, showing factory and logistics demand only when present and marking unknown demand separately. Report necessary coproducts and incomplete results, preserve other custom fields, and never save automatically. Fix false coproduct output in mixed production lines and at fractional building ratios.
|
||||
* 1.6.1
|
||||
* `Larger area for terraform`: Restore 11x11 through 30x30 foundation and Restore Terrain brushes after DSP 0.10.35.29104.
|
||||
* Fix the title-screen background turning black, even when the UXAssist window is closed.
|
||||
@@ -441,6 +441,7 @@
|
||||
* 1.6.3 - Unreleased
|
||||
* `夜间日光灯`:按镜头和当前观察位置的地表方向计算光照,不再跟随机甲朝向,行星视图也适用。统一建筑、地表、太阳能板和传送带的光照方向,在光源或行星切换后恢复功能,并在航行、关闭功能或白模渲染时恢复原版光照。
|
||||
* `快速铺设采矿机`:在「工厂」页增加按钮,按游戏实际碰撞体在最近的固体矿脉搜索密集布局,支持脚部交错、邻近矿机联动调整及结束前补入剩余可用位置。「允许恢复/掩埋矿物」默认关闭:仅使用可见矿点,跳过所有恢复和掩埋计算;开启后,恢复可恢复的掩埋矿点,并允许掩埋未被使用的矿点来提高覆盖数。以各台矿机覆盖矿点数之和为目标,要求每台在掩埋后仍覆盖至少 3 个矿点,不受库存限制地生成完整布局,缺少采矿机的位置保留待建造虚影。使用最多 4 个后台线程加速布局搜索,线程数不超过可用逻辑线程数的一半。功能调试期间输出可离线重放的 JSON 数据,完成提示保留约 8 秒。
|
||||
* `蓝图说明`:在蓝图浏览、复制和粘贴界面的说明框上方增加「自动填写说明」按钮和「增产」复选框。点击按钮会用蓝图满负荷运行时每分钟的物料流量替换原说明,按需分行列出「缺少」「多余」「输入」「输出」「研究」,并将工厂与物流耗电写入「耗电」自定义字段。输入量以下游建筑实际能消耗的量为限;蓝图含研究模式研究站时,蓝图内产出的矩阵列入「研究」行,研究模式研究站均按满负荷计入耗电。蓝图含喷涂机时,复选框默认勾选。无法计算的数值会单独标注而不显示为零,其他自定义字段保持不变,也不会自动保存蓝图。
|
||||
* 1.6.2
|
||||
* `提升物流塔和大型采矿机的最大功耗`:修复启用后调整大型采矿机开采速度时出现 0% 或异常速度的问题。
|
||||
* `调整建筑输入缓冲`:修复 DSP 0.10.35.29104 及后续版本中射线接收器透镜缓冲设置不生效的问题,并将显示的游戏原始值更正为 2。
|
||||
@@ -453,7 +454,6 @@
|
||||
* `用于自动购买黑雾物品的传送带信号`:统一使用当前游戏中的材料名称,保留原有兑换比例。
|
||||
* `初始化本行星`:修复行星上存在全息信标时,初始化后可能出现数组越界报错的问题。
|
||||
* `宇宙视图行星/星系矿脉数量显示`:修复矿脉数量文字偏下和矿物名称向右偏移的问题。
|
||||
* `蓝图说明`:在蓝图浏览、复制和粘贴界面的所有说明框上方增加「自动填写说明」按钮,并将「增产」复选框放在按钮右侧。直接用可换行内容替换原说明:按需依次显示「缺少:」「多余:」「输入:」「输出:」「研究:」,缺少或多余的物品共用一次行标签;标签不再显示「每分钟」,材料速率仍按每分钟计算。上游产量超过下游需求时,即使其他参数未知,也按已知下游的可持续产量估算输入;不把未知下游需求当作零。独立可确定的输出和耗电仍按额定值计算。所有研究模式研究站都按额定满负荷计入耗电;只要蓝图内有一座研究站,就假设它能接纳蓝图内产出的全部六种矩阵,不受存档科技或研究速度影响。扣除蓝图内其他建筑已知的矩阵消耗后,仅将净产量写入「研究」行;其他最终产物仍写入「输出」行。既不虚构研究站的矩阵消耗速率或外部需求,也不把被接纳的矩阵计为多余产量。仅在有耗电或耗电未知时生成「耗电」自定义字段,分别标注工厂与物流的有效类别。标出必要的联产盈余和数据不完整的结果;保留其他自定义字段,也不自动保存蓝图。修复混合生产线及非整数建筑配比下的副产物误报。
|
||||
* 1.6.1
|
||||
* `范围铺设地基的最大区域扩大`:适配 DSP 0.10.35.29104,恢复 11x11 至 30x30 的铺设地基与恢复地形范围。
|
||||
* 修复标题画面背景变黑的问题,包括关闭 UXAssist 窗口后背景仍不显示的情况。
|
||||
|
||||
@@ -17,6 +17,7 @@
|
||||
* Strict hotkey dectection for build menu, thus building hotkeys(0~9, F1~F10, X, U) are not triggered while holding Ctrl/Alt/Shift.
|
||||
* Fix a bug that warning popup on `Veins Utilization` upgraded to level 8000+
|
||||
* Sort blueprint structures before saving, to reduce generated blueprint data size a little
|
||||
* Add an `Auto-fill description` button and a `Proliferation` checkbox to the blueprint browser, copy, and paste panels, to fill the description with the blueprint's material flows per minute and its power demand
|
||||
* Increase maximum count of Metadata Instantiations to 20000 (from 2000)
|
||||
* Increase capacity of player order queue to 128 (from 16)
|
||||
* Enable `Hide UI` (`F11` by default) in Star Map view, hiding UI and other scene elements
|
||||
@@ -219,6 +220,7 @@
|
||||
* 更严格的建造菜单热键检测,因此在按住Ctrl/Alt/Shift时不再会触发建造热键(0~9, F1~F10, X, U)
|
||||
* 修复了`矿物利用`升级到8000级以上时弹出警告的bug
|
||||
* 保存蓝图前对建筑进行排序,以减少生成的蓝图数据大小
|
||||
* 在蓝图浏览、复制和粘贴界面增加「自动填写说明」按钮和「增产」复选框,用蓝图每分钟的物料流量和耗电自动填写说明
|
||||
* 将元数据提取的最大数量增加到20000(原来为2000)
|
||||
* 将玩家指令队列的容量增加到128(原来为16)
|
||||
* 在星图视图中启用 `隐藏 UI` 功能(默认按键为 `F11`),同时隐藏 UI 和场景中的其他元素
|
||||
|
||||
@@ -1,186 +0,0 @@
|
||||
# UXAssist Automatic Blueprint Description Plan
|
||||
|
||||
Status: Updated implementation specification, September 27, 2026.
|
||||
|
||||
The maintained production reference is [ProductionArchitecture.md](ProductionArchitecture.md). This document records the current behavior and acceptance criteria for the automatic blueprint description.
|
||||
|
||||
Keep shared production changes focused on this feature, update affected callers and tests, and preserve existing full-load accounting.
|
||||
|
||||
## 1. Confirmed Behavior and Display
|
||||
|
||||
Add an **Auto-fill description** button and a **Proliferation** checkbox to the shared blueprint inspector used in browser, copy, and paste modes. Place the checkbox immediately to the right of the button in one compact row above every description box, including the smaller description fields and the main description. On generation, replace the existing main description text with nonempty missing, excess, input, output, and research lines; use at most one native custom field for power. Preserve the author, version, short description, and unrelated custom fields.
|
||||
|
||||
| Purpose | English label | Simplified Chinese label | Value format |
|
||||
| --- | --- | --- | --- |
|
||||
| Generate or update | Auto-fill description | `自动填写说明` | Button |
|
||||
| Calculation setting | Proliferation | `增产` | Checkbox |
|
||||
| Optional power field | Power | `耗电` | Present factory and/or logistics consumption only |
|
||||
| Description missing line | Missing: | `缺少:` | Intermediate shortages, with the label shown only once |
|
||||
| Description excess line | Excess: | `多余:` | True overbuild, with the label shown only once |
|
||||
| Description input line | Input: | `输入:` | External inputs only, at estimated steady-state rates |
|
||||
| Description output line | Output: | `输出:` | Ordinary final products and necessary coproduct surplus |
|
||||
| Description research line | Research: | `研究:` | Net positive matrix output accepted by selected research-mode labs |
|
||||
|
||||
The Chinese power example is `工厂耗电 2.5GW | 物流耗电 600MW` when both categories consume power. Omit a category without consumption; if neither consumes power, do not create the power field and remove an obsolete matching one. Keep a present but unmeasurable category marked as `未知`. Each material entry has the form `<item icon>Item name x100`. All material rates remain items per minute, but no description label includes the time unit. Separate items with commas, write each label only once per line, and put newlines only between nonempty lines in this order: missing, excess, input, output, research. Omit empty categories even when material data is incomplete; a warning-only description has no empty input line.
|
||||
|
||||
Use the native multiline description so long material lines wrap within the large editor. The power custom field remains single-line; do not add line breaks to custom fields, custom newline tokens, hidden ownership markers, sidecar metadata, a custom serialization format, or a mod-specific display protocol. Do not extend the native text renderer.
|
||||
|
||||
Use native item icon/name tags so the stored text remains compatible with ordinary blueprint saving and sharing. Round only for display, omit unnecessary trailing zeros, and do not display an unknown value as zero. Register UI strings, line labels, and the power field title through UXAssist's localization registration and use translation keys at call sites.
|
||||
|
||||
## 2. Inspector Integration and Safe Field Updates
|
||||
|
||||
### Proliferation setting
|
||||
|
||||
- Initialize the checkbox from whether the current blueprint contains a Spray Coater. Use the building's native prefab capability rather than its localized name.
|
||||
- While the user has not overridden the setting, update that default when the blueprint contents change. Preserve a manual override for the current editing session; opening or switching to another blueprint resets the default.
|
||||
- Changing the checkbox does not rewrite the blueprint. Replace the description and update the optional power field only when the button is clicked.
|
||||
- When enabled, use the highest proliferation level supported by the captured catalog and preserve each building's extra-products or acceleration mode.
|
||||
- Retain the black box analyzer's existing assumption that input coating is supplied externally. The presence of a Spray Coater only initializes the checkbox; it does not establish spray routing or justify adding an inferred proliferator-consumption flow.
|
||||
|
||||
### Click-to-write flow
|
||||
|
||||
1. Synchronize pending custom-field edits before reading native fields, so clicking the button does not discard unsaved manual field changes. The existing main description is intentionally replaced, including pending text there.
|
||||
2. Read the inspector's current blueprint. Capture its buildings on the game thread with `BlueprintSelectionReader.FromBlueprint`, then create a request using the checkbox value and call `FactoryBlackBoxAnalyzer.Analyze`. Do not substitute the current planet's entire factory or live inventories.
|
||||
3. Format a power value and up to five labeled description lines (Missing, Excess, Input, Output, Research), omitting empty categories. Keep calculation and formatting separate from Unity controls so their behavior can be checked with synthetic data. Refuse descriptions longer than the native 2,000-character limit before making generated changes.
|
||||
4. Match only existing power custom fields by exact registered English or Chinese titles. Update one power field in place or append one when needed; merge duplicate matching power fields, and remove matching power fields when neither category consumes power. Do not inspect or delete input/output custom fields. Preserve every other field and its order, and do not search ordinary description prose for loose matches.
|
||||
5. Check the native field capacity before changing generated data. If a required new power field cannot fit, explain the limit and leave the existing description and fields unchanged.
|
||||
6. Commit both the prepared custom-field string and replacement `blueprint.desc`, update the native description input, and refresh the inspector through its native modification path. Refresh the displayed description, fields, and share-code preview, but do not save or overwrite a file automatically. The native save and copy buttons remain responsible for those actions.
|
||||
|
||||
Use existing UXAssist UI helpers and native styling. Reserve one compact row above all description fields for the button and its right-hand checkbox, not between smaller fields and the main description. Shift the first inspector group and following groups down together, increase the scroll content height, and size localized labels using the established UI utilities. Keep creation, event registration, refresh, and cleanup idempotent across inspector reuse and game sessions. Do not run the calculation repeatedly in a logic tick or per-frame update.
|
||||
|
||||
### Native integration reference
|
||||
|
||||
These integration points were checked in the original installed game DLL. Recheck their signatures and behavior against the original DLL after game updates, following the repository's Steam-install discovery guidance. Do not use stripped publicized method bodies as evidence.
|
||||
|
||||
- `UIBlueprintInspector` is shared by its `Browser`, `Copy`, and `Paste` usages. It stores the current `blueprint` and provides native refresh and custom-field editing paths.
|
||||
- Native `Refresh` recalculates `descGroupTrans.anchoredPosition`, `group1.sizeDelta`, the following groups' positions, and `contentTrans.sizeDelta`, but does not reset `group1.anchoredPosition`. Move `group1` down once while the controls are active, position their row above its first native field, offset the following groups and scroll height after each native refresh, and restore the one-time shift on teardown. Do not move only `descGroupTrans`: that puts the new row between description sections.
|
||||
- `BlueprintData.desc` stores the multiline description, including native item tags. Assign the inspector's `descTextInput.text` when replacing it because `Refresh(forModify: true)` does not reload that input from the blueprint. `BlueprintData.externalFields` stores custom fields; apply `ExternalFieldEscape` and `ExternalFieldUnescape` to power names and values.
|
||||
- `UIBlueprintInspector.CollectExternalFields`, `OnCustomFieldEndEdit`, and `Refresh` establish the native collection and refresh sequence. Collect current edits before replacing generated values, not afterward.
|
||||
- `UIBlueprintInspector.kMaxFieldCount` supplies the field limit; it was 20 in the inspected game build. A power update requires no new slot; unrelated custom fields are never removed to make room. The inspector rejects a `desc` longer than 2,000 characters; refuse that generated text instead of leaving the blueprint unsavable.
|
||||
- `BlueprintData.Validate` removes literal newlines from native custom-field content, and the inspector lays out those fields at a fixed row height. It does not strip newlines from the main `desc`. Keep multiline text there, not in custom fields, without globally patching validation.
|
||||
- `UIInputField` uses `LDB.signals.IconTag`; its `includeName` option supplies the native icon and localized item name together in the description text. The blueprint's normal serialization escapes and restores that text.
|
||||
|
||||
## 3. Material Classification and Shared API Changes
|
||||
|
||||
### Preserve the full-load report
|
||||
|
||||
Calculate from the buildings, recipes, and settings actually present in the blueprint. Keep all selected buildings at their modeled full load, even when upstream production is insufficient. Do not simulate belt reachability, logistics throughput, startup inventories, or runtime throttling.
|
||||
|
||||
Keep `GrossProduction`, `GrossConsumption`, `NetFlow`, producer/consumer attribution, and the original power calculations available. Material rates remain `double` items per minute and power remains watts.
|
||||
|
||||
For classification, account for a process's net production and consumption of each item. A material returned or recirculated within the same recipe must not become a false external requirement or surplus merely because it appears in both gross ledgers. Preserve the gross ledgers themselves for existing callers.
|
||||
|
||||
### Separate shortages, true overbuild, and coproducts
|
||||
|
||||
Extend the shared report with numeric results for:
|
||||
|
||||
- Intermediate material shortages requiring additional external supply.
|
||||
- Net surplus attributable to genuinely redundant whole buildings.
|
||||
- Net coproduct surplus left by necessary joint production after internal use.
|
||||
|
||||
One item can have both overbuild surplus and necessary coproduct surplus. Represent the amounts separately; a mutually exclusive item classification or a single boolean is insufficient. The existing per-item `IsExcessIntermediate` threshold alone does not prove that a building is redundant.
|
||||
|
||||
Use all products of a production group together when checking redundancy:
|
||||
|
||||
- Group equivalent buildings and process them in a stable order based on recipe, building, and operating settings so blueprint array order does not affect the result.
|
||||
- Iteratively test whole-building reductions against the shared material balance. A reduction qualifies only if it does not lower final-product capacity and does not create or enlarge an internal material shortage.
|
||||
- All items share the same selected redundant-building set and material budget. Do not independently claim the same surplus for several alternative reductions.
|
||||
- Attribute overbuild and coproduct quantities to the original report without double-counting mixed single-output and multi-output producers. Do not classify a material solely by its position in the recipe's result array.
|
||||
- Preserve the existing treatment of sub-building single-product ratio headroom as normal balance rather than an overbuild warning.
|
||||
|
||||
The whole-building reduction is only a classification calculation. Keep the actual blueprint's gross full-load inputs, outputs, original external-supply ledger, and rated power in the shared report. This feature does not remove buildings or become a separate factory-layout optimizer.
|
||||
|
||||
### Steady-state input demand
|
||||
|
||||
The displayed input rates must account for upstream production blocked by surplus intermediates. After identifying redundant whole buildings, allow fractional reductions of the remaining processes until each intermediate's production meets downstream demand. Apply each process reduction to all its inputs and joint products together; preserve rated final-product capacity and never enlarge an existing intermediate shortage. Propagate reductions through multiple upstream stages using a stable process order. The resulting external input is a separate steady-state estimate, not a replacement for gross full-load ledgers, output classification, or rated power. When other materials are incomplete, still cap independently known upstream processes against their known downstream demand and label the resulting input as a known portion. Do not mistake unmodeled downstream demand for zero: protect an unresolved process's known inputs, or all known products if its possible inputs are unknown. Keep whole-building overbuild and coproduct conclusions unknown until the material selection is complete.
|
||||
|
||||
A blueprint research-mode lab is a terminal outlet for all six native matrix types manufactured inside that same blueprint. One selected lab is enough to preserve the full rated output of every matrix producer, even when other known processes use some of those matrices. Classify positive net matrix production as final research output and place it on the separate Research line, not the ordinary Output line or an excess/coproduct entry. Subtract other buildings' known matrix consumption from the displayed research quantity, but do not add virtual research consumption to the gross material ledger or invent external matrix inputs. Other buildings' known matrix requirements still count, including external supply when no matrix is produced. Without a selected research-mode lab, use ordinary material classification and upstream throttling. This is a blueprint-planning assumption about where manufactured matrices can go, not a claim that a real lab has unlimited research throughput.
|
||||
|
||||
### Description lines
|
||||
|
||||
- If present, place intermediate shortages on a `Missing: ` / `缺少:` line and true overbuild on a separate `Excess: ` / `多余:` line, in that order before Input. Put each label only once before its comma-separated item list, not before every item. Do not mix warnings into Input or repeat a shortage as an ordinary input.
|
||||
- Put only external raw-material inputs in the Input line, using the estimated steady-state rate rather than theoretical gross consumption.
|
||||
- Put ordinary final products and necessary net coproduct surplus in the Output line. Do not include the overbuild portion again or duplicate research matrices here.
|
||||
- Put positive net matrix output accepted by a selected research-mode lab in the separate Research line, after Output. For example, 12 matrices produced per minute minus 1 consumed by another selected process yields 11 per minute in Research, not 12; omit this line if no matrices are made or none remain.
|
||||
- Merge entries for the same item within a category and sort each category by item ID. Use commas between entries and keep all rates in items per minute even though the labels omit the unit. Omit an entire line if it has no entries; do not generate `None` or `Unknown` as a stand-alone material line. Mark known entries as partial when material results are incomplete.
|
||||
|
||||
### Required joint-production example
|
||||
|
||||
Each upstream building produces A60 and B60 per minute. Internal downstream requirements are A120 and B30 per minute, and downstream capacity remains fixed.
|
||||
|
||||
| Selected upstream buildings | Original A/B production | True overbuild shown in Excess | Necessary coproduct shown in Output |
|
||||
| --- | --- | --- | --- |
|
||||
| 2 | A120, B120 | None | B90 |
|
||||
| 3 | A180, B180 | A60, B60 | B90 |
|
||||
|
||||
In the three-building case, preserve gross consumption and rated power for all three buildings, but display external input for only the two upstream buildings needed by downstream demand. Do not reclassify the entire B150 net surplus as overbuild, and do not report B150 as coproduct output while also warning about the redundant B60.
|
||||
|
||||
## 4. Power, Scope Boundaries, and Incomplete Results
|
||||
|
||||
### Independent power categories
|
||||
|
||||
Extend `ProductionReport` with independently usable factory-consumption and logistics-consumption results and completeness information. Preserve the existing total-power API and migrate affected callers without weakening their accounting.
|
||||
|
||||
- Factory consumption includes production buildings and non-logistics auxiliary demand, including sorters and Spray Coaters.
|
||||
- Logistics consumption uses stored configured charging limits, or native prefab defaults where no charging setting is applied, for the selected logistics facilities. Do not use transient draw.
|
||||
- Do not subtract generation from consumption. Keep accumulator exchange and logistics charging distinct and count charging demand only once. Do not add a second logistics charging term to advanced miners or grid consumption for gas collectors' self-fueling.
|
||||
- Unknown factory power must not discard known logistics power, or vice versa. For example, `工厂耗电 未知 | 物流耗电 600MW` is valid when only the factory total is unknown.
|
||||
- A research-mode lab blueprint does not store its current technology or research speed. Capture native `LabComponent.matrixIds` with the catalog and mark blueprint labs as `ResearchMatrixSink`; do not consult current technology, technology requirements, unlock state, or research speed to determine matrix use. An assumed lab has no numeric matrix input or hash throughput in the report. Other callers without this blueprint assumption still need explicit `TechId` and `ResearchSpeed` to calculate exact research flows. If native matrix item IDs are unavailable, retain an incomplete material result instead of treating the lab as unable to accept matrices.
|
||||
- Budget every selected research-mode lab at its full prefab working consumption, including labs currently unable to research or with invalid technology data. Apply the selected proliferation power multiplier when available; use base working power when no spray level is supported. This deliberately conservative estimate protects blueprint power capacity and keeps factory and total power independent of material-rate assumptions.
|
||||
- Omit a power category when its demand is known to be zero; do not show `0W` for an absent factory or logistics consumer. An unknown category tied to a selected building remains visible as `Unknown`. If neither category has consumption, do not create a power field and remove an earlier generated one.
|
||||
|
||||
### Blueprint-only scope and missing data
|
||||
|
||||
- Do not generate description entries or requested-parameter lists for veins or other scene objects that are not part of a blueprint. Do not expand this feature into a resource-context or planet-analysis interface.
|
||||
- If a building actually present in the blueprint still lacks a necessary operating parameter, retain independently calculable results and explicitly mark the affected result incomplete. The research-mode matrix outlet assumption above is an intentional exception; do not invent other external conditions.
|
||||
- Preserve the common analyzer's resource and operating-parameter requirements for its other callers; the description feature's scope does not authorize globally suppressing those diagnostics.
|
||||
- Keep material and power completeness independent. Mark partial material values as known portions, cap known upstream inputs against known demand, and suppress any final-output, overbuild, or coproduct conclusion that unresolved downstream consumers could invalidate.
|
||||
- An invalid blueprint, unavailable catalog, calculation exception, overlong description, or insufficient field capacity must leave the existing description and custom fields unchanged and show a useful localized explanation. A failed or unavailable calculation is not a complete empty report.
|
||||
|
||||
## 5. Validation and Maintenance
|
||||
|
||||
### Synthetic checks
|
||||
|
||||
Extend `UXAssist/tools/ProductionCheck` with focused tests for:
|
||||
|
||||
- The two- and three-building joint-production example above.
|
||||
- A shared item supplied by both single-output and multi-output processes, including simultaneous coproduct and overbuild amounts without duplication.
|
||||
- Whole-building thresholds, fractional ratio headroom, internal deficits, and stable results after reordering blueprint buildings.
|
||||
- Internal material return and cyclic recipes without losing the original gross production/consumption ledgers.
|
||||
- Proliferation on/off, the highest captured supported level, and preservation of building acceleration/extra-product modes.
|
||||
- Independent material, factory-power, and logistics-power completeness, including one research lab accepting all six manufactured matrix types without technology data, invented external matrix inputs, or hash rates; preserve full-load power with and without supported proliferation.
|
||||
- No research station, no matrix production, one produced matrix type, multiple labs, and a separate building that genuinely needs external matrices. Classify positive net matrix production as final research output, preserve known gross flows, prevent false matrix coproduct or overbuild warnings, and avoid throttling producers whose matrix output has an assumed research outlet.
|
||||
- Separate steady-state external inputs for whole and fractional upstream excess, multi-stage dependencies, shared producers, order stability, and shortages; cap known upstream inputs in partially known layouts while protecting unresolved downstream demand. Preserve gross ledgers, independently known rated output, and power.
|
||||
- Pure formatting for separate nonempty Missing, Excess, Input, Output, and Research lines in that order, including multiple items per warning line without repeated labels. Verify labels omit the per-minute suffix without changing rate units. Cover long material lists, independent power-category omission, and present-but-unknown power; check that matrix output appears exactly once in Research at its net rate while non-matrix final output stays in Output.
|
||||
- Pure field updates for first generation, repeated updates, exact bilingual power-title recognition, duplicate power fields, preservation of all other fields including input/output titles, and native-capacity rejection without partial writes. Check the description length before committing either change.
|
||||
|
||||
Keep game-dependent capture and inspector code separate from the pure-managed sources compiled by these checks.
|
||||
|
||||
Run the narrow checks and affected builds from the repository root:
|
||||
|
||||
```powershell
|
||||
dotnet run --project UXAssist/tools/ProductionCheck/ProductionCheck.csproj -c Release
|
||||
dotnet build UXAssist/UXAssist.csproj -c Release --no-restore
|
||||
dotnet build CheatEnabler/CheatEnabler.csproj -c Release --no-restore
|
||||
dotnet build UniverseGenTweaks/UniverseGenTweaks.csproj -c Release --no-restore
|
||||
git diff --check
|
||||
```
|
||||
|
||||
### Manual game acceptance
|
||||
|
||||
- Check browser, copy, and paste inspectors in English and Simplified Chinese. Confirm the checkbox sits directly to the right of the button without overlap, their row precedes all small and main description boxes, and the native description wraps long icon/name material lines. Reopen, refresh, and change language to ensure the row stays at the top and the original layout returns when the feature is disabled.
|
||||
- Check checkbox defaults with and without a Spray Coater, blueprint-content changes before a manual override, preservation of a manual override during refresh, and reset after switching blueprints.
|
||||
- Generate with no existing fields, generate again, and generate with unrelated custom fields, including fields titled Input or Output. Confirm the main description replaces its previous text, at most one power field remains, and other fields and pending manual custom-field edits survive unchanged.
|
||||
- Try factory-only, logistics-only, both, neither, and partially unknown consumption. Confirm absent categories and the entire empty power field disappear, while genuinely unknown demand stays labeled. Confirm Missing and Excess each use one label followed by comma-separated items before Input, with no per-minute suffix on any description label; empty material categories produce no lines.
|
||||
- Reach the native field limit. Confirm a missing power field causes an all-or-nothing refusal without deleting other fields, while an existing power field can be updated and description-only generation remains possible. Generate a description over 2,000 characters and confirm it is rejected without changing the blueprint.
|
||||
- Save, reopen, copy a share code, and import it again through the native UI. Confirm description newlines, native item icons, the optional power field, and unrelated fields survive without a custom format or a modified renderer.
|
||||
- Confirm no file is written just by toggling proliferation or clicking generation, and that errors preserve the previous description and fields.
|
||||
- Compare full-load rates and configured logistics charging limits under suitable conditions. Do not compare against transient, starved, or output-blocked production.
|
||||
- With no external outlet for surplus intermediates, compare the description's input after upstream output buffers fill against downstream demand, including when an unrelated building lacks operating data. Confirm that unresolved downstream consumers prevent unsupported input reductions while known rated output and power remain independent.
|
||||
- Generate blueprints with one research-mode lab and six matrix types made inside the blueprint, then with only one matrix type or none. Confirm every manufactured matrix has an outlet and its positive net rate appears once in the Research line, after the unrelated final products in Output. Known consumption by another blueprint building reduces the Research rate; do not estimate lab matrix use, hashes, or external matrix demand. Vary current technology and research speed, add more labs, and toggle proliferation: matrix throughput must not change, but each lab must still contribute its full applicable working power. Without a lab, ordinary matrix output and overbuild rules apply.
|
||||
|
||||
Game validation is manual. Do not add automated gameplay or save-file parsing as an acceptance requirement.
|
||||
|
||||
### Documentation and repository hygiene
|
||||
|
||||
Keep the maintained English production architecture documentation and aligned English/Chinese changelog notes consistent with this behavior and the repository's version rules. Put only durable standards or maintained architecture references in `AGENTS.md`, not this task's progress, investigation evidence, or completed plan. Do not stage unrelated files, create a branch, or commit without an explicit request.
|
||||
@@ -1,190 +0,0 @@
|
||||
# UXAssist Production Planner and Factory Black Box Analysis Plan
|
||||
|
||||
Status: Implemented. Automated acceptance uses synthetic calculations and project builds; in-game verification is a separate manual step. The maintained interface and behavior reference is [ProductionArchitecture.md](ProductionArchitecture.md).
|
||||
|
||||
This document records the architecture plan agreed during the planning discussion on September 26, 2026. It is an implementation handoff; consult the maintained architecture reference for current behavior.
|
||||
|
||||
## 1. Goals and Scope
|
||||
|
||||
Introduce a shared production model in UXAssist with two independent calculation entry points:
|
||||
|
||||
- **Production planner:** Start from target items and required rates, then calculate upstream production, external material requirements, proliferator consumption, final surplus, and power requirements.
|
||||
- **Factory black box analyzer:** Start from a fixed building list and calculate material flows and power at full load. Do not replace game production updates or reduce downstream output automatically when upstream supply is insufficient.
|
||||
- Deliver reusable C# interfaces, a blueprint-selection adapter, and migration of CheatEnabler's existing upstream calculation in v1. Do not add a complete calculator UI or a black box analysis window.
|
||||
- Do not simulate belt reachability, logistics throughput, startup inventory, or transportation scheduling. Treat identical items inside a black box as shareable.
|
||||
- Represent material rates as `double` values in items per minute and public power values in watts. Preserve fractional values during calculation and format them only for presentation.
|
||||
|
||||
**Default assumption, not explicitly confirmed:** Joint planning may expand an already selected production line to supply another target through its coproducts. It must not introduce an unselected recipe, and any additional primary products must appear in the final surplus report. This was the last unanswered planning question; the recommended option is the default for this handoff.
|
||||
|
||||
This document-only task does not include implementation or changes to `AGENTS.md`. Keep implementation documentation in English. After implementation, agent guidance should contain only durable architecture rules or a reference to the maintained architecture document, not this plan's task history.
|
||||
|
||||
## 2. Shared Production Model and Interfaces
|
||||
|
||||
### 2.1 Data and Lifecycle
|
||||
|
||||
- Read recipes, items, buildings, and resources from loaded `LDB` data, Proto objects, and `PrefabDesc`. Read game rules not represented by Proto data, such as proliferation multipliers, from the game's `Cargo` tables. Implement special mechanics against the original game DLL, not the stripped publicized assembly.
|
||||
- Do not use an external recipe database or copy the reference calculator's data files. The algorithm reference is `DSPCalculator/dsp-calc`; it is not a runtime data dependency.
|
||||
- Capture immutable data snapshots on the game thread. The calculation core must not access Unity objects, current inventories, or mutable component pools. This keeps it independently testable and permits off-thread calculation after capture.
|
||||
- Return `DataNotReady` before preload completes and retry through `GameLogic.OnDataLoaded`. Invalidate relevant caches when the catalog is rebuilt, calculation settings change, or a game session ends.
|
||||
- Return structured diagnostics for missing recipes, building selections, and special operating parameters. Track material-result and power-result completeness separately; never silently represent unknown values as zero.
|
||||
|
||||
### 2.2 Public Entry Points
|
||||
|
||||
| Interface | Input and responsibility | Output |
|
||||
| --- | --- | --- |
|
||||
| `ProductionPlanner.Calculate` | Targets, external-material boundaries, recipe and proliferation policies, and building selections | External material requirements, delivered targets, final surplus, process details, and power |
|
||||
| `FactoryBlackBoxAnalyzer.Analyze` | Building snapshots, a global proliferation switch, and required special operating parameters | Aggregate flows, per-item shortages and surplus, final products, and power |
|
||||
| `BlueprintSelectionReader.Capture` | A `PlanetFactory` and the object IDs selected in blueprint mode | Building snapshots without retained mutable game-object references |
|
||||
| `BlueprintSelectionReader.FromBlueprint` | A `BlueprintBuilding` list and supplementary context | The same building-snapshot format, with missing settings identified explicitly |
|
||||
|
||||
The shared report retains `GrossProduction`, `GrossConsumption`, `NetFlow`, and per-building-group details. A report containing only raw materials and final products is insufficient for diagnostics and migration of production statistics.
|
||||
|
||||
### 2.3 Normalized Production Processes
|
||||
|
||||
Each process records its recipe or special-process identifier, inputs, outputs, building capability, effective proliferation strategy, and power terms. The same recipe with different buildings or strategies produces distinct processes. Do not average unlike processes before evaluating them.
|
||||
|
||||
Use a common evaluator for ordinary assembling, smelting, chemical processing, refining, particle processing, and matrix production. Use dedicated adapters for the following mechanics:
|
||||
|
||||
| Mechanic | Required behavior |
|
||||
| --- | --- |
|
||||
| Fractionation | Separate circulating throughput from net material consumption. Use native probability, proliferation, stacking, throughput, and power rules. Unconverted circulating material is not an external material consumption. |
|
||||
| Accumulator charging and discharging | Preserve empty/full item conversion, energy accounting, and proliferation inheritance. Charging consumes electricity; report discharge separately rather than treating it as newly generated energy. |
|
||||
| Photons and ray receivers | Distinguish photon generation from electricity generation and account for lens consumption. Keep Dyson-sphere-side energy requirements separate from factory-grid demand. |
|
||||
| Mining, water extraction, and collection | Determine outputs from the actual resource type, coverage, or caller-supplied resource configuration. Do not invent vein counts or collection conditions. |
|
||||
| Fuel generators, ejectors, silos, and research mode | Use native fuel, proliferation, and cycle rules. Count ammunition, fuel, and matrices as consumed items. Report launches and research hashes separately instead of inventing item outputs. |
|
||||
|
||||
Provide an extensible process-adapter interface for special mechanics. Report unsupported production buildings rather than silently omitting them.
|
||||
|
||||
## 3. Architecture One: Production Planner
|
||||
|
||||
### 3.1 Request Configuration
|
||||
|
||||
`ProductionPlanRequest` contains:
|
||||
|
||||
- **Targets:** Item IDs and required delivery rates per minute. Merge duplicate targets before solving.
|
||||
- **External-material boundaries:** Allow any intermediate item to be treated as an external input. Dark Fog materials are always external inputs; do not model enemy drops or their conditions.
|
||||
- **Recipe choices:** Select a primary recipe for each product. Direct production uses only selected recipes, while coproducts from other selected processes can satisfy demand.
|
||||
- **Proliferation settings:** Whether proliferation is enabled, the proliferator item, whether it is self-sprayed, and per-product choices of no proliferation, speedup, or extra products.
|
||||
- **Building selections:** Per-recipe choices override per-building-category choices. Do not automatically choose the highest-tier building.
|
||||
- **Additional configuration:** Known external surplus, operating parameters for special processes, and an optional auxiliary-building list.
|
||||
|
||||
When no primary recipe is specified, prefer the valid default production recipe provided by the Proto data. An explicit production recipe for a naturally obtainable resource overrides its default collection source. Explicitly marking an item as an external material stops its upstream expansion.
|
||||
|
||||
When proliferation is enabled without a per-product override, ordinary recipes follow the native available mode: extra products when supported, otherwise speedup. An explicit request for an unsupported extra-products mode is a configuration error, not permission to silently select another mode.
|
||||
|
||||
### 3.2 Global Material-Balance Solver
|
||||
|
||||
Use a global material matrix and linear programming, rather than recursively calculating each target independently and merging the results afterward.
|
||||
|
||||
Define:
|
||||
|
||||
- `A`: Net input/output matrix for the selected production processes.
|
||||
- `x`: Process executions per minute.
|
||||
- `r`: Allowed external material imports per minute.
|
||||
- `s`: Fixed external surplus supplied by the caller per minute.
|
||||
- `d`: Target delivery rates per minute.
|
||||
- `u`: Final surplus rates per minute.
|
||||
|
||||
The model satisfies:
|
||||
|
||||
`A * x + r + s = d + u`
|
||||
|
||||
Process execution rates, external imports, and final surplus are nonnegative. Import variables exist only for items permitted as external materials.
|
||||
|
||||
- Include all targets, coproduct reuse, cyclic recipes, and proliferator production in the same model so traversal order cannot change the result.
|
||||
- Generate only selected recipes and required special processes. Keep separate variables for distinct proliferation or building configurations.
|
||||
- Use a deterministic v1 objective: first minimize total process executions, then external imports, then remaining surplus. This is not a claim of minimum power, minimum building count, or minimum mineral value.
|
||||
- Implement an internal pure-managed two-phase simplex solver. Do not introduce a JavaScript runtime or a native solver dependency.
|
||||
- Include scaling, deterministic pivot selection, an iteration budget, cancellation, and a post-solve conservation check. Return diagnostics on failure rather than an unverified successful result.
|
||||
|
||||
### 3.3 Proliferator Self-Spraying
|
||||
|
||||
- Derive spray demand from the actual input flows requiring spraying under their production strategies.
|
||||
- Derive base sprays per bottle and additional sprays after self-spraying from Proto data and native rules. Also deduct the spray consumed by coating that bottle itself.
|
||||
- Include proliferator manufacturing and its own upstream inputs in the same solver model. Do not retain fixed proliferator ingredient tables or a fixed effective-sprays-per-bottle constant.
|
||||
- Support optional spraying of delivered target items so the existing belt-signal feature can express its finished-product spraying requirements.
|
||||
- Exclude initial seed inventory for cyclic processes from steady-state per-minute demand, but keep cyclic processes identifiable in the result.
|
||||
|
||||
### 3.4 Power and Results
|
||||
|
||||
- Return all external material requirements, delivered targets, final surplus, and the full intermediate production/consumption ledger.
|
||||
- Evaluate ordinary production power from the selected building's speed, working power, and proliferation power increase. Do not add idle power a second time to an already applicable working-power value.
|
||||
- Use equivalent fully utilized building counts for the power needed to meet target flow. Report rounded deployment counts and their peak power separately; do not round the material model.
|
||||
- Without a building selection, still calculate material results that do not depend on that choice, but mark power results incomplete.
|
||||
- Do not infer sorter or spray-coater counts from recipes without a layout. Include auxiliary power only when the caller supplies the auxiliary-building list, and identify the reported power scope explicitly.
|
||||
- Exclude logistics transportation and charging. Include accumulator charging used as a production process and report Dyson-sphere-side requirements separately.
|
||||
|
||||
## 4. Architecture Two: Factory Black Box Analyzer
|
||||
|
||||
### 4.1 Building Lists and Blueprint Capture
|
||||
|
||||
- Each production-building snapshot identifies its building type, recipe, actual speedup/extra-products mode, and required speed or special-process settings.
|
||||
- Decode blueprint-selection settings using the native `BuildingParameters` semantics instead of maintaining an unverified independent parameter-index table.
|
||||
- Deduplicate and validate object IDs. Support prebuilds and stacked labs. Analyze a prebuild using its known intended completed configuration, and report missing settings explicitly.
|
||||
- Capture must not refresh, modify, or clear the user's blueprint selection. Do not carry mutable component references into background calculation.
|
||||
|
||||
### 4.2 Proliferation and Full-Load Assumptions
|
||||
|
||||
- Expose only a global no-proliferation/full-proliferation choice. Do not infer proliferation levels from current input buffers or offer per-building level overrides in v1.
|
||||
- Determine the maximum level from the capabilities of available proliferator items, not the last index in a multiplier table.
|
||||
- Preserve each building's actual speedup/extra-products mode.
|
||||
- Turning the global switch off also disables proliferation effects for fuel, ejectors, silos, and other special consumers.
|
||||
- When enabled, assume required inputs were sprayed outside the black box. Do not add proliferator demand or a self-spraying production chain. A selected building that manufactures proliferators still contributes its ordinary recipe flows.
|
||||
- Evaluate all configured processes at full load. A material deficit represents the external supply needed to sustain that capacity; it does not reduce downstream theoretical output.
|
||||
|
||||
### 4.3 Balances and the One-Building Surplus Threshold
|
||||
|
||||
The black box has fixed recipes and building counts, so it does not need simplex optimization. Reuse the shared process evaluator, then aggregate each building's flows by item:
|
||||
|
||||
`NetFlow = GrossProduction - GrossConsumption`
|
||||
|
||||
- A negative net flow is the required external supply of that raw material or intermediate item.
|
||||
- A positive output without any internal consumer is a final product. Do not apply the intermediate-surplus threshold to it.
|
||||
- For an intermediate item, the surplus threshold is the smallest positive net output of one actual upstream building in the selection. Include its tier, actual proliferation mode, and any consumption of the same item by that process.
|
||||
- Classify positive intermediate surplus as excess only when it reaches this threshold. A positive balance smaller than one such building's capacity is normally balanced.
|
||||
- Keep numerical tolerance separate from the business threshold. Preserve all fractional ledger values; classification must not alter the true net flow.
|
||||
- Retain producer-group and consumer-group attribution so every intermediate balance can be explained. Excess equivalent to one building does not, by itself, establish that the building can safely be removed.
|
||||
|
||||
Example: two upstream buildings produce net rates of 60 and 120 items per minute. If internal consumption is 150, the remaining 30 is normally balanced. If consumption is 120, the remaining 60 reaches the threshold and is reported as excess.
|
||||
|
||||
### 4.4 Power and Generation
|
||||
|
||||
- Evaluate wind, solar, geothermal, and ray-receiver generation in a standard ideal environment: standard environmental multipliers, full illumination, completed continuous-receiving warmup, and sufficient Dyson sphere supply. Do not use current day/night conditions or temporary energy starvation.
|
||||
- Treat technology, speed settings, fuel, and operating mode as separate parameters, not environmental assumptions. Capture settings that can be determined from the selection and request missing information explicitly.
|
||||
- Sum rated demand for selected production buildings and non-logistics auxiliary facilities, including sorters and spray coaters. Buildings without a configured production process contribute idle demand.
|
||||
- Calculate generation using fuel properties and native proliferation rules. Do not apply a single manufacturing-building power multiplier to every generator.
|
||||
- Report consumption, generation, accumulator charging/discharging capacity, and Dyson-sphere-side requirements separately. A net-power value must not replace the breakdown.
|
||||
- Exclude logistics stations, distributors, transportation, and mecha charging in v1.
|
||||
|
||||
## 5. Implementation, Migration, and Acceptance
|
||||
|
||||
### 5.1 Implementation Order
|
||||
|
||||
1. Build the immutable catalog, public report types, and shared process evaluator. Cover ordinary recipes and proliferation first.
|
||||
2. Implement special-process adapters, the planner's matrix compiler, and the solver. Verify cyclic and multi-target conservation.
|
||||
3. Implement black box aggregation, the single-building surplus threshold, and blueprint-selection adapters.
|
||||
4. Replace the upstream-source calculation in `CheatEnabler/Patches/Factory/BeltSignalPatch.cs`, starting at `AddSourcesToBeltSignal`. Remove the old recursive algorithm from the active calculation path.
|
||||
5. Add English architecture documentation and usage examples. After implementation, update `AGENTS.md` only with stable architecture guidance or a documentation reference, not the plan or investigation history.
|
||||
|
||||
### 5.2 Existing-Feature Compatibility
|
||||
|
||||
- Preserve existing configuration keys, statistics switches, item generation, speed limits, and portal behavior.
|
||||
- Translate the old policy into a caller-side preset using Proto-validated item identifiers. Do not preserve incorrect hard-coded ingredient lists or incorrect statistics as compatibility requirements.
|
||||
- Apply production and consumption ledgers independently. A single quantity plus an `isExtra` flag cannot represent all cases. Avoid counting delivered target items twice.
|
||||
- Cache per-unit results by item and relevant settings, and retain independent fractional accumulators. The game logic tick applies precomputed results; it does not run the solver.
|
||||
- When data is not ready or calculation fails, suspend the affected additional upstream statistics and report the reason without blocking existing item generation.
|
||||
|
||||
### 5.3 Acceptance Scenarios
|
||||
|
||||
| Area | Required scenarios |
|
||||
| --- | --- |
|
||||
| Ordinary production | Building tiers, recipe durations, extra products, speedup, and nonproductive recipes agree with native data and mechanics. |
|
||||
| Global balancing | Multiple targets share coproducts; target order does not affect results; intermediate items can be external inputs; cyclic refining, external surplus, and infeasible settings are handled. |
|
||||
| Self-spraying | Cover each proliferator grade, self-spraying on/off, proliferator manufacturing, and finished-product spraying without duplicate charges. |
|
||||
| Black box flows | Cover mixed building tiers and modes, shortages at every intermediate stage, the minimum single-building net-capacity threshold, and fractional final-product rates. Shortages do not reduce downstream full-load output. |
|
||||
| Special power rules | Verify fractionation circulation, accumulator round trips, photon/grid separation, different fuels, ejectors, and research mode. Disabling the global proliferation switch also affects special facilities. |
|
||||
| Boundaries and migration | Cover empty selections, duplicate/stale IDs, prebuilds, stacked buildings, missing special settings, session transitions, calls before preload, and target statistics without double counting. |
|
||||
|
||||
Use an independent check program consistent with the repository's existing check-tool approach. Validate calculations with synthetic game-free scenarios and verify special mechanics against the original game DLL. In-game behavior should be checked separately by a person; parsing real saves is not an acceptance requirement for this calculation infrastructure.
|
||||
|
||||
Implementation acceptance runs the UXAssist and CheatEnabler Release builds, the relevant checks, and `git diff --check`. Use the repository's normal build form, `dotnet build <project>/<project>.csproj -c Release --no-restore`. If shared-constant changes affect additional dependent projects, build those projects as well.
|
||||
Reference in new issue
Block a user