综合能源管理系统

综合能源管理系统

新增了SE能量单位,以及一系列以《明日方舟:终末地》为风格的能源传输装置,采用高精度存储与计算技术来处理能源。

技术

综合能量管理系统(IEMS)

版本 代号 NEOFORGE MINECRAFT

一个面向大型整合包的能量管理框架模组:统一能量抽象、BigInteger 高精度运算、激光拓扑可视化以及 Web 监控面板。设备与核心由外部模组接入;IEMS 的职责是将它们编织成一张单一电网。

开发团队: 等离子工作室(DLZstudio)

模组 ID: iems

开发代号: IEMS0930

许可证: MIT License


📖 目录


简介

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. 组网流程

  1. 安装提供核心的模组并放置核心
  2. 放置中继 / 广播塔(或直接利用已有的 FE 设备)
  3. 对准设备Shift + 右键进入拉线模式(HUD 实时显示距离)
  4. 对准目标设备Shift + 右键完成连接
  5. 广播塔范围内的设备自动组网;FE 设备自动桥接
  6. 在浏览器中打开 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),可在运行时调整。

超限保护

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

  1. 电网自动停机
  2. 所有设备断电,激光变红
  3. /iems status 显示停机原因

恢复方式:

  • 移除部分设备(重新扫描后触发自动恢复)
  • 或由核心模组在运行时提高容量

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"(务必同时更换令牌并配置 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 内送达的量”自适应声明粒度,因此无论兑换率多高或多低,吞吐量都不会被压制到 fePerSe FE/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() —— 宿主是否已注销(注册表中的位置已不是原实例)

两种用途:

  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 生命周期、伪装节点与孤儿清扫),参见设备发现系统与适配层。

Web 面板 HTTP API(完整)

要点:

  • 所有 /api/* 端点均需