You are viewing a potentially older version of this package. View all versions.
LDG-BeltThrottle-1.3.0 icon

BeltThrottle

限流阀:给原版流速监控器加上限速开关和目标流速输入框,传送带只按设定的每分钟个数放行,支持堆叠物品,设置随蓝图继承,关闭开关即恢复原版。 / Turns the vanilla Cargo Monitor into a real flow valve: throttle switch + rate box, the belt passes only the set items per minute, stack aware, settings kept in blueprints.

By LDG
Date uploaded 18 hours ago
Version 1.3.0
Download link LDG-BeltThrottle-1.3.0.zip
Downloads 11
Dependency string LDG-BeltThrottle-1.3.0

This mod requires the following mods to function

xiaoye97-BepInEx-5.4.17 icon
xiaoye97-BepInEx

BepInEx5.4.17 mod plugin framework, Mod框架

Preferred version: 5.4.17

README

Belt Throttle —— 流速监控器限流阀 v1.3.0

作者:LDG · 适用:Dyson Sphere Program(BepInEx 5)· 无前置依赖(BepInEx 除外)


AI 使用声明 / AI Disclosure

本模组的 C# 代码在编写过程中使用了 AI 工具辅助(代码生成与问题排查),随后由作者在真实游戏环境中完成编译、加载、实测与验证。作者对本模组的全部内容与行为负责。

按 Thunderstore 的政策要求,本包已标注 AI Generated 类别。

The C# source of this mod was written with the help of an AI assistant (code generation and debugging), then compiled, loaded and tested in-game by the author, who takes full responsibility for the content. This package is tagged AI Generated as required by Thunderstore's policy.


English summary — Belt Throttle turns the vanilla Cargo Monitor into a real throughput valve. Open a monitor's panel, flip the Throttle switch on, type how many items per minute you want, and that belt will only pass that many; the rest backs up upstream. It is stack-aware (counts items, not cargo slots) and can also be set in items per second. Switch off = pure vanilla behavior. Nothing is written into the save file, so uninstalling this mod leaves your factory untouched. Requires BepInEx 5 only.


给原版 流速监控器(Cargo Monitor) 补上它本来就该有的能力:真的把流量卡住。

原版的流速监控器只是一块贴在传送带上的仪表,它显示的数值只用来做 Pass / Fail 判定、触发报警或信号,从不限制通过量。这个插件在面板底部加一行 限速器:打开开关、填上每分钟想通过多少个,这条带子就按这个速率放行,多出来的货物堆在监控器上游。

一、用法

  1. 把流速监控器贴在传送带上(和平时一样)。

  2. 打开监控器面板,最下面多出一行:

    限速器  [ 开关 ]    目标流速  [  60  ]  个/分钟        放行 3.3%
    
  3. 点开开关,在输入框里填每分钟通过的个数,回车或点面板别处即生效。

状态 效果
开关关闭(默认) 完全原版行为,插件不碰这条带子
开关打开 + 速率 60 每分钟只放行 60 个,其余堆在监控器上游
开关打开 + 速率 0 等同于不限流
速率 ≥ 带子满速 自动跳过,不限流

带子满速:一级 360 个/分、二级 720、三级 1800。

面板右侧的「放行 xx%」是本 tick 的放行比例,填完数就能立刻看出限流是否生效。

二、它是怎么工作的

旧的两次失败都是同一个原因:现代 DSP 的传送带模拟跑在工作线程上。

// GameLogic 的 tick 表
case 2200:
    if (单线程)  FactoryCargoPathGameTick();                 // → CargoPathsGameTickSync()
    else          FactoryCargoPathGameTick_Parallel(...);    // → _cargo_path_parallel() → path.Update()

并行版直接调用 CargoPath.Update(),根本不经过 CargoTraffic.CargoPathsGameTickSync。 之前把「本 tick 该拦哪条带」的计算挂在 CargoPathsGameTickSync 上,所以在多核机器上那段代码从来没执行过 (日志里只有 patch check 和开关记录,没有 限流生效,原因就在这里)。

现在改成:主线程只算一次快照,拦截判定放在 CargoPath.Update 里纯算术完成。

  • 主线程(插件 Update,每 15 帧或设置变动时)扫描所有工厂的监控器,生成「path → 放行比例」的只读快照;
  • CargoPath.Update 的 Prefix 只做一次字典查询,然后 floor(tick × ratio) > floor((tick-1) × ratio) 为真就放行,否则整条 path 本 tick 不推进;
  • 无状态、无锁,工作线程并发调用也安全;
  • 没有监控器开启限流时快照是空字典,Prefix 只多一次 Count == 0 判断,几乎没有开销。

