集成能源管理系统 (IEMS)
⚠️ 国际玩家重要通知:
IEMS 目前仅作为框架存在。它本身不包含任何功能性的核心方块、发电机或能量存储设备。
官方核心提供模组(Core Provider Mod)目前正在进行中国区测试,即将在 Modrinth 发布。
专为大型整合包设计的能源管理框架模组:统一的能量抽象、高精度 BigInteger 运算、激光拓扑可视化以及网页监控面板。设备和核心由外部模组接入;IEMS 的职责是将它们编织成单一的统一电网。
开发团队: 等离子工作室 (DLZstudio)
模组 ID: iems
开发代号: IEMS0930
许可证: MIT License
? 目录
简介
IEMS 0.8.0-beta 是对旧版 IEMS 的完全重写(实现了逻辑层与表现层的彻底分离):
- 能源管理框架 — 本模组不附带电力生成/存储核心;核心和设备通过 API 由外部模组接入(官方参考实现:IEMS-TestDevices)
- 统一能量抽象 — FE / AE 等单位统一转换为 SE(标准能量),采用 BigInteger 高精度运算,超大数值无精度损失
- 激光连接可视化 — 设备间的激光束实时显示电网拓扑:通电黄色 / 断电红色 / 桥接青色(可配置)
- 手动拉线 + 自动组网 — Shift + 右键拖拽拉线建立连接(HUD 显示实时距离),在广播塔范围内自动扫描并连接设备,自动桥接外部 FE 设备
- 协议容量管理 — 基于设备数量的电网负载限制,超限时自动停机保护
- 网页监控面板 — 在浏览器中实时查看电网状态、设备、拓扑及历史指标(使用 JDK 内置 HttpServer,零第三方依赖)
- 模拟风格持久化 — 电网数据存储在
iems_grid.dat 中,重启后从设备工厂重建;即使区块未加载也保持运行
- 开放 API — 稳定的
IEMSAPI 静态外观类 + IIemsInteractable 拉线契约,供外部模组接入
⚠️ 重要提示: 本模组是一个框架,不提供核心方块!你需要安装一个提供核心的模组(官方测试模组 IEMS-TestDevices,或通过 API 自行接入)来形成完整的电网。
方块
核心方块
? 由其他模组通过 CoreDevice 提供(例如来自 IEMS-TestDevices 的测试核心)
- 电网的身份锚点,能量池的主进/出接口,以及协议容量管理器
- 注册所在的区块会自动设置为强制加载(注销时释放)
- 唯一实例;是电网 BFS 可达性检查的起点
能量传输中继器
- 远距离信号中继和电力传输;一种手动拉线设备(不参与自动扫描)
- 连接距离:500 格
- 激光锚点:方块中心 (0.5, 10.75, 0.5)(塔顶)
- 激光颜色:黄色(通电)/ 红色(断电)
- 占用的协议容量:1
能量广播塔
- 短距离无线传输,具备自动 + 手动双模式
- 连接距离:50 格
- 信号源位置:塔顶 (0.5, 8.0, 0.5)
- 放置后,自动扫描并连接范围内的设备(包括中继器和广播塔)
- 必须直接或间接连接到核心才能实际供电(孤立连接会以红色激光渲染)
- 占用的协议容量:1
- 自带等级 7 的光照,黑暗中可见
外部 FE 设备(自动桥接)
- IEMS 自动发现范围内的任何 NeoForge FE 设备(来自其他科技模组的发电机/消耗者/储能设备)
- 每 20 tick(1 秒)重新扫描,发现时自动创建桥接连接(青色激光,可配置为普通颜色)
- 另一个模组无需任何适配
┌────────────────────────────────────────────┐
│ Core (由其他模组提供) │
│ 能量池 · 协议上限 · BFS 根节点 │
│ │ │
│ ┌─────────────┼─────────────┐ │
│ ↓ ↓ ↓ │
│ ┌────────┐ ┌────────┐ ┌──────────┐ │
│ │ Relay │───│ Tower │───│FE 设备 │ │
│ │500 格 │ │ 50 格 │ │ 自动桥接 │ │
│ └────────┘ └────────┘ └──────────┘ │
└────────────────────────────────────────────┘
3. 网络工作流程
- 安装一个提供 Core 的模组并放置 Core
- 放置 Relay / Broadcast Tower(或直接使用现有的 FE 设备)
- 瞄准一个设备并按住 Shift + 右键 进入拉线模式(HUD 会显示实时距离)
- 瞄准目标设备并按住 Shift + 右键 完成连接
- 处于 Broadcast Tower 范围内的设备会自动组网;FE 设备会自动进行桥接
- 在浏览器中打开
http://127.0.0.1:28567/ 以监控电网
设备供电状态
- 连接到 Core 的设备(直接或间接通过 Relay/Broadcast Tower)将自动获得供电
- 当电网关闭时(协议容量超限或手动关闭),所有设备失去电力,激光变为红色
- 两端已注册但未连接到 Core 的连接(孤岛连接)将渲染为红色激光
连接系统
手动拉线模式
如何进入:
- 瞄准实现了拉线契约的设备并按住 Shift + 右键
拉线过程中:
- HUD 显示实时拉线距离和最大距离
- 超出最大距离(+10 格缓冲)后,线缆会自动收回并弹出通知
- 维度变化(穿过传送门 / 跨维度TP)会立即收回线缆 —— 新维度中的旧坐标毫无意义
- 离开世界会自动清除拉线状态
完成连接:
- 瞄准目标设备并按住 Shift + 右键 再次点击
- 客户端发送连接请求,服务器会重新验证它(合法的端点、同一维度、距离、重复项、Relay 规则),然后创建连接
- 点击起始点本身或非设备方块 → 取消拉线
有效连接规则
| 连接类型 |
有效 |
条件 |
| Core → Relay |
✅ |
在距离内,Core 强制加载 |
| Core → Broadcast Tower |
✅ |
在距离内 |
| Relay → Relay |
✅ |
500 格以内 |
| Relay → Broadcast Tower |
✅ |
使用两端较小的距离限制 |
| Broadcast Tower → Broadcast Tower |
✅ |
50 格以内,自动或手动 |
| Broadcast Tower → FE 设备 |
✅ |
自动桥接 (ADAPTER_BRIDGE) |
| 跨维度连接 |
❌ |
被客户端和服务器拒绝(除了维度桥接) |
| 未连接到 Core 的孤岛间互连 |
⚠️ |
允许创建,渲染为红色激光,不供电 |
连接距离限制
⚠️ 距离限制是两端设备声明的距离中较小者。如果未声明任何内容,则使用框架默认的 500 格。
| 设备组合 |
最大距离 |
| Relay ↔ Relay |
500 格 |
| Broadcast Tower ↔ Broadcast Tower |
50 格 |
| Broadcast Tower ↔ Relay |
50 格 |
| Bridge (FE 设备 ↔ 设备) |
遵循锚定设备 |
激光显示
| 状态 |
颜色 |
描述 |
| 供电连接 |
黄色 |
带有能量流动动画 |
| 未供电 / 孤岛连接 |
红色 |
电网关闭或未连接到 Core |
| FE 桥接 |
青色(默认) |
当 colorizeAutoConnect = true 时,与普通连接区分开 |
| FE 桥接 |
黄色/红色 |
当 colorizeAutoConnect = false 时,颜色与普通连接相同 |
渲染特性:
- 光束宽度会根据距离进行屏幕空间最小宽度补偿(远距离时不会细到看不见)
- 双面渲染,从任何视角可见
- 跨维度孤岛连接不渲染(无法计算方向向量)
- 只要任一端点在渲染距离内即绘制(长连接不会被视锥体整体剔除)
协议容量系统
什么是协议容量?
协议容量是电网所能支持的设备连接数量的上限。
| 设备 |
占用的容量 |
| Relay |
1 |
| Broadcast Tower |
1 |
| 外部连接设备 |
由设备声明 |
| Core |
0(不使用) |
限制: 在注册时由 Core 声明 (protocolLimit),可在运行时调整。
超限保护
当使用容量超过总容量时:
- 电网自动关闭
- 所有设备失去电力,激光变为红色
/iems status 显示关闭原因
如何恢复:
- 移除部分设备(扫描后会自动触发恢复)
- 或者让 Core 模组在运行时提高容量上限
Web 监控面板
如何访问
- 启动游戏并加载世界(面板随服务器启动/停止)
- 在浏览器中访问:
http://127.0.0.1:28567/
- 首次启动时自动生成随机令牌(写入配置文件)
身份验证
- 所有
/api/* 端点都需要令牌:请求头 X-IEMS-Token: <token> 或查询参数 ?token=<token>
/health 和 /(主页)不需要身份验证
- 令牌位于
config/DLZstudio/IEMS/APIserve.toml
配置文件
# config/DLZstudio/IEMS/APIserve.toml
[APIserve]
enabled = true # 是否启用 Web 面板
host = "127.0.0.1" # 绑定地址;如需远程访问请改为 "0.0.0.0"(同时务必修改 token 并配置 TLS 反向代理)
port = 28567 # 监听端口
token = "a1B2c3D4..." # API 令牌(首次启动时随机生成)
端点概览
| 方法 |
路径 |
描述 |
| GET |
/health |
存活探针(无信封包装) |
| GET |
/api/status |
电网概览(核心位置/能量/容量/协议/停机状态) |
| GET |
/api/devices |
设备列表(包含核心、各设备的属性) |
| GET |
/api/connections |
连接列表(可达的主网 + 边界连接) |
| GET |
/api/topology |
拓扑快照(聚合的主网/孤岛/边界视图) |
| GET |
/api/metrics |
时间序列指标(环形缓冲区,采样得到的能量/容量/协议/设备数量) |
| POST |
/api/grid/active |
手动启用/禁用电网(映射至 IEMSAPI.setGridActive) |
数据信封
{
"schema": 1,
"ts": 1727073600000,
"data": { }
}
- BigInteger 字段如 energy/capacity/rates 以十进制字符串形式传输(以避免精度丢失)
- 维度使用资源键字符串(例如
"minecraft:overworld")
- 若无核心,energy 返回
"0" 且 corePos 为 null
curl 示例
# 只读端点
curl -H "X-IEMS-Token: <token>" http://127.0.0.1:28567/api/status
# 写入端点(关闭电网)
curl -X POST -H "X-IEMS-Token: <token>" \
-H "Content-Type: application/json" \
-d '{"active": false}' \
http://127.0.0.1:28567/api/grid/active
? 在 Windows PowerShell 中,内联 JSON 的引号会因参数传递而被破坏;请将请求体写入文件,并使用 --data-binary @body.json 提交。
能量交换率配置
SE(电网内部标准单位)与 FE 之间的交换率决定了“多大的能量缺口值得调用 FE 级设备”,可根据你整合包中的能量规模进行调整。
config/DLZstudio/IEMS/Energy.toml:
# IEMS 能量交换率配置
[energy]
# 1 SE 转换为多少 FE(即 SE:FE = 1:N)。
# 默认值为 10;范围 [1, 900000000000000000000000000](上限是旧版的固定值,因此可一键恢复旧版行为)。
# 编辑后在游戏内运行 /iems reload 即可立即生效(无需重启游戏或离开世界)。
# 注意:此更改会重新解释电网中现有的 SE 数值(重新定义了 1 SE 对应的 FE 量),请谨慎调整。
fePerSe = 10
- 默认值:1 SE = 10 FE:匹配主流 FE 设备的规模,使得通过 FE 桥接的设备能正常参与电网吞吐量
- 下限 1(1 SE = 1 FE),上限 9×10²⁶(旧版硬编码默认值;将其设为该值可恢复旧版行为)
- 超出范围的数值会自动钳制到边界,非数值型值则回退到默认值
- 手动重载:编辑文件后,在游戏内运行
/iems reload(权限等级 2)即可立即生效——无需重启游戏,也无需离开世界
- 如果在编辑时删除了整个键,将保留当前生效的值而非回退到默认值(部分编辑不会导致意外损坏)
/iems reload
一条命令重载所有 IEMS 配置文件(手动触发,无自动轮询):
| 配置文件 |
重载效果 |
Energy.toml |
重新解析交换率并将其注入转换器,立即生效 |
APIserve.toml |
重建 Web 面板,应用 enabled / host / port / token |
Renderer.toml |
使客户端渲染配置缓存失效(在本地客户端下次读取时生效;专用服务器上的远程客户端需要重新进入世界) |
/iems reload 需要权限等级 2(与 /iems shutdown 和 /iems restart 相同)。
⚠️ 交换率是 SE 相对于 FE 的定义;更改它会立即重新解释电网中所有现有的 SE 数值(核心能量存储、设备容量等)。设备间的 SE 比率保持不变,结算依然保守,但外部展示的 FE 等价量整体缩放——请根据你整合包的能量规模设定一次,并避免频繁调整。
⚠️ 当交换率设置较高时,FE 级设备的实际速率可能转换为小于 1 SE/tick;桥接层已根据其“单 tick 交付量”自适应声明粒度,因此无论速率高低,吞吐量绝不会降至 fePerSe FE/tick。
渲染配置
config/DLZstudio/IEMS/Renderer.toml:
# IEMS 渲染配置
[renderer]
colorizeAutoConnect = true # true:自动桥接连接使用青色;false:与普通连接颜色相同(黄色/红色)
- 零 IO 懒加载缓存:配置按需读取并缓存,离开世界时自动失效
- 更改配置后,重新进入世界即可应用,无需重启游戏
持久化存储
电网数据保存
存储位置:
world save/data/iems_grid.dat
持久化内容:
- 设备列表(按工厂 ID 索引,包含位置/类型/参数)
- 核心信息
- 所有连接(包括孤岛连接和桥接连接)
模拟风格重建 (M9)
- 设备以工厂 ID + 参数的形式持久化,而非依赖 BlockEntity(方块实体)保持存活
- 服务器启动时,遍历
iems_grid.dat:重建工厂 → restoreState(恢复状态)→ 网格恢复
- 即使设备所在的区块未加载,网格仍会继续模拟(BlockEntity 仅用于外观/视图显示)
- 核心所在的区块在注册时会自动强制加载
自动保存点
数据安全
- 破坏设备会自动注销它并清理其连接
- 区块卸载不再注销设备(修复于 BUILD.00000110:
setRemoved 错误地注销了核心,导致重启后连接丢失)
- 保存并重启后,连接完全保留
高级玩法
网络技巧
- 高度优势: 将广播塔建在高处以扩展有效覆盖范围
- 中继骨干网: 使用中继器(500 格)进行长距离骨干链接,使用广播塔(50 格)进行端点覆盖
- FE 设备复用: 现有的科技模组设备会被自动桥接,无需拆卸或修改任何东西
- 岛屿预布线: 尚未连接到核心的设备可以先互连(红色激光表示无电力),一旦放置核心,整个网络即可通电
- 核心选址: 核心所在的区块会被强制加载,因此请将其放置在主基地的中心,以缩短骨干网距离
能源管理策略
- 峰谷平衡: 依靠储能设备在用电高峰期放电
- 容量规划: 保持 20% 的协议容量余量;超出限制会导致整个网格关闭
- 监控与警报:
/api/metrics 提供时间序列样本,可接入外部仪表盘
- 分区供电: 为重要设备分配独立的核心/子网
技术细节
架构:逻辑与表现完全分离
外部模组(设备提供方)
│
└── 方块 / 方块实体(向 Minecraft 注册,仅用于外观/视图)
│
├── 在构造函数/loadAdditional() 中实例化逻辑实例(纯 POJO,不需要 Level)
├── 在 onLoad() 中通过 IEMSAPI.attachOrRegisterDevice() 进行挂钩(仅限服务端)
└── 在 saveAdditional() 中持久化参数
│
▼
┌─────────────────────────────────────────────┐
│ IEMS 逻辑层 (com.iems) │
│ │
│ CoreDevice(唯一实例,强制加载) │
│ DeviceRegistry 设备池(N 个实例) │
│ │
│ GridTopology(BFS/拓扑快照) │
│ EnergyDispatcher(每刻能量分配 + 帧切片调度)│
│ ProtocolCalculator(容量计算/超限检测) │
│ FEDA(FE 设备发现与桥接适配) │
└─────────────────────────────────────────────┘
设计理念:实例自治 —— 每个设备实例完全独立,不持有对其他实例的引用,仅通过调度器与网格交互;支持独立的创建/销毁/参数更改,天然支持多核并行。
模块分解
| 包 |
职责 |
com.iems.api |
公共门面 (IEMSAPI / IIemsInteractable / SubSeAccumulator) |
com.iems.core |
网格内核(网格 / 节点 / 调度 / 协议) |
com.iems.eds |
设备发现系统 EDS(扫描器 + 身份轴,仅发现,不桥接) |
com.iems.adapter |
适配层(DA:FEDA 伪装外部 FE 设备为节点并将其接入网格) |
com.iems.network |
C2S/S2C 载荷(连接请求、全量同步、关闭同步) |
com.iems.webpanel |
Web 面板(JDK HttpServer,端口 28567) |
com.iems.example |
示例设备(中继器/广播塔,仅依赖 api 门面) |
线程模型
- 所有网格状态由服务器 Tick 线程独占拥有
- 外部线程(Web 面板 HTTP 线程等)通过
IEMSAPI.runOnServerThread() / callOnServerThread() 提交任务,消除数据竞争
- Web 面板线程池在世界重载时手动停止,以防止线程泄漏
网络同步
GridSyncPayload —— 全量拓扑同步(三个列表分别对应主网格/孤岛/桥梁,带有大小验证以防止 OOM)
ConnectionRequestPayload —— C2S 拉线连接请求(服务端重新验证 + 距离检查 + 速率限制)
- 关闭状态/协议容量随快照同步;HUD 显示三种状态
激光渲染细节
- 广告牌宽度方向:宽度 = 光束方向 × (相机→光束),因此侧面视角不会消失
- 屏幕空间最小宽度:
max(0.03, distance × 0.0015),因此远处光束不会变细并消失
- 退化三角形分隔相邻条带,消除“幽灵对角线”
- 客户端缓存 (
ClientGridCache) 处理三个列表(主网格 + 孤岛 + 桥梁),包含象限统计和 EMA 平滑处理
设备发现系统
设备发现系统 (EDS) 旨在回答一个问题:哪些附近的能量设备属于哪个能量系统?
其边界非常清晰——它只负责发现和分类;不进行注册、创建连接或转换。所有桥接决策都留给下游 适配层。
扫描入口点
IEMSAPI.EDS.scan(level, center, radius) // 同步一次性扫描(服务器主线程)
IEMSAPI.EDS.addListener(listener) // 注册一个消费者(可注销)
IEMSAPI.EDS.registerFlavor(flavor) // 声明你自己的能量系统
- 半径以方块为单位,限制在 [1, 128] 范围内(
EDSScanner.MAX_RADIUS = 128)
- 全局入口点:
IEMSAPI.EDS 是一个静态外观类(相当于全局函数);扫描器的监听器表和身份表也是静态的
- 仅枚举已加载的区块,然后裁剪为球形范围
- 已注册的 IEMS 设备(包括核心)将被跳过,并在报告的
skippedIemsDevices 中计数
- 同步执行,无异步,无速率限制 — 调用频率由调用者决定(内置适配器每 20 刻执行一次)
单设备探测
每个方块实体通过获取7 个方向上下文的并集并读取 NeoForge IEnergyStorage 能力来进行探测:
| 读取项 |
用途 |
canExtract |
分类为生产者 |
canReceive |
分类为消费者 |
stored / capacity |
存储量和容量快照 |
| 暴露面 |
记录可以从哪一侧抽取能量(exposedSides;null 表示无方向上下文) |
身份轴:EnergyFlavor
设备的能源系统根据其方块 ID 的命名空间解析:
| 字段 |
含义 |
namespace |
模组的命名空间(例如 appliedenergistics2) |
unit |
该系统的能量单位(决定桥接时的转换基准) |
displayName |
身份的显示名称(例如 Applied Energistics) |
- 外部模组通过
IEMSAPI.EDS.registerFlavor 声明自己的系统
- 未注册的命名空间默认被视为 FE,并使用其命名空间本身作为显示名称
发现报告:EDSReport
一次扫描产生一个不可变的报告(EDS, v1),并推送给所有监听器:
| 字段 |
描述 |
origin / radius / scanTick |
扫描原点、受限半径、扫描时刻(level.getGameTime()) |
devices |
发现的设备列表(EDSDevice,顺序稳定) |
chunksScanned |
实际枚举的已加载区块数量 |
blockEntitiesProbed |
被探测的方块实体总数(包括那些没有匹配能力的) |
skippedIemsDevices |
跳过的已注册 IEMS 设备数量(包括核心) |
便捷子集方法:producers() / consumers() / storage() / byNamespace(ns)。
消费者契约:IEDSListener
void onDiscovery(EDSReport report);
- 回调在服务器主线程上运行
- 心智模型:发现层只说明“这是一个 FE 设备,那是一个 AE 设备”;是否、与谁以及如何桥接完全取决于监听器
- 注册同一个监听器两次意味着它将收到每份报告的两个副本
⚠️ EDSReport 是扫描时刻的快照,而非实时状态。不要依赖它来判断现有设备是否存活 — 发现层将已注册的位置分类为 skippedIems 并跳过它们,因此重新扫描必然看不到它们(正确的方法请参阅适配器层中的 sync)。
适配器层
适配器层(记作 DA;当指代所有 DA 的集合时也称为 EDA)是一个可插拔的执行层:它将发现层找到的外部设备以伪装成 IEMS 节点的方式注册到网格中,并在每刻执行双向 SE ↔ 目标单位的读写转换。
每种能源系统有一个 DA 实现,命名为“系统名称 + DA” — 此版本中唯一的实现是 FEDA(FE 系统的 DA);AE / EU 及其他系统是未来的扩展点。
为什么需要适配器层
调度器仅识别节点接口,并且不区分“原生 SE 设备”和“适配器伪装的节点”:
IEnergyProducer / IEnergyConsumer / StorageDevice
DA 仅仅是一个将 SE 指令翻译为外部协议的执行器 — 添加新的能源系统只需添加一个 DeviceAdapter 实现,无需更改内核。
DeviceAdapter 接口
每个适配器都绑定到一个自动连接的 TransferDevice(例如能量广播塔):
| 方法 |
调用时机 |
职责 |
unit() |
— |
它适配到的能源系统单位(FE / AE…) |
scan(level, center, radius) |
定期 |
请求发现层扫描并返回此适配器关心的设备列表 |
sync(level) |
每 20 刻 |
将报告与已注册节点进行差异比较:注册新节点,注销消失的节点 |
tick(level) |
每刻 |
对其节点的外部能力执行实际的读写操作(提取 / 测量剩余接收容量 / 交付) |
detach() |
主机失效时 |
注销其所有节点 |
⚠️ sync 通过直接探测现有设备的方块能力来决定存在性,而不依赖扫描报告 — 因为发现层将已注册的位置分类为 skippedIems 并跳过它们;如果仅咨询报告,重新扫描会将现有设备误判为消失的设备。
调度器:FeBridgeTicker
| 周期 |
动作 |
| 每刻 |
迭代自动连接的继电器 → DeviceAdapter.tick;同时清理孤立节点 |
| 每 20 刻 |
DeviceAdapter.sync 重新扫描(差异同步) |
主循环内的顺序(IEMSEvents):FeBridgeTicker.tick / tickRescan → EnergyDispatcher.dispatchAtTick,即先同步外部设备,然后执行本刻的能量分配。
伪装节点与孤立清理
由适配器注册到网格中的节点均实现了标记接口 IAdapterNode:
owner() — 所有权链:主机中继 → 每台设备的伪装节点
isOrphaned() — 主机是否已被注销(注册表中的位置不再是原始实例)
两个用途:
- 自动连接排除 —
IemsAutoConnector 跳过对伪装节点的 RELAY_TO_DEVICE 自动连接;其访问仅通过 ADAPTER_BRIDGE 进行,避免双重连接冲突
- 孤儿清理 — 主机中继注销后,伪装节点将成为无连接的孤儿,
FeBridgeTicker 会在每个刻(tick)检测并注销它们
内置实现:FEDA
FEDA 是本版本中唯一的 DeviceAdapter 实现;它绑定到自动连接中继(广播塔),并通过分类外部设备能力来注册:
| 外部能力 |
伪装节点类型 |
场景 |
| 可提取 |
FeProducerAdapter |
外部发电机 → 向电网输入电力 |
| 可接收 |
FeConsumerAdapter |
外部消费者 → 从电网抽取电力 |
| 有容量 |
FeBufferAdapter |
外部存储 → 双向吞吐量 |
- 通过
silentRegister 将外部设备注册为独立的伪装节点
- 通过
IEMSAPI.addConnection(..., ConnectionType.ADAPTER_BRIDGE) 建立桥接连接(渲染为青色激光;可通过 colorizeAutoConnect 禁用着色)
- 当主机失效(中继损坏/注销)时,调用
detach() 并清理其节点
转换缓冲:FeConversionBuffer
维护每个设备的提取侧和推送侧 FE ↔ SE 缓冲区;它是 DA 层能量转换的核心状态机:
- 根据外部接收余量和
maxFePerTick 计算 SE 需求声明
- 电网分配的 SE 按当前
fePerSe 转换为 FE 进入推送池,然后交付给外部设备
- 需求声明的粒度随汇率自适应:当一 tick 内交付的量小于 1 SE 时,声明向上取整,因此提高汇率不会阻碍吞吐量(详见 能量交换速率配置)
开发者 API
快速开始
IEMS 作为 Jar-in-Jar / libs 依赖集成到外部模组中:
Gradle 依赖 (Groovy DSL):
dependencies {
// 将 IEMS 构建产物复制到 libs/ 后:
implementation files('libs/IEMS-0.8.0-beta-BUILD.00000120.jar')
}
neoforge.mods.toml 依赖声明:
[[dependencies.yourmod]]
modId="iems"
type="required"
versionRange="[0.8.0-beta,)" # ⚠️ -beta 后缀是必须的;"[0.8.0,)" 比较结果为不满足,并在加载时崩溃
ordering="AFTER"
side="BOTH"
设备集成:三个逻辑基类
外部模组的 BlockEntity 持有一个逻辑实例(纯 POJO):
// 1. 在模组加载期间注册工厂(M9 持久化重建的关键)
IEMSAPI.registerDeviceFactory("mymod:my_device", MyDevice::new);
// 2. 在 BlockEntity.onLoad() 中挂钩(仅限服务端)
GlobalPos pos = new GlobalPos(level.dimension(), blockPos);
MyDevice device = new MyDevice("My Device");
IEMSAPI.attachOrRegisterDevice(pos, device, "mymod:my_device");
// 具有 factoryId 的设备会持久化到 iems_grid.dat,并在重启后由工厂重建,即使未加载区块
// 3. 在 BlockEntity.setRemoved() 中注销
IEMSAPI.unregisterDevice(pos);
核心集成:
CoreDevice core = new CoreDevice("My Core",
BigInteger.valueOf(1000), // protocolLimit 协议容量限制
BigInteger.valueOf(100000), // energyCapacity 总能量容量 (SE)
BigInteger.ZERO); // powerGenRate 每 tick 自生能量
IEMSAPI.attachOrRegisterCore(pos, core, "mymod:my_core");
// 注册时会自动强制加载其所在区块;注销时释放
拉线契约:IIemsInteractable
BlockEntity 只需实现此接口,即可参与框架内置的 Shift+右键拉线交互:
public class MyDeviceBlockEntity extends BlockEntity implements IIemsInteractable {
@Override
public boolean canBeConnectionEndpoint() {
return true;
}
@Override
public int getMaxConnectionDistance() {
return 500; // 未声明时的框架默认值 500 格
}
}
- 纯粹的客户端发现机制(
instanceof 检测);服务端不依赖此接口做出安全决策
- 拉线 HUD、超距回撤和维度变更回撤均由框架处理
- 服务端连接创建通过
ConnectionRequestPayload 重新验证(端点/同维度/距离/重复项/中继规则)
IEMSAPI 静态外观(方法概览)
| 类别 |
方法 |
描述 |
| 线程安全 |
runOnServerThread(Runnable) |
从外部线程异步提交任务 |
| 线程安全 |
callOnServerThread(Supplier, timeoutMs) |
从外部线程同步等待结果 |
| 工厂 |
registerDeviceFactory(id, factory) |
注册设备工厂(M9 重构) |
| 设备 |
attachOrRegisterDevice(pos, node, factoryId) |
连接设备(若拥有工厂则持久化存储) |
| 设备 |
unregisterDevice(pos) |
注销设备 |
| 核心 |
attachOrRegisterCore(pos, core, factoryId) |
连接核心(区块强制加载) |
| 核心 |
unregisterCore(pos) |
注销核心 |
| 查询 |
getCurrentEnergy() / getTotalCapacity() |
能量池(BigInteger) |
| 查询 |
getProtocolUsed() / getProtocolTotal() |
协议容量 |
| 查询 |
getSnapshot() |
拓扑快照(主电网/孤岛/边界) |
| 查询 |
isDeviceConnected(pos) |
设备是否连接到主电网 |
| 连接 |
addConnection(a, b, type) / removeConnection(...) |
连接管理 |
| 控制 |
setGridActive(boolean) / forceRescan() |
电网开/关 / 强制重扫 |
| 电源 |
registerPowerInput(id, rate) / unregisterPowerInput(id) |
电源注册 |
| EDS |
EDS.scan(level, center, radius) |
附近设备扫描(半径限制在 [1,128] 内) |
| EDS |
EDS.addListener(l) / EDS.removeListener(l) |
注册/注销发现监听器 |
| EDS |
EDS.registerFlavor(flavor) |
注册能源系统身份(命名空间 → 单位/显示名称) |
有关发现和适配层(扫描边界、报告结构、DeviceAdapter 生命周期、伪装节点和孤儿清理)的完整设计,请参阅 Device Discovery System 和 Adapter Layer。
Web Panel HTTP API(完整)
要点:
- 所有
/api/* 端点均需要令牌(X-IEMS-Token 标头或 ?token= 参数)
- 统一信封
{schema, ts, data},其中 BigInteger 被序列化为字符串
- 错误代码:
400(参数/JSON 错误)、401(未授权)、404(路由未找到)、405(方法不允许)、409(状态冲突,例如无核心)、500(内部错误)
参考实现:IEMS-TestDevices
测试模组 IEMS-TestDevices(modid iemstest)展示了每种集成模式:
| 设备 |
演示内容 |
test_core 测试核心 |
CoreDevice 集成 + 协议容量声明 |
auto_relay / manual_relay |
自动/手动中继设备(TransferDevice) |
fe_battery |
FE 存储方块(由 FEDA 自动桥接) |
arc_furnace 电弧炉 |
带 GUI/菜单的耗电设备的完整示例 |
构建与开发
BUILDID 构建系统
本模组使用 DLZ Studio BUILDID 约定进行构建;唯一合法的构建入口点是:
.DLZstudio/buildid/
├── BUILDID.txt # 迭代计数器(8 位零填充)
├── build.ps1 # Windows 构建入口点
└── build.sh # Unix/Linux/macOS 构建入口点
Windows:
# ⚠️ 请先设置 JAVA_HOME(脚本环境不会继承它)
$env:JAVA_HOME="D:\Java\jdk-21"
$env:Path="D:\Java\jdk-21\bin;"+$env:Path
powershell -ExecutionPolicy Bypass -File .\.DLZstudio\buildid\build.ps1
Unix:
./.DLZstudio/buildid/build.sh
发布模式(版本号同步至 neoforge.mods.toml):
build.ps1 -Release / build.sh --release
制品命名: IEMS-0.8.0-beta-BUILD.00000120.jar(正常) / iems-1.21.1-neoforge-0.8.0-beta.120.jar(发布版,版本号写回 neoforge.mods.toml)
测试
.\gradlew test # webpanel + 客户端单元测试(包括 RendererConfigTest 等)
.\gradlew compileJava # 快速编译检查
环境要求
- JDK 21
- NeoForge 21.1.x(依赖范围
[21.1.0,))
- 测试运行时类路径已同步至纯 ASCII 目录(以解决中文路径下的 GBK 解码问题)
依赖项
必需依赖
| 模组 |
版本 |
描述 |
| NeoForge |
21.1.0+ |
加载器(依赖范围 [21.1.0,)) |
| Minecraft |
1.21.1 |
— |
捆绑组件
| 组件 |
描述 |
| GeckoLib 4.8.4 |
通过 Jar-in-Jar 捆绑(META-INF/jarjar/);玩家无需单独安装 |
推荐搭配
| 模组 |
描述 |
| IEMS-TestDevices |
官方测试模组:测试核心/中继/FE 电池/电弧炉(推荐的参考实现) |
| 任何 FE 技术模组 |
设备会被 FEDA 自动发现并桥接 |
ZCSMSS(矩阵子节点服务器) |
⚠️ 不再维护:仅兼容旧版 IEMS,未能跟上新版 API |
⚠️ ZCSMSS 已停止支持:它不再适应更新后的 IEMS 版本,因此不支持新版 IEMS。在新版本中,请使用官方测试模组 IEMS-TestDevices,或按照 Developer API 自行提供核心。
安装步骤
- 安装 NeoForge 21.1+
- 下载 IEMS JAR 并将其放入
mods 文件夹
- (可选)添加提供核心的模组(推荐使用官方测试模组 IEMS-TestDevices)
- 启动游戏
常见问题
Q: 为什么没有核心方块?
A: IEMS 是一个能源管理框架;核心由外部模组提供,以避免功能重复。你可以安装官方测试模组 IEMS-TestDevices。
Q: ZCSMSS 还能用吗?
A: 不推荐。ZCSMSS 已不再维护,仅兼容旧版 IEMS 且未能跟上新版 API —— 在新版 IEMS 下不再受支持。请使用官方测试模组 IEMS-TestDevices,或按照 Developer API 自行提供核心。
问:如何确认核心是否正在工作?
答:使用 /iems status 检查网格状态,或访问 Web 面板 http://127.0.0.1:28567/(需要令牌)。
问:保存重新加载后连接丢失了?
答:此问题已在 BUILD.00000110 中修复(区块卸载错误地注销了核心)。网格数据存储在 iems_grid.dat 中,在重启间完全保留;如果仍有丢失,请确保 BUILD ≥ 110。
问:激光变红了?
答:两种情况——网格已关闭(协议容量超限或手动执行 /iems shutdown),或者连接处于孤岛状态(未连接到核心;始终为红色且从未通电)。
问:如果在拉线中途传送离开会发生什么?
答:维度变更(传送门/跨维度传送)会立即撤回线路并发送通知;退出世界也会清除拉线状态。
问:其他模组的 FE 设备如何连接?
答:无需任何操作——FEDA 每 20 刻(青色激光)自动扫描并桥接范围内的 FE 设备。
问:我不喜欢那个青色的桥接激光?
答:在 config/DLZstudio/IEMS/Renderer.toml 中设置 colorizeAutoConnect = false 并重新进入世界即可生效。
问:我想调整 SE 到 FE 的兑换率?
答:更改 config/DLZstudio/IEMS/Energy.toml 中的 fePerSe(默认值为 10,范围 1 ~ 9×10²⁶),然后在游戏中运行 /iems reload 以立即生效,无需重启。请注意,更改兑换率会立即重新解释网格中现有的 SE 值。
问:Web 面板无法访问?
答:检查:游戏是否已加载世界、APIserve.toml 中 enabled 是否为 true、端口 28567 是否被占用,以及防火墙。远程访问需要更改 host = "0.0.0.0" 并必须配合新的令牌和 TLS 反向代理。
问:外部模组依赖 IEMS 时,应如何编写其版本范围?
答:"[0.8.0-beta,)"。切勿写成 "[0.8.0,)"——因为在语义比较中 0.8.0-beta < 0.8.0,所需的依赖会被判定为不满足,导致游戏加载时崩溃。
问:如何开发我自己的设备?
答:请参阅本文档的 开发者 API 部分,并参考 IEMS-TestDevices 源代码(电弧炉是一个带有 GUI 的完整示例)。
调试命令
| 命令 |
权限等级 |
描述 |
/iems status |
无 |
网格状态(核心/能量/主网格/岛屿/连接/关闭原因) |
/iems protocol |
无 |
协议容量使用情况与超限状态 |
/iems scan |
无 |
强制进行 BFS 重扫描并报告结果 |
/iems shutdown |
2 |
手动关闭网格(设备的添加/移除不会自动恢复) |
/iems restart |
2 |
恢复供电 |
/iems reload |
2 |
重新加载所有 IEMS 配置文件(Energy / APIserve / Renderer) |
更新日志
相较于旧版 IEMS 的改进(新版 0.8.0-beta / IEMS0930 ← 旧版 v0.6.0 ~ v0.8.0-BUILD.00000160)
新版本是对旧版 IEMS 的彻底重写:从“方块实体即网格”的单块实现,转变为具有“逻辑与表现完全分离 + 基于工厂的持久化”的能量管理框架。以下按维度列出主要改进和行为差异(当前构建 BUILD.00000120)。
1. 架构:逻辑与表现的完全分离
| 维度 |
旧版 |
新版 |
| 网格逻辑所在位置 |
写在 BlockEntity 内部,与 Level 紧密耦合 |
独立的逻辑层(纯 POJO),不依赖 Level |
| 设备标识 |
硬编码的类型枚举 |
工厂 ID + 参数,可由外部模组注册 |
| 设备间的关系 |
互相持有引用 |
实例自治,仅通过调度器与网格交互 |
| 网格运行 |
区块卸载时停止 |
即使未加载区块也保持模拟 |
- ✅ 外部模组只需
new 一个逻辑实例 + IEMSAPI.attachOrRegisterDevice(),无需继承框架基类
- ✅ 实例可独立创建/销毁/重新参数化,天然适合多核心并行
- ✅ 设备工厂机制使得“没有方块也存在”的设备成为可能
2. 持久化:从“仅连接”到“完整网格快照”
| 维度 |
旧版 |
新版 |
| 存储文件 |
data/DLZstudio/IEMS/iems_connections.dat |
data/iems_grid.dat |
| 存储内容 |
仅连接(坐标 + 类型枚举) |
设备(工厂 ID + 参数)+ 核心 + 所有连接 |
| 重建方法 |
依赖 BEs 逐个重新注册,顺序敏感 |
由服务器启动时的工厂 → restoreState 重建 |
| 区块卸载 |
卸载意味着注销 + 清理连接 |
卸载不会注销设备;重启后连接完全保留 |
| 覆盖范围 |
仅主网格连接 |
完整覆盖主网格 + 岛屿 + 桥梁 |
- ✅ 修复了旧版中“先于核心加载的设备 →
onLoad() 注册无效 → 网格永远为空”的顺序敏感缺陷
- ✅ 修复了“区块卸载错误注销核心 → 重启后核心连接丢失”的问题(BUILD.00000110)
3. 能量系统:从“三种单位的硬编码转换”到“统一的 SE 基准 + 可配置的兑换率”
| 维度 |
旧版 |
新版 |
| 单位系统 |
SE / FE / GE (EnergyValue.EnergyUnit) |
FE / AE / SE,其中 SE 作为内部结算基准 |
| 单位换算 |
硬编码(1 SE = 1 FE,1 SE = 10⁸ GE) |
可配置比率:Energy.toml 中的 fePerSe(默认值为 10) |
| 转换载体 |
需要放置额外的“能量转换器”方块 |
FE 设备由桥接层自动转换,无需转换器 |
| 结算刻数 |
每 2 刻结算一次 SE |
每刻结算 SE(实时结算) |
| 遗留单位 |
GE 贯穿整个代码库 |
移除 GE(连同其显示模式 API 一并移除) |
- ✅
fePerSe 支持热重载(/iems reload),超出范围的值会被截断,非数值型值将回退到默认值
- ✅ FE 桥接声明粒度适应“单刻送达量”;在高交换率下,吞吐量不再被压缩至
fePerSe FE/tick
4. 外部设备集成:从“要求对方适配”到“零适配自动桥接”
- 旧版:其他模组的设备必须实现 IEMS API 或扩展框架方块才能加入电网
- 新版:职责分为两层——设备发现系统 (EDS) 负责扫描和身份识别(仅发现,不桥接),而适配层 (EDA) 使用
FEDA 将每个设备伪装成节点;它每 20 刻重新扫描范围内的任何 NeoForge FE 设备(发电机/消费者/存储设备),并在发现时自动建立桥接连接(青色激光,可配置),其他模组无需任何更改
- ✅ 这终于实现了此前一直无法工作的外部 FE 设备互连(自 BUILD.00000091 起)
5. Web 面板:从“8080 端口未认证只读页面”到“基于 Token 认证的 REST API”
| 维度 |
旧版 |
新版 |
| 端口/绑定 |
8080,仅限本地页面 |
28567,默认绑定 127.0.0.1,可显式启用远程访问 |
| 认证 |
无 |
所有 /api/* 请求均需 Token(通过 Header 或查询参数传递) |
| 表单形式 |
固定页面(状态 + 设备开关) |
REST API:status / devices / connections / topology / metrics / grid/active |
| 数据格式 |
页面直接读取内存 |
统一信封格式 {schema, ts, data},BigInteger 序列化为字符串以防止精度丢失 |
| 时序数据 |
无 |
指标环形缓冲区,可接入外部仪表盘 |
| 写入操作 |
设备电源开关 |
POST /api/grid/active 切换电网状态 |
- ✅ 线程安全:HTTP 线程任务被排入 tick 线程队列执行,消除了与
CoreDevice 的数据竞争
- ✅ 在世界重载时显式停止线程池,并按会话清除指标缓冲区,避免线程泄漏和跨存档干扰
6. 电网拓扑:新的“主网 / 孤岛 / 桥接”三态
- 旧版:任何未连接到核心的设备都被判定为无效(未连接到核心的广播塔直接拒绝连接)
- 新版:尚未连接到核心的设备允许先进行互连(形成孤岛),以红色激光渲染表示无电力供应,一旦放置核心则自动供电
- ✅ BFS 可达性判定 + 拓扑快照(聚合的主网 / 孤岛 / 边界视图)
- ✅ 当设备离开主网时,核心↔设备连接变为红色而非消失(核心侧的豁免过滤)
7. 连接交互:从“简单的两点连线”到“带重新验证的拉线契约”
| 维度 |
旧版 |
新版 |
| 交互检测 |
对具体方块类进行 instanceof 判断 |
IIemsInteractable 契约(与方块类型解耦) |
| 距离反馈 |
顶部文本提示,过远时静默取消 |
HUD 实时显示距离 + 最大距离,过远时自动收回(+10 缓冲余量) |
| 服务器验证 |
较弱(信任客户端) |
C2S 请求 + 服务器重新验证(端点 / 同生物群系 / 距离 / 重复项 / 中继规则) |
| 安全性 |
无 |
邻近检查 + 速率限制(防止通过伪造数据包进行远程任意连接) |
| 残留状态 |
可能在维度变化 / 退出世界后残留 |
维度变化时立即收回线缆,退出世界时强制清除 |
8. 激光渲染:视角、距离和拓扑的三重鲁棒性
- ✅ Billboard 宽度方向(宽度 = 光束方向 × (相机→光束))——侧面视角不再被压缩成细线
- ✅ 屏幕空间最小宽度
max(0.03, distance × 0.0015) ——远距离光束不会变细并消失
- ✅ 禁用背面剔除以实现双面渲染,从任意角度可见;保留深度测试(仍会被方块遮挡)
- ✅ 在相邻条带之间插入退化三角形以消除“幽灵对角线”
- ✅
Renderer.toml 中新增 colorizeAutoConnect:可关闭青色桥接激光
- ✅
ClientGridCache 客户端缓存处理所有三个列表(主网 / 孤岛 / 桥接),包含象限统计和 EMA 平滑处理
9. 并发模型:明确的“Tick 线程所有权”
- 旧版:公共 API 直接读写电网状态,Web 线程和游戏线程并发访问
- 新版:电网状态由服务器 Tick 线程独占拥有;外部线程均通过
IEMSAPI.runOnServerThread() / callOnServerThread() 提交任务
- ✅
GridSyncPayload 大小验证,防止过大数据包导致客户端 OOM
10. 命令与操作
| 旧版 |
新版 |
/iems_debug add_connection |
/iems status 电网概览 |
/iems_debug list_connections |
/iems protocol 协议容量 |
/iems_debug clear_connections |
/iems scan 强制 BFS 重新扫描 |
| — |
/iems shutdown / /iems restart 电网开/关(权限等级 2) |
| — |
/iems reload 热重载所有配置(权限等级 2) |
11. 构建与依赖
- ✅ 采用了 DLZstudio BUILDID 规范:唯一合法构建入口为
build.ps1 / build.sh,构建号嵌入至工件中(旧版使用手动编写的 build_v3.bat)
- ✅ GeckoLib 4.8.4 通过 Jar-in-Jar 方式打包,玩家无需单独安装(旧版将其列为必需的第三方依赖)
- ✅ NeoForge 依赖范围从固定的
21.1.228+ 放宽至 [21.1.0,)
- ✅ 配置集中管理于
config/DLZstudio/IEMS/(Energy / APIserve / Renderer),首次启动时自动生成并附带注释
12. 框架边界变更与行为差异(迁移参考)
以下为行为变更,并非全部为改进;升级时请注意。
- 方块整合:旧版自带中继器 / 广播塔 / 标准存储 / 通用存储 / 转换器 / 标记方块;新版框架仅保留示例设备(中继器 / 广播塔),核心与存储交由外部模组处理(例如 IEMS-TestDevices;ZCSMSS 已停止维护且不符合新的 IEMS 规范)
- 核心连接距离:旧版固定为 1500 格 → 新版由核心在注册时声明,若未声明则框架默认值为 500 格
- 协议容量:旧版默认为 1000,由设备端通过
requestProtocolCapacity / releaseProtocolCapacity 增减 → 新版由核心声明为 protocolLimit,由框架统一计算并进行超限检测
- 视线遮挡检查:旧版广播塔有“被 ≥3 层完整方块阻挡则无法连接”的规则 → 新版采用纯距离判定
- 时间显示模式 API:旧版
standard / coordinated → 新版已移除,统一为 SE/tick
- API 形态:旧版
IEMSApi.getInstance() 实例外观 + EnergyValue 包装类 → 新版静态外观 IEMSAPI + 原始 BigInteger
IEMS0930 (2026-09-30, BUILD.00000114)
采用开发代号 IEMS0930;本条目对应 0.8.0-beta 重写主线版本的最新构建。
修复(连接持久化):
- ✅
setRemoved 错误地在区块卸载时注销核心设备,导致重启后核心连接丢失 —— 现在卸载路径会标记并跳过注销操作,而真正消失的方块仍会正常注销
- ✅ 核心侧对岛屿过滤的豁免:断开与核心的连接后,连接渲染为红色激光而非直接消失(与旧版语义一致)
修复(激光渲染):
- ✅ 退化三角形分离相邻条带,消除“幽灵对角线”
- ✅ 一系列渲染鲁棒性修复:广告牌宽度方向(侧面不消失)、屏幕空间最小宽度(远处不变得过细)、双面渲染(防止特定角度下整束激光消失)以及防御异常跨维度连接
修复(光照):
- ✅ 示例设备允许天光直接穿透(覆盖
propagatesSkylightDown + 记录机制),因此新放置的设备不再显示为“完全黑色的模型”
新增(渲染配置):
- ✅
Renderer.toml 中的 colorizeAutoConnect 开关:可关闭青色 FE 桥接激光
- ✅ 渲染配置的零 IO 懒缓存,重新进入世界时生效
新增(能量交换率配置):
- ✅
Energy.toml 中的 fePerSe 比率项(默认 1 SE = 10 FE,范围 1 ~ 9×10²⁶)
- ✅
/iems reload 命令:手动重新加载所有配置(Energy / APIserve / Renderer),无需重启游戏
- ✅ FE 桥接需求声明适配“单 tick 内送达的数量”;低交换率吞吐量不再被压低至
fePerSe FE/tick
- ✅ 移除旧版遗留的 GE 单位(项目中无任何引用;新单位系统为 FE / AE / SE)
修复(WebPanel / 线程安全):
- ✅ HTTP 线程与 tick 线程之间针对
CoreDevice 的数据竞争 —— 外部线程任务现排队处理(H-01)
- ✅ 世界重载时的线程池泄漏(M-01),指标环形缓冲区跨会话干扰(M-02)
- ✅ C2S 连接请求的近距检查 + 速率限制(H-02),
GridSyncPayload 大小验证以防止客户端 OOM(M-03)
- ✅ 当 FEDA 在重叠的多主机半径下静默跳过注册时,不再创建桥接(M-04)
- ✅ 跨维度 / 退出世界时残留的拉线状态(M-06)
0.8.0-beta Rewrite Mainline (2026-08 ~ 2026-09)
- M1-M4 网格内核:设备注册、BFS 拓扑、协议容量、能量调度
- M5-M7 网络同步与激光渲染:全量快照同步、岛屿/桥接渲染、象限统计
- M8/M8.1 拉线交互:
IIemsInteractable 契约、C2S 请求及服务器重新验证
- M9 模拟风格 设备工厂持久化;无需加载区块即可在重启后保持运行
- M10 WebPanel JDK HttpServer 面板(端口 28567,令牌认证,指标环形缓冲区)
- M11 审查修复 针对 H/M/L 系列潜在问题报告的最小化修复 + 渲染配置
- 外部 FE 桥接(FEDA)首次正常工作:IEMS 与 NeoForge FE 设备成功互联(自 BUILD.00000091 起)
致谢
- GeckoLib 团队 —— 优秀的 3D 模型渲染库(通过 Jar-in-Jar 分发)
- NeoForge 团队 —— 强大的模组加载器
- 北山_Besson —— 提供了部分设备模型
- [EI] 终末地工业 (Endfield Industries) —— 部分模型的参考来源
许可证
MIT License
本模组开源,欢迎贡献与衍生作品!
捆绑的 GeckoLib 4.8.4 同样以 MIT 许可证分发;其版权声明可在嵌套 JAR 内的 LICENSE 文件中找到。
等离子工作室 (DLZstudio) © 2026 · 开发代号 IEMS0930
Integrated Energy Management System (IEMS)
⚠️ IMPORTANT NOTICE FOR INTERNATIONAL PLAYERS:
IEMS is currently a FRAMEWORK ONLY. It does not contain any functional core blocks, generators, or energy storage on its own.
The official Core Provider Mod is currently undergoing testing in the China region and will be released on Modrinth soon.
An energy management framework mod designed for large modpacks: a unified energy abstraction, high-precision BigInteger arithmetic, laser topology visualization, and a web monitoring panel. Devices and cores are hooked up by external mods; IEMS's job is to weave them into one single power grid.
Development team: 等离子工作室 (DLZstudio)
Mod ID: iems
Development codename: IEMS0930
License: MIT License
? Table of Contents
Introduction
IEMS 0.8.0-beta is a complete rewrite of the old IEMS (with a total separation of logic layer and presentation layer):
- Energy management framework — this mod does not ship power generation/storage cores; cores and devices are hooked up by external mods through the API (official reference implementation: IEMS-TestDevices)
- Unified energy abstraction — units such as FE / AE are uniformly converted to SE (Standard Energy), with BigInteger high-precision arithmetic and no precision loss for extremely large values
- Laser connection visualization — laser beams between devices show the grid topology in real time: powered yellow / unpowered red / bridged cyan (configurable)
- Manual wire pulling + automatic networking — Shift + right-click to drag a wire and create a connection (HUD shows live distance), automatic scanning and connection within a broadcast tower's range, automatic bridging of external FE devices
- Protocol capacity management — a device-count-based load limit for the grid, with automatic shutdown protection when exceeded
- Web monitoring panel — view grid status, devices, topology, and historical metrics in a browser in real time (JDK built-in HttpServer, zero third-party dependencies)
- Simulation-style persistence — grid data is stored in
iems_grid.dat and rebuilt from device factories after a restart; it keeps running even when chunks are not loaded
- Open API — a stable
IEMSAPI static facade + the IIemsInteractable wire-pulling contract, for external mods to hook into
⚠️ Important: this mod is a framework and does not provide core blocks! You need to install a mod that provides a core (the official test mod IEMS-TestDevices, or wire one up yourself via the API) to form a complete grid.
Blocks
Core Block
? Provided by other mods through CoreDevice (e.g. the test core from IEMS-TestDevices)
- The grid's identity anchor, the main inlet/outlet of the energy pool, and the protocol capacity manager
- The chunk it is in when registered is automatically set to force-loaded (released on unregister)
- Unique instance; the starting point for the grid's BFS reachability check
Energy Transfer Relay
- Long-distance signal relaying and power transfer; a manual wire-pulling device (does not take part in automatic scanning)
- Connection distance: 500 blocks
- Laser anchor: block center (0.5, 10.75, 0.5) (tower top)
- Laser color: yellow (powered) / red (unpowered)
- Protocol capacity used: 1
Energy Broadcast Tower
- Short-range wireless transfer, with automatic + manual dual modes
- Connection distance: 50 blocks
- Signal source position: tower top (0.5, 8.0, 0.5)
- After placement, automatically scans and connects devices in range (including relays and other broadcast towers)
- Must be connected to the core directly or indirectly to actually supply power (isolated connections are rendered with a red laser)
- Protocol capacity used: 1
- Comes with light level 7, visible in the dark
External FE Devices (automatic bridging)
- IEMS automatically discovers any NeoForge FE device in range (generators/consumers/energy storage from other tech mods)
- Rescans every 20 ticks (1 second) and automatically creates a bridge connection on discovery (cyan laser, configurable to a regular color)
- The other mod needs no adaptation at all
Gameplay Guide
Getting Started
1. Understand the energy unit
All energy uses SE (Standard Energy) as its unified unit and is stored precisely as a BigInteger. The energy of external FE devices is converted automatically by the bridge layer.
2. How the grid works
┌────────────────────────────────────────────┐
│ Core (provided by another mod) │
│ Energy pool · Protocol cap · BFS root │
│ │ │
│ ┌─────────────┼─────────────┐ │
│ ↓ ↓ ↓ │
│ ┌────────┐ ┌────────┐ ┌──────────┐ │
│ │ Relay │───│ Tower │───│FE device │ │
│ │500 blk │ │ 50 blk │ │ auto-brg │ │
│ └────────┘ └────────┘ └──────────┘ │
└────────────────────────────────────────────┘
3. Networking workflow
- Install a mod that provides a core and place the core
- Place relays / broadcast towers (or make direct use of existing FE devices)
- Aim at a device and Shift + right-click to enter wire-pulling mode (the HUD shows the live distance)
- Aim at the target device and Shift + right-click to finish the connection
- Devices within a broadcast tower's range are networked automatically; FE devices are bridged automatically
- Open
http://127.0.0.1:28567/ in a browser to monitor the grid
Device Power Status
- Devices connected to the core (directly or via relays/broadcast towers) are powered automatically
- When the grid is shut down (protocol capacity exceeded or manual shutdown) all devices lose power and lasers turn red
- Connections where both ends are registered but not connected to the core (islanded connections) are rendered as a red laser
Connection System
Manual Wire-Pulling Mode
How to enter:
- Aim at a device that implements the wire-pulling contract and press Shift + right-click
During wire pulling:
- The HUD shows the live pulling distance and the maximum distance
- Beyond the maximum distance (+10 blocks of buffer) the wire is retracted automatically with a notification
- A dimension change (going through a portal / cross-dimension TP) retracts the wire immediately — old coordinates are meaningless in the new dimension
- Leaving the world clears the wire-pulling state automatically
Completing the connection:
- Aim at the target device and press Shift + right-click again
- The client sends a connection request, and the server re-validates it (legal endpoints, same dimension, distance, duplicates, relay rules) before creating the connection
- Clicking the starting point itself or a non-device block → cancels wire pulling
Valid Connection Rules
| Connection type |
Valid |
Condition |
| Core → Relay |
✅ |
Within distance, core force-loaded |
| Core → Broadcast tower |
✅ |
Within distance |
| Relay → Relay |
✅ |
Within 500 blocks |
| Relay → Broadcast tower |
✅ |
Uses the smaller distance limit of the two ends |
| Broadcast tower → Broadcast tower |
✅ |
Within 50 blocks, automatic or manual |
| Broadcast tower → FE device |
✅ |
Automatic bridging (ADAPTER_BRIDGE) |
| Cross-dimension connection |
❌ |
Rejected by both client and server (except dimension bridges) |
| Island-to-island interconnection not connected to the core |
⚠️ |
Allowed to be created, rendered as a red laser, not powered |
Connection Distance Limits
⚠️ The distance limit is the smaller of the distances declared by the two devices at the ends. When nothing is declared, the framework default of 500 blocks is used.
| Device combination |
Maximum distance |
| Relay ↔ Relay |
500 blocks |
| Broadcast tower ↔ Broadcast tower |
50 blocks |
| Broadcast tower ↔ Relay |
50 blocks |
| Bridge (FE device ↔ device) |
Follows the anchoring device |
Laser Display
| State |
Color |
Description |
| Powered connection |
Yellow |
Animated with power flow |
| Unpowered / islanded connection |
Red |
Grid shut down or not connected to the core |
| FE bridge |
Cyan (default) |
Distinguished from regular connections when colorizeAutoConnect = true |
| FE bridge |
Yellow/Red |
Same color as regular connections when colorizeAutoConnect = false |
Rendering features:
- Beam width gets a screen-space minimum-width compensation based on distance (does not become too thin to see at a distance)
- Double-sided rendering, visible from any viewing angle
- Cross-dimension islanded connections are not rendered (direction vector cannot be computed)
- Drawn as long as either end is within render distance (long connections are not culled as a whole by the frustum)
Protocol Capacity System
What Is Protocol Capacity?
Protocol capacity is the upper limit on the number of device connections the grid can support.
| Device |
Capacity used |
| Relay |
1 |
| Broadcast tower |
1 |
| Externally connected device |
Declared by the device |
| Core |
0 (uses none) |
Limit: declared by the core at registration time (protocolLimit), adjustable at runtime.
Over-Limit Protection
When used capacity exceeds total capacity:
- The grid shuts down automatically
- All devices lose power and lasers turn red
/iems status shows the reason for the shutdown
How to recover:
- Remove some devices (an automatic recovery is triggered after a rescan)
- Or have the core mod raise the capacity at runtime
Web Monitoring Panel
How to Access
- Launch the game and load a world (the panel starts/stops with the server)
- Visit in a browser:
http://127.0.0.1:28567/
- A random token is generated automatically on first launch (written to the config file)
Authentication
- All
/api/* endpoints require a token: request header X-IEMS-Token: <token> or query parameter ?token=<token>
/health and / (home page) need no authentication
- The token lives in
config/DLZstudio/IEMS/APIserve.toml
Config File
# config/DLZstudio/IEMS/APIserve.toml
[APIserve]
enabled = true # Whether to enable the web panel
host = "127.0.0.1" # Bind address; for remote access change to "0.0.0.0" (make sure to change the token too and set up a TLS reverse proxy)
port = 28567 # Listening port
token = "a1B2c3D4..." # API token (randomly generated on first launch)
Endpoint Overview
| Method |
Path |
Description |
| GET |
/health |
Liveness probe (no envelope) |
| GET |
/api/status |
Grid overview (core position/energy/capacity/protocol/shutdown status) |
| GET |
/api/devices |
Device list (including the core, per-device attributes) |
| GET |
/api/connections |
Connection list (reachable main grid + boundary connections) |
| GET |
/api/topology |
Topology snapshot (aggregated main grid/islands/boundary views) |
| GET |
/api/metrics |
Time-series metrics (ring buffer, sampled energy/capacity/protocol/device count) |
| POST |
/api/grid/active |
Manually enable/disable the grid (maps to IEMSAPI.setGridActive) |
Data Envelope
{
"schema": 1,
"ts": 1727073600000,
"data": { }
}
- BigInteger fields such as energy/capacity/rates are transmitted as decimal strings (to avoid precision loss)
- Dimensions use resource-key strings (e.g.
"minecraft:overworld")
- With no core, energy returns
"0" and corePos is null
curl Examples
# Read-only endpoint
curl -H "X-IEMS-Token: <token>" http://127.0.0.1:28567/api/status
# Write endpoint (shut down the grid)
curl -X POST -H "X-IEMS-Token: <token>" \
-H "Content-Type: application/json" \
-d '{"active": false}' \
http://127.0.0.1:28567/api/grid/active
? In Windows PowerShell, inline JSON gets its quotes mangled by argument passing; write the request body to a file and submit it with --data-binary @body.json instead.
Energy Exchange Rate Configuration
The exchange rate between SE (the grid's internal standard unit) and FE determines "how large an energy shortfall justifies calling on FE-tier devices", and can be tuned to the energy scale of your modpack.
config/DLZstudio/IEMS/Energy.toml:
# IEMS energy exchange rate configuration
[energy]
# How many FE 1 SE converts to (i.e. SE:FE = 1:N).
# Default 10; range [1, 900000000000000000000000000] (the upper bound is the old fixed value, so old behavior can be restored in one step).
# After editing, run /iems reload in-game for it to take effect immediately (no need to restart the game or leave the world).
# Note: the change reinterprets the existing SE values in the grid (the FE equivalent of 1 SE is redefined), so adjust with care.
fePerSe = 10
- Default: 1 SE = 10 FE: matched to the scale of mainstream FE devices, so FE-bridged devices can take part in grid throughput normally
- Lower bound 1 (1 SE = 1 FE), upper bound 9×10²⁶ (the old hard-coded default; set it to this value to restore old behavior)
- Out-of-range values are clamped to the bounds automatically, and non-numeric values fall back to the default
- Manual reload: after editing the file, run
/iems reload in-game (permission level 2) for it to take effect immediately — no need to restart the game, and no need to leave the world
- If the whole key is deleted while editing, the currently effective value is kept rather than falling back to the default (partial edits won't cause accidental damage)
/iems reload
One command reloads all IEMS config files (manually triggered, no automatic polling):
| Config file |
Reload effect |
Energy.toml |
Re-parses the exchange rate and injects it into the converter, effective immediately |
APIserve.toml |
Rebuilds the web panel, applying enabled / host / port / token |
Renderer.toml |
Invalidates the client render config cache (effective on the local client's next read; remote clients on a dedicated server need to re-enter the world) |
/iems reload requires permission level 2 (same as /iems shutdown and /iems restart).
⚠️ The exchange rate is the definition of SE versus FE; changing it immediately reinterprets all existing SE values in the grid (core energy storage, device capacity, etc.). The SE ratios between devices stay the same and settlement remains conservative, but the FE equivalents presented externally scale overall — set it once according to your modpack's energy scale and avoid adjusting it frequently.
⚠️ When the exchange rate is set high, the real rate of FE-scale devices may convert to less than 1 SE/tick; the bridge layer already adapts its declaration granularity to the "amount delivered in one tick", so throughput will never be crushed down to fePerSe FE/tick no matter how high or low the rate is.
Render Configuration
config/DLZstudio/IEMS/Renderer.toml:
# IEMS render configuration
[renderer]
colorizeAutoConnect = true # true: automatic bridge connections use cyan; false: same color as regular connections (yellow/red)
- Zero-IO lazy cache: config is read on demand and cached, and invalidated automatically when leaving the world
- After changing the config, re-entering the world applies it, with no game restart needed
Persistent Storage
Grid Data Saving
Storage location:
world save/data/iems_grid.dat
Persisted content:
- Device list (indexed by factory ID, including position/type/parameters)
- Core information
- All connections (including islanded connections and bridge connections)
Simulation-Style Rebuild (M9)
- Devices are persisted as a factory ID + parameters, rather than relying on the BlockEntity staying alive
- On server startup,
iems_grid.dat is traversed: factory rebuild → restoreState → grid recovery
- The grid keeps simulating even when the chunk a device is in is not loaded (the BlockEntity is only the appearance/view)
- The chunk the core is in is force-loaded automatically when registered
Automatic Save Points
- When a connection is created / removed
- When the world is saved
- When the server stops
Data Safety
- Breaking a device unregisters it automatically and cleans up its connections
- Chunk unloading no longer unregisters devices (fix in BUILD.00000110:
setRemoved mistakenly unregistered the core, causing connections to be lost after a restart)
- Connections are fully preserved after a save restart
Advanced Gameplay
Networking Tips
- Height advantage: build broadcast towers high up to extend effective coverage
- Relay backbone: use relays (500 blocks) for long-distance backbone links and broadcast towers (50 blocks) for end-point coverage
- FE device reuse: existing tech-mod devices are bridged automatically, with no need to disassemble or modify anything
- Island pre-wiring: devices not yet connected to the core can be interconnected first (a red laser indicates no power), and the whole network powers up once the core is in place
- Core siting: the core's chunk is force-loaded, so put it in the center of your main base to shorten the backbone
Energy Management Strategies
- Peak/valley balancing: rely on energy storage devices to discharge during peak usage
- Capacity planning: keep a 20% protocol capacity margin; exceeding the limit shuts down the whole grid
- Monitoring and alerts:
/api/metrics provides time-series samples that can feed an external dashboard
- Zoned power: give important devices their own core/subnet
Technical Details
Architecture: Full Logic-Presentation Separation
External mod (device provider)
│
└── Block / BlockEntity (registered with Minecraft, appearance/view only)
│
├── new the logic instance in the constructor/loadAdditional() (pure POJO, no Level needed)
├── hook up in onLoad() via IEMSAPI.attachOrRegisterDevice() (server side only)
└── persist parameters in saveAdditional()
│
▼
┌─────────────────────────────────────────────┐
│ IEMS logic layer (com.iems) │
│ │
│ CoreDevice (unique instance, force-loaded) │
│ Device pool DeviceRegistry (N instances) │
│ │
│ GridTopology (BFS/topology snapshot) │
│ EnergyDispatcher (per-tick energy allocation + frame-sliced scheduling) │
│ ProtocolCalculator (capacity calculation/over-limit detection) │
│ FEDA (FE device discovery and bridge adaptation) │
└─────────────────────────────────────────────┘
Design philosophy: instance autonomy — every device instance is fully independent, holds no references to other instances, and interacts with the grid only through the dispatcher; it supports independent new / destroy / parameter changes and naturally supports multi-core parallelism.
Module Breakdown
| Package |
Responsibility |
com.iems.api |
Public facade (IEMSAPI / IIemsInteractable / SubSeAccumulator) |
com.iems.core |
Grid kernel (grid / node / dispatch / protocol) |
com.iems.eds |
Device Discovery System EDS (scanner + identity axis, discovery only, no bridging) |
com.iems.adapter |
Adapter layer (DA: FEDA disguises external FE devices as nodes and hooks them into the grid) |
com.iems.network |
C2S/S2C payloads (connection requests, full sync, shutdown sync) |
com.iems.webpanel |
Web panel (JDK HttpServer, port 28567) |
com.iems.example |
Example devices (relay/broadcast tower, depending only on the api facade) |
Threading Model
- All grid state is owned exclusively by the server tick thread
- External threads (web panel HTTP threads, etc.) submit tasks through
IEMSAPI.runOnServerThread() / callOnServerThread(), eliminating data races
- The web panel thread pool is stopped manually on world reload to prevent thread leaks
Network Sync
GridSyncPayload — full topology sync (three lists for main grid/islands/bridges, with size validation to prevent OOM)
ConnectionRequestPayload — C2S wire-pulling connection request (server re-validation + proximity check + rate limiting)
- Shutdown status / protocol capacity sync along with snapshots; the HUD shows three states
Laser Rendering Details
- Billboard width direction: width = beam direction × (camera→beam), so side views don't vanish
- Screen-space minimum width:
max(0.03, distance × 0.0015), so distant beams don't thin out and disappear
- Degenerate triangles separate adjacent strips, eliminating "ghost diagonals"
- Client cache (
ClientGridCache) handles the three lists (main grid + islands + bridges), with quadrant statistics and EMA smoothing
Device Discovery System
The Device Discovery System (EDS) answers one question: which external energy devices are nearby, and which energy system does each of them belong to?
Its boundary is very clear — it only discovers and classifies; it does not register, create connections, or convert. All bridging decisions are left to the downstream adapter layer.
Scan Entry Points
IEMSAPI.EDS.scan(level, center, radius) // synchronous one-shot scan (server main thread)
IEMSAPI.EDS.addListener(listener) // register a consumer (can be unregistered)
IEMSAPI.EDS.registerFlavor(flavor) // declare your own energy system
- Radius is in blocks, clamped to [1, 128] (
EDSScanner.MAX_RADIUS = 128)
- Global entry points:
IEMSAPI.EDS is a static facade (equivalent to global functions); the scanner's listener table and identity table are also static
- Only loaded chunks are enumerated, then clipped to a spherical range
- Already registered IEMS devices (including the core) are skipped, and counted in the report's
skippedIemsDevices
- Executed synchronously, no async, no rate limiting — call frequency is up to the caller (the built-in adapter does it once every 20 ticks)
Single-Device Probing
Each block entity is probed by taking the union of 7 directional contexts and reading the NeoForge IEnergyStorage capability:
| Reading |
Purpose |
canExtract |
Classified as a producer |
canReceive |
Classified as a consumer |
stored / capacity |
Stored amount and capacity snapshot |
| Exposed sides |
Records from which side energy can be drawn (exposedSides; null means no directional context) |
Identity Axis: EnergyFlavor
The device's energy system is resolved from the namespace of its block ID:
| Field |
Meaning |
namespace |
The mod's namespace (e.g. appliedenergistics2) |
unit |
That system's energy unit (determines the conversion basis for bridging) |
displayName |
Display name of the identity (e.g. Applied Energistics) |
- External mods declare their own system via
IEMSAPI.EDS.registerFlavor
- Unregistered namespaces are treated as FE by default, using the namespace itself as the display name
Discovery Report: EDSReport
One scan produces an immutable report (EDS, v1) that is pushed to all listeners:
| Field |
Description |
origin / radius / scanTick |
Scan origin, clamped radius, scan moment (level.getGameTime()) |
devices |
List of discovered devices (EDSDevice, stable order) |
chunksScanned |
Number of loaded chunks actually enumerated |
blockEntitiesProbed |
Total number of block entities probed (including those without a matching capability) |
skippedIemsDevices |
Number of registered IEMS devices skipped (including the core) |
Convenience subset methods: producers() / consumers() / storage() / byNamespace(ns).
Consumer Contract: IEDSListener
void onDiscovery(EDSReport report);
- The callback runs on the server main thread
- Mental model: the discovery layer only says "this is an FE device, that is an AE device"; whether, with whom, and how to bridge is entirely up to the listener
- Registering the same listener twice means it receives two copies of every report
⚠️ EDSReport is a snapshot at scan time, not live state. Do not rely on it to decide whether an existing device is alive — the discovery layer classifies registered positions as skippedIems and skips them, so a rescan will inevitably not see them (for the correct approach, see sync in the adapter layer).
Adapter Layer
The adapter layer (denoted DA; also called EDA when referring to the set of all DAs) is a pluggable execution layer: it registers external devices found by the discovery layer into the grid disguised as IEMS nodes, and performs bidirectional SE ↔ target-unit read/write conversion every tick.
There is one DA implementation per energy system, named "system name + DA" — the only implementation in this version is FEDA (the DA for the FE system); AE / EU and others are future extension points.
Why an Adapter Layer Is Needed
The dispatcher only recognizes the node interfaces and does not distinguish between "native SE devices" and "adapter-disguised nodes":
IEnergyProducer / IEnergyConsumer / StorageDevice
A DA is merely an executor that translates SE instructions into an external protocol — adding a new energy system means adding one DeviceAdapter implementation, with no kernel changes required.
The DeviceAdapter Interface
Every adapter is bound to one auto-connectable TransferDevice (such as an energy broadcast tower):
| Method |
When called |
Responsibility |
unit() |
— |
The energy system unit it adapts to (FE / AE…) |
scan(level, center, radius) |
Periodic |
Requests a discovery-layer scan and returns the device list this adapter cares about |
sync(level) |
Every 20 ticks |
Diffs the report against registered nodes: register new ones, unregister gone ones |
tick(level) |
Every tick |
Performs actual reads/writes on the external capabilities of its nodes (extract / measure remaining receive capacity / deliver) |
detach() |
Host invalidated |
Unregisters all of its nodes |
⚠️ sync decides existence by probing the block capability of existing devices directly, not relying on the scan report — because the discovery layer classifies registered positions as skippedIems and skips them; if only the report were consulted, a rescan would mistake existing devices for gone ones.
Dispatcher: FeBridgeTicker
| Period |
Action |
| Every tick |
Iterates auto-connected relays → DeviceAdapter.tick; also sweeps orphan nodes |
| Every 20 ticks |
DeviceAdapter.sync rescan (diff sync) |
Order within the main loop (IEMSEvents): FeBridgeTicker.tick / tickRescan → EnergyDispatcher.dispatchAtTick, i.e. sync external devices first, then perform this tick's energy allocation.
Disguised Nodes and Orphan Sweeping
Nodes registered into the grid by adapters all implement the marker interface IAdapterNode:
owner() — ownership chain: host relay → per-device disguised node
isOrphaned() — whether the host has been unregistered (the position in the registry is no longer the original instance)
Two uses:
- Auto-connect exclusion —
IemsAutoConnector skips RELAY_TO_DEVICE automatic connections for disguised nodes; their access goes through ADAPTER_BRIDGE only, avoiding double-connection conflicts
- Orphan sweeping — after the host relay is unregistered, the disguised node becomes a connectionless orphan, which
FeBridgeTicker detects and unregisters every tick
Built-in Implementation: FEDA
FEDA is the only DeviceAdapter implementation in this version; it binds to auto-connect relays (broadcast towers) and registers by classifying external device capabilities:
| External capability |
Disguised node type |
Scenario |
| Can extract |
FeProducerAdapter |
External generator → feeds power into the grid |
| Can receive |
FeConsumerAdapter |
External consumer → draws power from the grid |
| Has capacity |
FeBufferAdapter |
External storage → bidirectional throughput |
- Registers external devices as independent disguised nodes via
silentRegister
- Establishes bridge connections via
IEMSAPI.addConnection(..., ConnectionType.ADAPTER_BRIDGE) (rendered as a cyan laser; coloring can be disabled with colorizeAutoConnect)
- On host invalidation (relay broken / unregistered) it calls
detach() and cleans up its nodes
Conversion Buffer: FeConversionBuffer
Maintains per-device extraction-side and push-side buffers for FE ↔ SE; it is the core state machine of energy conversion in the DA layer:
- Computes the SE demand declaration from the external receive headroom and
maxFePerTick
- SE allocated by the grid is converted to FE at the current
fePerSe into the push pool, then delivered to the external device
- The demand declaration granularity adapts to the exchange rate: when the amount delivered in one tick is less than 1 SE, the declaration is rounded up, so raising the exchange rate does not choke throughput (see Energy Exchange Rate Configuration for details)
Developer API
Quick Start
IEMS is integrated into external mods as a Jar-in-Jar / libs dependency:
Gradle dependency (Groovy DSL):
dependencies {
// After copying the IEMS build artifact into libs/:
implementation files('libs/IEMS-0.8.0-beta-BUILD.00000120.jar')
}
neoforge.mods.toml dependency declaration:
[[dependencies.yourmod]]
modId="iems"
type="required"
versionRange="[0.8.0-beta,)" # ⚠️ The -beta suffix is mandatory; "[0.8.0,)" compares as unsatisfied and crashes on load
ordering="AFTER"
side="BOTH"
Device Integration: Three Logical Base Classes
An external mod's BlockEntity holds a logic instance (a pure POJO):
// 1. Register the factory during mod loading (key to M9 persistence rebuild)
IEMSAPI.registerDeviceFactory("mymod:my_device", MyDevice::new);
// 2. Hook up in BlockEntity.onLoad() (server side only)
GlobalPos pos = new GlobalPos(level.dimension(), blockPos);
MyDevice device = new MyDevice("My Device");
IEMSAPI.attachOrRegisterDevice(pos, device, "mymod:my_device");
// Devices with a factoryId are persisted to iems_grid.dat and rebuilt by the factory after a restart, even without chunk loading
// 3. Unregister in BlockEntity.setRemoved()
IEMSAPI.unregisterDevice(pos);
Core integration:
CoreDevice core = new CoreDevice("My Core",
BigInteger.valueOf(1000), // protocolLimit protocol capacity limit
BigInteger.valueOf(100000), // energyCapacity total energy capacity (SE)
BigInteger.ZERO); // powerGenRate self-generated energy per tick
IEMSAPI.attachOrRegisterCore(pos, core, "mymod:my_core");
// The chunk it is in is force-loaded automatically on registration; released on unregister
Wire-Pulling Contract: IIemsInteractable
A BlockEntity can take part in the framework's built-in Shift+right-click wire-pulling interaction simply by implementing this interface:
public class MyDeviceBlockEntity extends BlockEntity implements IIemsInteractable {
@Override
public boolean canBeConnectionEndpoint() {
return true;
}
@Override
public int getMaxConnectionDistance() {
return 500; // framework default of 500 blocks when not declared
}
}
- A purely client-side discovery mechanism (
instanceof detection); the server does not rely on this interface for security decisions
- The wire-pulling HUD, over-distance retraction, and dimension-change retraction are all handled by the framework
- Server-side connection creation goes through
ConnectionRequestPayload re-validation (endpoints / same dimension / distance / duplicates / relay rules)
IEMSAPI Static Facade (Method Overview)
| Category |
Method |
Description |
| Thread safety |
runOnServerThread(Runnable) |
Submit a task asynchronously from an external thread |
| Thread safety |
callOnServerThread(Supplier, timeoutMs) |
Wait synchronously for a result from an external thread |
| Factory |
registerDeviceFactory(id, factory) |
Register a device factory (M9 rebuild) |
| Device |
attachOrRegisterDevice(pos, node, factoryId) |
Hook up a device (persisted if it has a factory) |
| Device |
unregisterDevice(pos) |
Unregister a device |
| Core |
attachOrRegisterCore(pos, core, factoryId) |
Hook up a core (chunk force-loaded) |
| Core |
unregisterCore(pos) |
Unregister a core |
| Query |
getCurrentEnergy() / getTotalCapacity() |
Energy pool (BigInteger) |
| Query |
getProtocolUsed() / getProtocolTotal() |
Protocol capacity |
| Query |
getSnapshot() |
Topology snapshot (main grid/islands/boundary) |
| Query |
isDeviceConnected(pos) |
Whether the device is connected to the main grid |
| Connection |
addConnection(a, b, type) / removeConnection(...) |
Connection management |
| Control |
setGridActive(boolean) / forceRescan() |
Grid on/off / force rescan |
| Power |
registerPowerInput(id, rate) / unregisterPowerInput(id) |
Power source registration |
| EDS |
EDS.scan(level, center, radius) |
Nearby device scan (radius clamped to [1,128]) |
| EDS |
EDS.addListener(l) / EDS.removeListener(l) |
Register/unregister a discovery listener |
| EDS |
EDS.registerFlavor(flavor) |
Register an energy system identity (namespace → unit/display name) |
For the full design of the discovery and adapter layers (scan boundaries, report structure, DeviceAdapter lifecycle, disguised nodes and orphan sweeping), see Device Discovery System and Adapter Layer.
Web Panel HTTP API (Complete)
Key points:
- All
/api/* endpoints require a token (X-IEMS-Token header or ?token= parameter)
- Uniform envelope
{schema, ts, data}, with BigIntegers stringified
- Error codes:
400 (parameter/JSON error), 401 (unauthorized), 404 (route not found), 405 (method not allowed), 409 (state conflict such as no core), 500 (internal error)
Reference Implementation: IEMS-TestDevices
The test mod IEMS-TestDevices (modid iemstest) demonstrates every integration pattern:
| Device |
What it demonstrates |
test_core test core |
CoreDevice integration + protocol capacity declaration |
auto_relay / manual_relay |
Automatic/manual relay devices (TransferDevice) |
fe_battery |
FE storage block (automatically bridged by FEDA) |
arc_furnace arc furnace |
A complete example of a power-consuming device with GUI/Menu |
Building and Development
BUILDID Build System
This mod is built using the DLZ Studio BUILDID convention; the only legal build entry points are:
.DLZstudio/buildid/
├── BUILDID.txt # Iteration counter (8-digit zero-padded)
├── build.ps1 # Windows build entry point
└── build.sh # Unix/Linux/macOS build entry point
Windows:
# ⚠️ Set JAVA_HOME first (the script environment does not inherit it)
$env:JAVA_HOME="D:\Java\jdk-21"
$env:Path="D:\Java\jdk-21\bin;"+$env:Path
powershell -ExecutionPolicy Bypass -File .\.DLZstudio\buildid\build.ps1
Unix:
./.DLZstudio/buildid/build.sh
Release mode (version number synced to neoforge.mods.toml):
build.ps1 -Release / build.sh --release
Artifact naming: IEMS-0.8.0-beta-BUILD.00000120.jar (normal) / iems-1.21.1-neoforge-0.8.0-beta.120.jar (release, version number written back to neoforge.mods.toml)
Testing
.\gradlew test # webpanel + client unit tests (including RendererConfigTest, etc.)
.\gradlew compileJava # quick compile check
Environment Requirements
- JDK 21
- NeoForge 21.1.x (dependency range
[21.1.0,))
- The test runtime classpath has been synced to a pure ASCII directory (to work around GBK decoding issues with Chinese paths)
Requirements
Required Dependencies
| Mod |
Version |
Description |
| NeoForge |
21.1.0+ |
Mod loader (dependency range [21.1.0,)) |
| Minecraft |
1.21.1 |
— |
Bundled Components
| Component |
Description |
| GeckoLib 4.8.4 |
Bundled via Jar-in-Jar (META-INF/jarjar/); players do not need to install it separately |
Recommended Companions
| Mod |
Description |
| IEMS-TestDevices |
Official test mod: test core/relay/FE battery/arc furnace (the recommended reference implementation) |
| Any FE tech mod |
Devices are discovered and bridged automatically by FEDA |
ZCSMSS (matrix sub-node server) |
⚠️ No longer maintained: only compatible with the old IEMS and has not kept up with the new API |
⚠️ ZCSMSS is discontinued: it no longer adapts to updated versions of IEMS, and therefore does not support the new IEMS. On the new version, use the official test mod IEMS-TestDevices instead, or provide a core yourself following the Developer API.
Installation Steps
- Install NeoForge 21.1+
- Download the IEMS JAR and put it in the
mods folder
- (Optional) Add a mod that provides a core (the official test mod IEMS-TestDevices is recommended)
- Launch the game
FAQ
Q: Why is there no core block?
A: IEMS is an energy management framework; the core is provided by external mods to avoid duplicated functionality. You can install the official test mod IEMS-TestDevices.
Q: Does ZCSMSS still work?
A: Not recommended. ZCSMSS is no longer maintained and is only compatible with the old IEMS without keeping up with the new API — under the new IEMS it is no longer supported. Use the official test mod IEMS-TestDevices instead, or provide a core yourself following the Developer API.
Q: How do I know whether the core is working?
A: Use /iems status to check grid status, or visit the web panel at http://127.0.0.1:28567/ (token required).
Q: Connections are lost after restarting the save?
A: This was fixed in BUILD.00000110 (chunk unloading mistakenly unregistered the core). Grid data is stored in iems_grid.dat and fully preserved across restarts; if losses still occur, make sure BUILD ≥ 110.
Q: The lasers turned red?
A: Two situations — the grid is shut down (protocol capacity exceeded or manual /iems shutdown), or the connection is islanded (not connected to the core; always red and never powered).
Q: What happens if I teleport away halfway through pulling a wire?
A: A dimension change (portal/cross-dimension TP) retracts the wire immediately with a notification; leaving the world also clears the wire-pulling state.
Q: How do FE devices from other mods get connected?
A: No action needed — FEDA automatically scans and bridges FE devices in range every 20 ticks (cyan laser).
Q: I don't like the cyan bridge laser?
A: Set colorizeAutoConnect = false in config/DLZstudio/IEMS/Renderer.toml and re-enter the world for it to take effect.
Q: I want to adjust the SE-to-FE exchange rate?
A: Change fePerSe in config/DLZstudio/IEMS/Energy.toml (default 10, range 1 ~ 9×10²⁶), then run /iems reload in-game for it to take effect immediately, with no restart needed. Note that changing the rate immediately reinterprets the existing SE values in the grid.
Q: The web panel is unreachable?
A: Check: whether the game has a world loaded, whether enabled is true in APIserve.toml, whether port 28567 is occupied, and the firewall. Remote access requires changing host = "0.0.0.0" and must be accompanied by a new token and a TLS reverse proxy.
Q: How should an external mod write its version range when depending on IEMS?
A: "[0.8.0-beta,)". You must not write "[0.8.0,)" — in semantic comparison 0.8.0-beta < 0.8.0, so the required dependency would be judged unsatisfied and the game would crash on load.
Q: How do I develop my own device?
A: See the Developer API section of this document and refer to the IEMS-TestDevices source (the arc furnace is a complete example with a GUI).
Debug Commands
| Command |
Permission |
Description |
/iems status |
none |
Grid status (core/energy/main grid/islands/connections/shutdown reason) |
/iems protocol |
none |
Protocol capacity usage and over-limit state |
/iems scan |
none |
Force a BFS rescan and report the result |
/iems shutdown |
2 |
Manually shut down the grid (device add/remove does not auto-recover) |
/iems restart |
2 |
Restore power |
/iems reload |
2 |
Reload all IEMS config files (Energy / APIserve / Renderer) |
Changelog
Improvements over the Old IEMS (new 0.8.0-beta / IEMS0930 ← old v0.6.0 ~ v0.8.0-BUILD.00000160)
The new version is a complete rewrite of the old IEMS: from a monolithic implementation where "the block entity is the grid" to an energy management framework with "full logic-presentation separation + factory-based persistence". The main improvements and behavior differences are listed below by dimension (current build BUILD.00000120).
1. Architecture: Full Separation of Logic and Presentation
| Dimension |
Old |
New |
| Where grid logic lives |
Written inside BlockEntity, tightly coupled to Level |
A separate logic layer (pure POJO) that does not depend on Level |
| Device identity |
Hard-coded type enum |
Factory ID + parameters, registrable by external mods |
| Relations between devices |
Hold references to each other |
Instance autonomy, interacting with the grid only through the dispatcher |
| Grid operation |
Stops when chunks are unloaded |
Keeps simulating even without chunk loading |
- ✅ External mods only need to
new a logic instance + IEMSAPI.attachOrRegisterDevice(), without extending framework base classes
- ✅ Instances can be independently created / destroyed / re-parameterized, naturally suited to multi-core parallelism
- ✅ The device factory mechanism makes "devices that exist even without their block" possible
2. Persistence: From "connections only" to a "complete grid snapshot"
| Dimension |
Old |
New |
| Storage file |
data/DLZstudio/IEMS/iems_connections.dat |
data/iems_grid.dat |
| Stored content |
Connections only (coordinates + type enum) |
Devices (factory ID + parameters) + core + all connections |
| Rebuild method |
Relies on BEs re-registering one by one, order-sensitive |
Rebuilt by factories on server startup → restoreState |
| Chunk unload |
Unload means unregister + clean up connections |
Unloading does not unregister devices; connections are fully preserved after a restart |
| Coverage |
Main grid connections only |
Full coverage of main grid + islands + bridges |
- ✅ Fixes the old order-sensitivity defect where "a device loads before the core →
onLoad() registration has no effect → the grid is forever empty"
- ✅ Fixes "chunk unload mistakenly unregisters the core → core connections are lost after a restart" (BUILD.00000110)
3. Energy System: From "hard-coded conversion of three units" to "unified SE basis + configurable exchange rate"
| Dimension |
Old |
New |
| Unit system |
SE / FE / GE (EnergyValue.EnergyUnit) |
FE / AE / SE, with SE as the internal settlement basis |
| Unit conversion |
Hard-coded (1 SE = 1 FE, 1 SE = 10⁸ GE) |
Configurable rate: fePerSe in Energy.toml (default 10) |
| Conversion carrier |
Requires placing an extra "energy converter" block |
FE devices are converted automatically by the bridge layer, no converter needed |
| Settlement tick |
SE/2 ticks (once every 2 ticks) |
SE/tick (settled every tick) |
| Legacy unit |
GE threaded through the whole codebase |
GE removed (along with its display-mode API) |
- ✅
fePerSe supports hot reload (/iems reload), clamps out-of-range values, and falls back to the default for non-numeric values
- ✅ FE bridge declaration granularity adapts to the "amount delivered in one tick"; under a high exchange rate throughput is no longer crushed down to
fePerSe FE/tick
4. External Device Integration: From "requiring adaptation by the other side" to "zero-adaptation automatic bridging"
- Old: devices from other mods had to implement the IEMS API or extend framework blocks to join the grid
- New: responsibilities are split across two layers — the Device Discovery System (EDS) handles scanning and identity recognition (discovery only, no bridging), while the adapter layer (EDA) uses
FEDA to disguise each device as a node; it rescans any NeoForge FE device in range every 20 ticks (generators / consumers / storage) and establishes a bridge connection automatically on discovery (cyan laser, configurable), with zero changes required in the other mod
- ✅ This finally unlocked the external FE device interconnection that had never worked before (since BUILD.00000091)
5. Web Panel: From "unauthenticated read-only page on 8080" to "token-authenticated REST API"
| Dimension |
Old |
New |
| Port / binding |
8080, local page only |
28567, default 127.0.0.1, remote access can be explicitly enabled |
| Authentication |
None |
All /api/* require a token (header or query parameter) |
| Form |
Fixed page (status + device toggles) |
REST API: status / devices / connections / topology / metrics / grid/active |
| Data format |
Page reads memory directly |
Uniform envelope {schema, ts, data}, BigIntegers stringified to prevent precision loss |
| Time-series data |
None |
Metrics ring buffer, can feed an external dashboard |
| Write operations |
Device power toggles |
POST /api/grid/active to toggle the grid |
- ✅ Thread safety: HTTP thread tasks are queued onto the tick thread, eliminating data races with
CoreDevice
- ✅ The thread pool is explicitly stopped on world reload, and the metrics buffer is cleared per session, avoiding thread leaks and cross-save interference
6. Grid Topology: New "main grid / island / bridge" tri-state
- Old: anything not connected to the core was judged invalid (broadcast towers not connected to the core simply refused connections)
- New: devices not yet connected to the core are allowed to interconnect first (islands), rendered with a red laser to indicate no power, and powered automatically once the core is in place
- ✅ BFS reachability determination + topology snapshot (aggregated main grid / island / boundary views)
- ✅ Core↔device connections turn red rather than disappearing when the device leaves the main grid (core-side exemption filtering)
7. Connection Interaction: From "simple two-point lines" to a "wire-pulling contract with re-validation"
| Dimension |
Old |
New |
| Interaction detection |
instanceof on concrete block classes |
The IIemsInteractable contract (decoupled from block type) |
| Distance feedback |
Top text prompt, silently cancelled when too far |
HUD live distance + maximum distance, automatic retraction when too far (+10 buffer) |
| Server validation |
Weak (trusted the client) |
C2S request + server re-validation (endpoints / same dimension / distance / duplicates / relay rules) |
| Security |
None |
Proximity check + rate limiting (prevents remote arbitrary connections via forged packets) |
| Leftover state |
Could linger across dimension changes / world exit |
Wire retracted immediately on dimension change, forcibly cleared on world exit |
8. Laser Rendering: Triple Robustness for Viewing Angle, Distance, and Topology
- ✅ Billboard width direction (width = beam direction × (camera→beam)) — side views are no longer compressed into a thin line
- ✅ Screen-space minimum width
max(0.03, distance × 0.0015) — distant beams do not thin out and vanish
- ✅ Back-face culling disabled for double-sided rendering, visible from any angle; depth testing retained (still occluded by blocks)
- ✅ Degenerate triangles inserted between adjacent strips to eliminate "ghost diagonals"
- ✅ New
colorizeAutoConnect in Renderer.toml: the cyan bridge laser can be toggled off
- ✅ The
ClientGridCache client cache handles all three lists (main grid / islands / bridges), with quadrant statistics and EMA smoothing
9. Concurrency Model: Explicit "tick thread ownership"
- Old: public APIs read/write grid state directly, with web threads and the game thread accessing concurrently
- New: grid state is owned exclusively by the server tick thread; external threads all submit through
IEMSAPI.runOnServerThread() / callOnServerThread()
- ✅
GridSyncPayload size validation to prevent oversized packets from causing client OOM
10. Commands and Operations
| Old |
New |
/iems_debug add_connection |
/iems status grid overview |
/iems_debug list_connections |
/iems protocol protocol capacity |
/iems_debug clear_connections |
/iems scan force a BFS rescan |
| — |
/iems shutdown / /iems restart grid on/off (permission 2) |
| — |
/iems reload hot reload all config (permission 2) |
11. Build and Dependencies
- ✅ Adopted the DLZstudio BUILDID convention: the only legal build entry points are
build.ps1 / build.sh, with the build number embedded in the artifact (the old version used a hand-written build_v3.bat)
- ✅ GeckoLib 4.8.4 is bundled via Jar-in-Jar, so players do not need to install it separately (the old version listed it as a required external dependency)
- ✅ The NeoForge dependency range was relaxed from a fixed
21.1.228+ to [21.1.0,)
- ✅ Config is centralized in
config/DLZstudio/IEMS/ (Energy / APIserve / Renderer), auto-generated with comments on first launch
12. Framework Boundary Changes and Behavior Differences (Migration Reference)
The following are behavior changes, not all improvements; be aware of them when upgrading.
- Block consolidation: the old version shipped relays / broadcast towers / standard storage / general storage / converters / marker blocks; the new framework keeps only the example devices (relay / broadcast tower), leaving cores and storage to external mods (e.g. IEMS-TestDevices; ZCSMSS is no longer maintained and does not follow the new IEMS)
- Core connection distance: fixed at 1500 blocks in the old version → declared by the core at registration in the new version, with a framework default of 500 blocks when not declared
- Protocol capacity: defaulted to 1000 in the old version, increased/decreased by the device side via
requestProtocolCapacity / releaseProtocolCapacity → declared by the core as protocolLimit in the new version, with the framework performing unified calculation and over-limit detection
- Line-of-sight occlusion check: old broadcast towers had a "cannot connect if blocked by ≥3 layers of full blocks" rule → the new version uses pure distance determination
- Time display mode API: old
standard / coordinated → removed in the new version, unified as SE/tick
- API shape: old
IEMSApi.getInstance() instance facade + EnergyValue wrapper → new static facade IEMSAPI + raw BigInteger
IEMS0930 (2026-09-30, BUILD.00000114)
Development codename IEMS0930 adopted; this entry corresponds to the latest build of the 0.8.0-beta rewrite mainline.
Fixes (connection persistence):
- ✅
setRemoved mistakenly unregistering the core device on chunk unload, causing core connections to be lost after a restart — the unload path now marks and skips unregistration, while a block that truly disappears is still unregistered normally
- ✅ Core-side exemption for island filtering: after disconnecting from the core, the connection is rendered as a red laser instead of simply disappearing (aligned with old semantics)
Fixes (laser rendering):
- ✅ Degenerate triangles separate adjacent strips, eliminating "ghost diagonals"
- ✅ A series of rendering robustness fixes: billboard width direction (doesn't vanish from the side), screen-space minimum width (doesn't thin out at a distance), double-sided rendering (prevents a whole beam from disappearing at certain angles), and defense against abnormal cross-dimension connections
Fixes (lighting):
- ✅ Example devices let skylight pass straight through (
propagatesSkylightDown override + documented mechanism), so newly placed devices no longer appear as "completely black models"
New (render config):
- ✅
colorizeAutoConnect toggle in Renderer.toml: the cyan FE bridge laser can be turned off
- ✅ Zero-IO lazy cache for render config, effective on re-entering the world
New (energy exchange rate config):
- ✅
fePerSe rate entry in Energy.toml (default 1 SE = 10 FE, range 1 ~ 9×10²⁶)
- ✅
/iems reload command: manually reload all config (Energy / APIserve / Renderer) with no game restart needed
- ✅ FE bridge demand declaration adapts to the "amount delivered in one tick"; under a low exchange rate throughput is no longer crushed down to
fePerSe FE/tick
- ✅ Removed the legacy GE unit from the old version (zero references in the project; the new unit system is FE / AE / SE)
Fixes (WebPanel / thread safety):
- ✅ Data race between HTTP threads and the tick thread over
CoreDevice — external thread tasks are now queued (H-01)
- ✅ Thread pool leak on world reload (M-01), metrics ring buffer cross-session interference (M-02)
- ✅ Proximity check + rate limiting for C2S connection requests (H-02),
GridSyncPayload size validation to prevent client OOM (M-03)
- ✅ No more bridges created when FEDA silently skips registration under overlapping multi-host radii (M-04)
- ✅ Leftover wire-pulling state across dimensions / on world exit (M-06)
0.8.0-beta Rewrite Mainline (2026-08 ~ 2026-09)
- M1-M4 Grid kernel: device registration, BFS topology, protocol capacity, energy dispatch
- M5-M7 Network sync and laser rendering: full snapshot sync, island/bridge rendering, quadrant statistics
- M8/M8.1 Wire-pulling interaction: the
IIemsInteractable contract, C2S requests, and server re-validation
- M9 simulation-style device factory persistence; keeps running after a restart without chunk loading
- M10 WebPanel JDK HttpServer panel (port 28567, token authentication, metrics ring buffer)
- M11 review fixes minimized fixes for the H/M/L series of potential issue reports + render config
- External FE bridging (FEDA) working for the first time: IEMS and NeoForge FE devices successfully interconnected (since BUILD.00000091)
Acknowledgments
- The GeckoLib team — an excellent 3D model rendering library (distributed via Jar-in-Jar)
- The NeoForge team — a powerful mod loader
- 北山_Besson — provided some device models
- [EI] 终末地工业 (Endfield Industries) — source of reference for some models
License
MIT License
This mod is open source; contributions and derivative works are welcome!
The bundled GeckoLib 4.8.4 is likewise distributed under the MIT License; its notice can be found in the LICENSE file inside the nested JAR.
等离子工作室 (DLZstudio) © 2026 · Development codename IEMS0930
评论 0
登录后参与评分
还没有评论,来抢沙发吧