
综合能源管理系统
新增了SE能量单位,以及一系列以《明日方舟:终末地》为风格的能源传输装置,采用高精度存储与计算技术来处理能源。
查看大图综合能量管理系统(IEMS)
一个面向大型整合包的能量管理框架模组:统一能量抽象、BigInteger 高精度运算、激光拓扑可视化以及 Web 监控面板。设备与核心由外部模组接入;IEMS 的职责是将它们编织成一张单一电网。
开发团队: 等离子工作室(DLZstudio)
模组 ID: iems
开发代号: IEMS0930
许可证: MIT License
📖 目录
- 简介
- 方块
- 玩法指南
- 连接系统
- 协议容量系统
- Web 监控面板
- 能量兑换率配置
- 渲染配置
- 持久化存储
- 进阶玩法
- 技术细节
- 设备发现系统
- 适配层
- 开发者 API
- 构建与开发
- 环境需求
- 常见问题
- 调试命令
- 更新日志
- 致谢
简介
IEMS 0.8.0-beta 是旧版 IEMS 的完全重写(逻辑层与表现层彻底分离):
- 能量管理框架 —— 本模组不提供发电/储电核心;核心与设备由外部模组通过 API 接入(官方参考实现:IEMS-TestDevices)
- 统一能量抽象 —— FE / AE 等单位统一换算为 SE(标准能量),采用 BigInteger 高精度运算,超大数值无精度损失
- 激光连接可视化 —— 设备间的激光束实时显示电网拓扑:通电黄色 / 未通电红色 / 桥接青色(可配置)
- 手动拉线 + 自动组网 —— Shift + 右键拖拽线缆建立连接(HUD 实时显示距离),广播塔范围内自动扫描并连接,外部 FE 设备自动桥接
- 协议容量管理 —— 基于设备数量的电网负载上限,超出时自动停机保护
- Web 监控面板 —— 在浏览器中实时查看电网状态、设备、拓扑与历史指标(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 秒)重新扫描,发现后自动创建桥接连接(青色激光,可配置为常规颜色)
- 对方模组无需任何适配
玩法指南
入门
1. 了解能量单位
所有能量以 SE(标准能量)为统一单位,并以 BigInteger 精确存储。外部 FE 设备的能量由桥接层自动换算。
2. 电网工作原理
┌────────────────────────────────────────────┐
│ 核心(由其他模组提供) │
│ 能量池 · 协议上限 · BFS 根节点 │
│ │ │
│ ┌─────────────┼─────────────┐ │
│ ↓ ↓ ↓ │
│ ┌────────┐ ┌────────┐ ┌──────────┐ │
│ │ 中继 │───│ 广播塔 │───│FE 设备 │ │
│ │500 格 │ │ 50 格 │ │ 自动桥接 │ │
│ └────────┘ └────────┘ └──────────┘ │
└────────────────────────────────────────────┘
3. 组网流程
- 安装提供核心的模组并放置核心
- 放置中继 / 广播塔(或直接利用已有的 FE 设备)
- 对准设备Shift + 右键进入拉线模式(HUD 实时显示距离)
- 对准目标设备Shift + 右键完成连接
- 广播塔范围内的设备自动组网;FE 设备自动桥接
- 在浏览器中打开
http://127.0.0.1:28567/监控电网
设备供电状态
- 连接到核心的设备(直接连接或经中继/广播塔)自动供电
- 电网停机时(协议容量超出或手动停机)所有设备断电,激光变红
- 两端均已注册但未连接到核心的连接(孤立连接)以红色激光渲染
连接系统
手动拉线模式
进入方式:
- 对准实现了拉线契约的设备,按 Shift + 右键
拉线过程中:
- HUD 显示实时拉线距离与最大距离
- 超出最大距离(+10 格缓冲)时自动收回线缆并提示
- 切换维度(通过传送门 / 跨维度传送)立即收回线缆 —— 旧坐标在新维度中毫无意义
- 退出世界时自动清除拉线状态
完成连接:
- 对准目标设备再次按 Shift + 右键
- 客户端发送连接请求,服务端重新校验(合法端点、同维度、距离、重复、中继规则)后创建连接
- 点击起点自身或非设备方块 → 取消拉线
有效连接规则
| 连接类型 | 是否有效 | 条件 |
|---|---|---|
| 核心 → 中继 | ✅ | 距离内,核心强加载 |
| 核心 → 广播塔 | ✅ | 距离内 |
| 中继 → 中继 | ✅ | 500 格内 |
| 中继 → 广播塔 | ✅ | 取两端距离限制中较小者 |
| 广播塔 → 广播塔 | ✅ | 50 格内,自动或手动 |
| 广播塔 → FE 设备 | ✅ | 自动桥接(ADAPTER_BRIDGE) |
| 跨维度连接 | ❌ | 客户端与服务端均拒绝(维度桥除外) |
| 未连接到核心的孤岛互连 | ⚠️ | 允许创建,以红色激光渲染,不供电 |
连接距离限制
⚠️ 距离限制取两端设备所声明距离中较小者。未声明时使用框架默认值 500 格。
| 设备组合 | 最大距离 |
|---|---|
| 中继 ↔ 中继 | 500 格 |
| 广播塔 ↔ 广播塔 | 50 格 |
| 广播塔 ↔ 中继 | 50 格 |
| 桥接(FE 设备 ↔ 设备) | 跟随锚定设备 |
激光显示
| 状态 | 颜色 | 描述 |
|---|---|---|
| 通电连接 | 黄色 | 随能量流动播放动画 |
| 未通电 / 孤立连接 | 红色 | 电网停机或未连接到核心 |
| FE 桥接 | 青色(默认) | colorizeAutoConnect = true 时与常规连接区分 |
| FE 桥接 | 黄色/红色 | colorizeAutoConnect = false 时与常规连接同色 |
渲染特性:
- 光束宽度根据距离获得屏幕空间最小宽度补偿(远距离不会细到看不见)
- 双面渲染,任意视角可见
- 跨维度孤立连接不渲染(无法计算方向向量)
- 只要任意一端在渲染距离内即绘制(长连接不会被视锥整体剔除)
协议容量系统
什么是协议容量?
协议容量是电网可支持的设备连接数量上限。
| 设备 | 占用容量 |
|---|---|
| 中继 | 1 |
| 广播塔 | 1 |
| 外部接入设备 | 由设备声明 |
| 核心 | 0(不占用) |
上限: 由核心在注册时声明(protocolLimit),可在运行时调整。
超限保护
当已用容量超过总容量时:
- 电网自动停机
- 所有设备断电,激光变红
/iems status显示停机原因
恢复方式:
- 移除部分设备(重新扫描后触发自动恢复)
- 或由核心模组在运行时提高容量
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"(务必同时更换令牌并配置 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 字段以十进制字符串传输(避免精度损失)
- 维度使用资源键字符串(例如
"minecraft:overworld") - 无核心时能量返回
"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 内送达的量”自适应声明粒度,因此无论兑换率多高或多低,吞吐量都不会被压制到
fePerSeFE/tick。
渲染配置
config/DLZstudio/IEMS/Renderer.toml:
# IEMS 渲染配置
[renderer]
colorizeAutoConnect = true # true:自动桥接连接使用青色;false:与常规连接同色(黄/红)
- 零 IO 懒缓存:配置按需读取并缓存,退出世界时自动失效
- 修改配置后重新进入世界即可应用,无需重启游戏
持久化存储
电网数据保存
存储位置:
世界存档/data/iems_grid.dat
持久化内容:
- 设备列表(以工厂 ID 为索引,含位置/类型/参数)
- 核心信息
- 所有连接(包括孤立连接与桥接连接)
仿真式重建(M9)
- 设备以工厂 ID + 参数形式持久化,而非依赖 BlockEntity 存活
- 服务器启动时遍历
iems_grid.dat:工厂重建 →restoreState→ 电网恢复 - 设备所在区块未加载时电网仍持续模拟(BlockEntity 只是外观/视图)
- 核心所在区块在注册时自动强加载
自动保存点
- 创建 / 移除连接时
- 保存世界时
- 服务器停止时
数据安全
- 破坏设备自动注销并清理其连接
- 区块卸载不再注销设备(BUILD.00000110 修复:
setRemoved误注销核心,导致重启后连接丢失) - 保存重启后连接完整保留
进阶玩法
组网技巧
- 高度优势: 将广播塔建在高处以扩大有效覆盖
- 中继骨干: 使用中继(500 格)做长距离骨干链路,广播塔(50 格)做端点覆盖
- FE 设备复用: 已有科技模组设备自动桥接,无需拆卸或改造
- 孤岛预布线: 尚未连接到核心的设备可先互连(红色激光表示无电),核心就位后整网通电
- 核心选址: 核心所在区块强加载,将其放在主基地中心可缩短骨干
能量管理策略
- 削峰填谷: 依靠储能设备在用电高峰放电
- 容量规划: 保留 20% 协议容量余量;超出上限会停机整个电网
- 监控与告警:
/api/metrics提供时序样本,可接入外部仪表盘 - 分区供电: 为重要设备设置独立核心/子网
技术细节
架构:逻辑与表现完全分离
外部模组(设备提供方)
│
└── Block / BlockEntity(注册到 Minecraft,仅外观/视图)
│
├── 在构造器/loadAdditional() 中 new 逻辑实例(纯 POJO,无需 Level)
├── 在 onLoad() 中通过 IEMSAPI.attachOrRegisterDevice() 接入(仅服务端)
└── 在 saveAdditional() 中持久化参数
│
▼
┌─────────────────────────────────────────────┐
│ IEMS 逻辑层(com.iems) │
│ │
│ CoreDevice(唯一实例,强加载) │
│ 设备池 DeviceRegistry(N 个实例) │
│ │
│ GridTopology(BFS/拓扑快照) │
│ EnergyDispatcher(每 tick 能量分配 + 帧切片调度) │
│ ProtocolCalculator(容量计算/超限检测) │
│ FEDA(FE 设备发现与桥接适配) │
└─────────────────────────────────────────────┘
设计理念:实例自治 —— 每个设备实例完全独立,不持有其他实例的引用,仅通过调度器与电网交互;支持独立 new / 销毁 / 参数变更,天然支持多核心并行。
模块划分
| 包 | 职责 |
|---|---|
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 显示三种状态
激光渲染细节
- Billboard 宽度方向:宽度 = 光束方向 × (相机→光束),侧视角不会消失
- 屏幕空间最小宽度:
max(0.03, 距离 × 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 tick 执行一次)
单设备探测
每个方块实体通过取 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 节点注册进电网,并每 tick 执行 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 | 将报告与已注册节点做差分:注册新出现的,注销消失的 |
tick(level) |
每 tick | 对其节点的外部能力执行实际读写(抽取 / 测量剩余接收容量 / 送达) |
detach() |
宿主失效 | 注销其所有节点 |
⚠️
sync通过直接探测现有设备的方块能力来决定存在性,不依赖扫描报告 —— 因为发现层会将已注册位置归类为skippedIems并跳过;若只看报告,重新扫描会把现有设备误认为已消失。
调度器:FeBridgeTicker
| 周期 | 动作 |
|---|---|
| 每 tick | 遍历自动连接的中继 → DeviceAdapter.tick;同时清扫孤儿节点 |
| 每 20 tick | DeviceAdapter.sync 重新扫描(差分同步) |
主循环内的顺序(IEMSEvents):FeBridgeTicker.tick / tickRescan → EnergyDispatcher.dispatchAtTick,即先同步外部设备,再执行本 tick 的能量分配。
伪装节点与孤儿清扫
由适配器注册进电网的节点均实现标记接口 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生命周期、伪装节点与孤儿清扫),参见设备发现系统与适配层。
Web 面板 HTTP API(完整)
要点:
- 所有
/api/*端点均需
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。