长期平均流量精确等于设定值,误差不超过一个 tick。不丢货、不复制物品、不往存档写任何自定义数据。

关于堆叠物品

传送带上一个货物格子可能堆叠 N 个物品。默认 StackAware = true:插件会实时采样这条带子上的平均堆叠数,你填的是物品个数——填 120 就是每分钟 120 个物品,哪怕每格堆了 4 个。

想让数字和原版监控器显示的含义完全一致(按货物格子算),把 StackAware 改成 false。

三、设置存在哪

BepInEx\config\LDG.BeltThrottle.settings.txt,一行一个监控器:

# planetId,entityId,enabled,rate,unit
750000001,382,1,60,0

存档本身完全干净。卸载插件后带子恢复原速,只是限速设置会丢失。

从旧版(1.2.0 及更早)升级:新版第一次启动会自动读取旧的 local.dsp.beltthrottle.settings.txt,你改动任意一项设置后就写成新文件名,无需手工迁移。

四、蓝图与复制粘贴

打开限速的监控器复制成蓝图,再粘贴出来,限速设置会一起带过去,不需要手动重填。

原理:原版把流速监控器的设置存在建筑参数数组 BuildingParameters.parameters(int[128])里,蓝图复制粘贴会搬运这份数组。该数组的索引 15、16 在原版两个方向上都没用到(导出只写 0~14、17~21),本插件就用它们存「开关 + 目标流速」:

槽位 内容
parameters[15] 1 = 开启限速,0 = 未设置
parameters[16] 低 24 位:每分钟流量 × 100;高 8 位:单位(0 = 个/分钟,1 = 个/秒)

因为原版导入参数时根本不读这两个槽,所以即使以后卸载本插件,存档与蓝图里的残留值也只会被忽略,不会引发异常行为。

同样地,原版的 复制建筑设置 / 粘贴建筑设置(Shift + 右键)走的是同一条链路,一样会继承限速。

两点边界情况:

  • 旧蓝图(没有这两个槽)粘贴后不会带限速,也不会清除目标位置原有的限速设置;
  • 用「未开启限速」的蓝图覆盖一个已开限速的监控器时,旧设置会保留,需要手动关掉。

这样设计是有意为之:读档重建建筑时会走同一条参数应用链路,若在「无数据」时清除会误删玩家的设置。

五、配置项

BepInEx\config\LDG.BeltThrottle.cfg:

[throttle]
## 总开关,关掉后所有监控器都回原版
Enabled = true

## 按物品个数限流(自动除以平均堆叠数)
StackAware = true

## 排查问题时打开,会在日志里打印每个监控器的目标/满速/放行比例
VerboseLog = false

六、卡住了怎么查

启动日志里每个拦截点都会自检,正常应该是这样:

[BeltThrottle] patch check: CargoPath.Update prefix=1 postfix=0
[BeltThrottle] patch check: BuildingParameters.ToParamsArray prefix=0 postfix=1
[BeltThrottle] patch check: BuildingParameters.FromParamsArray prefix=0 postfix=1
[BeltThrottle] patch check: BuildingParameters.PasteToFactoryObject prefix=0 postfix=1
[BeltThrottle] patch check: BuildingParameters.ApplyPrebuildParametersToEntity prefix=0 postfix=1

后四行是蓝图携带设置用的。如果它们显示 没有挂到补丁,蓝图就不会带限速(限流本身仍然正常)。

  • 如果出现 没有挂到补丁,限流不会生效,说明补丁被别的插件抢了,把日志发我;
  • 打开开关后应该出现一行 限流生效:监控器#12(entity 382) 目标 300 个/分 …;
  • 如果出现 有限速设置但没有接管任何传送带:设置=105#43353=300;当前工厂 planetId=…,说明监控器编号和当前工厂对不上,把这行发我;
  • 如果出现 指向的传送带编号无效 / 没有货运路径 之类,说明监控器和带子的绑定关系和预期不一致,也请发我。

七、已知限制

  1. 限流的实现方式是「让整条传送带在部分 tick 停下」,所以低速率时看起来是走走停停(例如 30 个/分时约每 60 tick 挪一次)。平均流量准确,但视觉上不是匀速滑动。
  2. 同一条传送带上挂了多个监控器时,取最严格的那个生效。
  3. 监控器本身的「监测周期」不影响限速,限速只看你填的目标流速。

八、构建

build.bat    :: 编译 → pkg → dist\BeltThrottle-1.3.0.zip

CHANGELOG

Changelog

[1.3.2] - 2026-11-21

