Easy Origins API

Easy Origins API

这是origins模组的一个API，它为origins添加了几个新功能，极大增强了之前可行的能力，或直接实现了此前无法达成的事项。

EOrigins API

EOrigins API 是一个可复用的 Forge 1.20.1 版 Origins 与 Apoli 附属模组。它添加了有界实体查询、持久目标存储、移动工具、弹射物归属工具，以及其他数据包作者可直接通过 JSON 使用的基础构建模块。

它 不会 替代 Origins 或 Apoli，本身也不添加可游玩的起源。它扩展了 Apoli 现有的动作与条件注册表，使自定义起源可以在正常的 origins:* 功能之外，使用额外的 eorigins_api:* 工厂。

Wiki - https://evehaddox.site/eapi/

主要功能

有界实体查询

  • 对附近的已加载实体执行动作，无需依赖宽泛的 @e 选择器。
  • 可配置半径、结果数量限制、球形或立方体范围、排序方式和 Apoli 条件。
  • 通过可配置的辅助瞄准与方块遮挡检测，查找玩家视野中的实体。
  • 使用独立的进入、停留和退出动作，维护可复用的实体字段。
  • 仅查询已加载实体，绝不扫描整个维度。

持久目标、集合与检查点

  • 在命名空间槽位中，通过 UUID 和维度存储目标。
  • 在每个命名的实体集合中，最多存储 256 个唯一的实体引用。
  • 稍后可对已加载的成员进行添加、移除、清空、计数和动作执行。
  • 存储坐标和旋转，用于后续的传送。
  • 存储数据在登出、重启和玩家死亡后依然保留。
  • 解析实体引用时，绝不会强制加载其所在区块。

双实体移动与伤害

  • 在同一维度中交换两个实体的位置。
  • 将目标从施动者处推开。
  • 将目标拉向施动者，并可配置停止距离。
  • 相对于目标面对的方向传送施动者。
  • 应用已注册的伤害类型，同时保留施动者归属和击杀判定。

弹射物工具

  • 检测原版及兼容的模组弹射物。
  • 检查弹射物是否拥有已加载的主人。
  • 在弹射物与其主人之间执行双实体动作。
  • 检查施动者是否拥有该目标弹射物。
  • 分配或清除弹射物归属权。
  • 立即停止弹射物，并通过有界动作稍后进行清理。

弹射物工具支持继承 Minecraft Projectile 类的实体。通过无关的自定义类实现弹射物实体的模组，可能需要单独的兼容性处理。

诊断

操作员无需安装单独的剖析附属模组即可检查 API：

/eapi status
/eapi debug queries
/eapi debug storage <player>
/eapi debug reset

查询诊断报告由 API 拥有的查询的累计调用次数、空间候选数、选中结果数、结果限制命中数、平均时间和最大耗时。存储诊断显示命名目标、位置和实体集合槽位，且不会打印原始 UUID。

调试命令需要权限等级 2。

性能与安全

本 API 专为多人整合包设计，在这些整合包中，起源可能依赖重复的命令选择器、标记实体或盔甲架。

  • 实体搜索使用 Minecraft 的空间实体索引。
  • 每个通用查询都有有界半径和结果数量限制。
  • 任意顺序的搜索在达到其限制后可以立即停止。
  • 最近和最远搜索仅保留请求数量的结果。
  • 存储的实体引用不会创建区块加载票据。
  • 实体集合每个槽位有 256 个引用的硬性限制。
  • 玩家传送使用服务器正常的玩家连接处理方式。
  • 跨维度行为仅在具有明确、安全策略的情况下启用。

API 无法自动将一个低效的起源变得高效：非常大的范围或故意每 tick 执行的动作仍然可能昂贵。内置的诊断功能有助于识别这些情况。

示例

将附近的活体实体捕获到持久集合中：

{
  "type": "eorigins_api:collect_entities",
  "slot": "example:targets",
  "mode": "replace",
  "radius": 16.0,
  "limit": 32,
  "shape": "sphere",
  "sort": "nearest",
  "include_self": false,
  "bientity_condition": {
    "type": "origins:target_condition",
    "condition": {
      "type": "origins:living"
    }
  }
}

稍后对当前已加载的成员执行动作：

{
  "type": "eorigins_api:action_on_entity_set",
  "slot": "example:targets",
  "limit": 32,
  "same_dimension": true,
  "require_alive": true,
  "bientity_action": {
    "type": "eorigins_api:pull_target_toward",
    "strength": 1.25,
    "stop_distance": 1.5,
    "include_vertical": true,
    "set_velocity": true
  }
}

为槽位标识符使用你自己的命名空间，以防止与其他数据包冲突。

环境要求

EOrigins API 0.5.0 的目标环境：

  • Minecraft: 1.20.1
  • Forge: 47.4.10
  • Origins Forge: 1.10.0.9
  • Apoli Forge: 2.9.0.8
  • Calio Forge: 1.11.0.5
  • Caelus Forge: 3.1.0+1.20
  • Java: 17

在 服务器和每个客户端 上同时安装 EOrigins API 及其依赖项。本模组面向 Forge；此构建不支持 Fabric 版本的 Origins。

0.5.0 中的工厂表面

当前版本注册了：

  • 15 个实体动作
  • 6 个实体条件
  • 9 个双实体动作
  • 1 个双实体条件

值得注意的工厂包括：

for_each_entity
entity_count_in_range
action_on_entity_in_view
entity_field
collect_entities
action_on_entity_set
store_target
store_position
swap_positions
push_target_away
pull_target_toward
teleport_actor_relative_to_target
damage_target
projectile_has_owner
action_on_projectile_owner
set_projectile_owner

下载中包含一份详细的快速参考，包含字段定义和 JSON 示例。

面向整合包与起源作者

EOrigins API 主要是一个基础设施。它适用于以下机制：

  • 锁定与最后一击目标选择；
  • 弹射物屏障与反射系统；
  • 持久化的捕获或被标记实体组；
  • 无需永久性标记盔甲架的检查点传送；
  • 拉拽、击退、交换和目标相对移动；
  • 光环进入/停留/退出处理；
  • 带归属的自定义伤害；
  • 重复宽泛实体选择器的有界替代方案。

API 保持起源中立：特定于某个角色或整合包的机制应属于该起源的数据包，而不是核心库。

当前限制

  • 可取消的时间线计划在后续版本中推出，并非 0.5.0 的一部分。
  • 当引用的实体被卸载时，存储的实体引用依然存在；动作只会跳过未解析的成员。
  • 弹射物归属分配不会自动重定向速度。
  • 相对传送仅限于同维度。
  • 不寻常的模组弹射物实现可能需要专门的兼容性。

问题反馈

反馈问题时，请包含：

  1. 完整的 latest.log 或崩溃报告。
  2. /eapi status 的结果。
  3. 相关的起源能力 JSON。
  4. 如果问题涉及性能，请提供 /eapi debug queries 的结果。
  5. 问题发生在客户端、专用服务器，还是两者都有。