IEMS

模组

· 作者 NSCS00

添加了《明日方舟:终末地》风格的高精度储能与计算能源单位(SE energy units)以及一系列能源传输装置。

0 本站下载 0 关注 更新于 1 个月前

最新 0.8.0-beta.120 · 1.21.1 · NeoForge

一键开服(送7天)

集成能源管理系统 (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. 网络工作流程

  1. 安装一个提供 Core 的模组并放置 Core
  2. 放置 Relay / Broadcast Tower(或直接使用现有的 FE 设备)
  3. 瞄准一个设备并按住 Shift + 右键 进入拉线模式(HUD 会显示实时距离)
  4. 瞄准目标设备并按住 Shift + 右键 完成连接
  5. 处于 Broadcast Tower 范围内的设备会自动组网;FE 设备会自动进行桥接
  6. 在浏览器中打开 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),可在运行时调整。

超限保护

当使用容量超过总容量时:

  1. 电网自动关闭
  2. 所有设备失去电力,激光变为红色
  3. /iems status 显示关闭原因

如何恢复:

  • 移除部分设备(扫描后会自动触发恢复)
  • 或者让 Core 模组在运行时提高容量上限

Web 监控面板

如何访问

  1. 启动游戏并加载世界(面板随服务器启动/停止)
  2. 在浏览器中访问:http://127.0.0.1:28567/
  3. 首次启动时自动生成随机令牌(写入配置文件)

身份验证

  • 所有 /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() — 主机是否已被注销(注册表中的位置不再是原始实例)

两个用途:

  1. 自动连接排除 — IemsAutoConnector 跳过对伪装节点的 RELAY_TO_DEVICE 自动连接;其访问仅通过 ADAPTER_BRIDGE 进行,避免双重连接冲突
  2. 孤儿清理 — 主机中继注销后,伪装节点将成为无连接的孤儿,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 自行提供核心。

安装步骤

  1. 安装 NeoForge 21.1+
  2. 下载 IEMS JAR 并将其放入 mods 文件夹
  3. (可选)添加提供核心的模组(推荐使用官方测试模组 IEMS-TestDevices)
  4. 启动游戏

常见问题

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

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源