按 Thunderstore 版主要求做的 README 合规调整,代码与游戏内行为没有任何变化。

变更

  • 移除 README 末尾的「八、构建」小节(其中的 build.bat 打包命令属于开发流程说明,Thunderstore 全球规则要求包里不包含开发 / 测试相关内容);
  • 版本号递增到 1.3.2。

升级

直接覆盖安装即可,限速设置与蓝图不受影响。

[1.3.1] - 2026-11-20

纯文档与元数据更新,DLL 与 1.3.0 完全一致,游戏内行为没有任何变化。

变更

  • manifest.json 的简介(模组管理器列表里显示的那一行)改为中文在前、英文在后的双语写法,国内玩家一眼就能看懂用途;
  • 简介长度压到 243 字符,符合 Thunderstore 的 250 字符硬上限(上一版是 281 字符,已超出限制);
  • 1.3.0 的包已提交,Thunderstore 不允许同版本号重复上传,故以 1.3.1 重新发布。

升级

直接把新包覆盖安装即可,限速设置与蓝图不受影响。

[1.3.0] - 2026-11-20

新增:限速设置跟随蓝图

打开限速的监控器复制成蓝图后,粘贴出来的新监控器自动沿用蓝图里的限速开关与目标流速,不再需要手动重设。

实现方式:原版把流速监控器的设置存在 BuildingParameters.parameters(int[128])里,蓝图复制粘贴会搬运这份数组。其中索引 15、16 在原版两个方向上都未使用,本版将限速数据写入:

  • parameters[15]:1 = 开启限速,0 = 未设置;
  • parameters[16]:低 24 位为「每分钟流量 × 100」,高 8 位为单位(0 = 每分钟,1 = 每秒)。

涉及的五个补丁点:

  • CopyFromFactoryObject:复制时把当前监控器的限速写进参数槽位;
  • ToParamsArray:把 15/16 补进最终参数数组,真正进入 BlueprintBuilding.parameters;
  • FromParamsArray:粘贴时把 15/16 从蓝图参数读回;
  • PasteToFactoryObject:覆盖建造 / 粘贴建筑设置时应用;
  • ApplyPrebuildParametersToEntity:蓝图粘贴出的新建筑在 prebuild 建成时应用(这条是最容易被漏掉的一条)。

「无数据」时不清除既有设置——因为读档重建建筑也会走同一条参数链路,清除会误删玩家配置。

兼容性:原版导入参数时不读 15/16,卸载本插件后残留值被忽略;旧蓝图没有这两个槽,粘贴后视为未开启限速。原版「复制 / 粘贴建筑设置」(Shift + 右键)同样会继承限速设置。

[1.2.2] - 2026-11-20

合规重发版,游戏内功能与 1.2.1 完全一致,DLL 未做任何逻辑改动。

变更

  • README 顶部补充 AI 使用声明(中英双语),配合 Thunderstore 的 AI 内容披露要求;
  • 包在 Thunderstore 页面标注 AI Generated 类别;
  • 版本号递增到 1.2.2。1.2.1 因缺少 AI 披露被审核拒绝且包内容不可变,只能以新版本提交。

升级

无需任何操作,存档与限速设置完全兼容。

[1.2.1] - 2026-11-19

首个公开发布版,限流逻辑与 1.2.0 完全一致(1.2.0 已实测通过)。

变更

  • 作者改为 LDG,插件 GUID 由 local.dsp.beltthrottle 改为 LDG.BeltThrottle;
  • 配置文件随之变为 BepInEx\config\LDG.BeltThrottle.cfg;
  • 限速设置文件迁移到 LDG.BeltThrottle.settings.txt。首次启动会自动读取旧的 local.dsp.beltthrottle.settings.txt,已有的限速配置不会丢,改动任意一项后自动写成新文件;
  • manifest.json 补齐 Thunderstore 依赖 xiaoye97-BepInEx-5.4.17。

升级注意

GUID 变了,旧版(local.dsp.beltthrottle)和新版会被 r2modman / BepInEx 当成两个插件。 请先在 r2modman 里卸载旧的 BeltThrottle,再安装本版,避免两个 DLL 同时加载。

[1.2.0] - 2026-11-19

