BeltThrottle
Turn the vanilla Cargo Monitor into a real flow valve: a switch and a target-rate field are added to the panel, and the belt only passes the set items per minute. Stack aware. Switch off = vanilla behavior.
By LDG
| Date uploaded | 21 hours ago |
| Version | 1.2.2 |
| Download link | LDG-BeltThrottle-1.2.2.zip |
| Downloads | 7 |
| Dependency string | LDG-BeltThrottle-1.2.2 |
This mod requires the following mods to function
README
Belt Throttle —— 流速监控器限流阀 v1.2.2
作者: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 判定、触发报警或信号,从不限制通过量。这个插件在面板底部加一行 限速器:打开开关、填上每分钟想通过多少个,这条带子就按这个速率放行,多出来的货物堆在监控器上游。
一、用法
-
把流速监控器贴在传送带上(和平时一样)。
-
打开监控器面板,最下面多出一行:
限速器 [ 开关 ] 目标流速 [ 60 ] 个/分钟 放行 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\local.dsp.beltthrottle.settings.txt,一行一个监控器:
# planetId,entityId,enabled,rate,unit
750000001,382,1,60,0
存档本身完全干净。卸载插件后带子恢复原速,只是限速设置会丢失。
四、配置项
BepInEx\config\local.dsp.beltthrottle.cfg:
[throttle]
## 总开关,关掉后所有监控器都回原版
Enabled = true
## 按物品个数限流(自动除以平均堆叠数)
StackAware = true
## 排查问题时打开,会在日志里打印每个监控器的目标/满速/放行比例
VerboseLog = false
五、卡住了怎么查
启动日志里每个拦截点都会自检,正常应该是这样:
[BeltThrottle] patch check: CargoPath.Update prefix=1 postfix=0
- 如果出现
没有挂到补丁,限流不会生效,说明补丁被别的插件抢了,把日志发我; - 打开开关后应该出现一行
限流生效:监控器#12(entity 382) 目标 300 个/分 …; - 如果出现
有限速设置但没有接管任何传送带:设置=105#43353=300;当前工厂 planetId=…,说明监控器编号和当前工厂对不上,把这行发我; - 如果出现
指向的传送带编号无效/没有货运路径之类,说明监控器和带子的绑定关系和预期不一致,也请发我。
六、已知限制
- 限流的实现方式是「让整条传送带在部分 tick 停下」,所以低速率时看起来是走走停停(例如 30 个/分时约每 60 tick 挪一次)。平均流量准确,但视觉上不是匀速滑动。
- 同一条传送带上挂了多个监控器时,取最严格的那个生效。
- 监控器本身的「监测周期」不影响限速,限速只看你填的目标流速。
七、构建
build.bat :: 编译 → pkg → dist\BeltThrottle-1.2.1.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、不写自定义存档字段。