修正(1.1.1 仍然无效的真正根因)

  • 传送带不是在主线程逐条推进的。GameLogic 的 tick 表里: case 2200: if (单线程) FactoryCargoPathGameTick() else FactoryCargoPathGameTick_Parallel()。 并行版 _cargo_path_parallel 直接调用 cargoPath.Update(),完全绕开 CargoTraffic.CargoPathsGameTickSync。 1.1.x 把「本 tick 该拦哪条带」的计算挂在 CargoPathsGameTickSync 的 Prefix 上,在你的机器上这个方法从来没被调用过, 所以补丁挂上了也一条日志都没有。
  • 新实现不再依赖任何每 tick 的主线程回调:主线程(插件 Update)只负责重建「path → 放行比例」的只读快照, 拦截判定放在 CargoPath.Update 的 Prefix 里,用 floor(tick×ratio) > floor((tick-1)×ratio) 纯算术判断, 无状态、无锁、工作线程安全。
  • 快照通过 volatile 引用整体替换发布;没有监控器开启限流时是空字典,Prefix 只多一次 Count == 0 判断, 基本没有性能开销(也顺手去掉了 1.1.x 每 tick 全量扫 monitorPool 的开销)。
  • 新增诊断:有限速设置却没接管任何传送带时,日志会打出「设置里的 planetId#entityId」和「当前工厂的 planetId」, 一眼能看出是不是编号对不上。
  • UI 里改开关或改流速后会立刻重建快照,不用等下一次轮询。

[1.1.1] - 2026-11-19

修正(1.1.0 面板正常但限流无效)

  • 拦截记录被写坏的根因:GameLogic 每个 tick 会对所有已创建的工厂各调一次 CargoTraffic.CargoPathsGameTickSync。原实现在每次调用开头 Blocked.Clear(),于是后一个工厂把前一个工厂刚标记的传送带全部清空,限流从没生效过。现在改为「按 path 引用打 gameTick 时间戳、过期自然失效」,不再有任何全局清空。
  • 补丁改成逐个类显式挂载(CreateClassProcessor),并在启动日志里用 Harmony.GetPatchInfo 校验 CargoPath.Update、CargoPathsGameTickSync 是否真的挂上,挂不上会直接报 Error。
  • 启动/停止限流时会打一行日志(限流生效 / 恢复满速),VerboseLog=true 时每 64 tick 输出诊断行(放行比例、path 长度、本 tick 拦截数、累计拦截 Update 次数)。

[1.1.0] - 2026-11-19

重做(1.0.x 实测无效)

  • 限流方式整个换掉。原来去改传送带 chunk 的「每 tick 前进格数」,但 chunk 数据会被游戏在拼带、升级、读档时重建,写进去的值随时失效,实测完全没有效果。现在改为直接拦截 CargoPath.Update:需要限流的传送带本 tick 不推进,货物停在原地。
  • 面板底部新增「限速器」开关 + 目标流速输入框,不再借用原版那个隐形的「目标流量」框。开关关闭 = 100% 原版流速监控器。
  • 速率用时间占空比控制:目标 N 个/分 → 每 tick 放行比例 = N / 满速,累加器攒够 1 放行一 tick,长期平均精确等于设定值。
  • 支持堆叠物品:默认按「物品个数」限流,自动除以带上的平均堆叠数(StackAware)。
  • 面板右侧实时显示「放行 xx%」,填完数立刻能看出是否生效。
  • 限速设置独立存放在 BepInEx\config\local.dsp.beltthrottle.settings.txt,存档保持干净。
  • 去掉 RequirePower / RestoreBeltSpeedOnSave(新方案不改带速,没有这两类问题)。

[1.0.1] - 2026-11-19

修正

  • 「目标流量」那个数字就是输入框,但原版没有可见边框,几乎所有人都以为它只是一行说明文字。现在面板打开时会给这个数字加青色描边、必要时补一层淡背景,一眼能看出「这里能填数」。
  • README 补上「怎么填」「监测周期会改变填写含义」的说明。

[1.0.0] - 2026-11-19

首个版本。

新增

  • 流速监控器限流:把监控器的「流速」数值变成真实的限流值。目标 N 个/分钟时,监控器所贴的传送带段每分钟只放行 N 个,多余货物堆积在监控器上游,流出段稳定按设定值输出。
  • 流速为 0 时自动不限流;拆监控器 / 断电 / 提高目标到满速以上,都会自动恢复原版带速。
  • 每 tick 先恢复再重算,不会留下卡死的传送带。
  • 存档写入前把带速恢复原版(RestoreBeltSpeedOnSave),存档保持干净、卸载插件后旧存档也不会异常。
  • 配置项:Enabled、RequirePower、VerboseLog、RestoreBeltSpeedOnSave。

说明

  • 限流作用在监控器所在的那一段传送带(chunk)。不限流时与原版完全一致。
  • 只改 CargoTraffic 的 tick 与存档入口,不新增物品、不改 prefab、不写自定义存档字段。