Gate Manage API

门禁管理 API

提供一个用于管理《X4：基石》中跃迁门和加速器的游戏内API。该API支持创建、连接或断开连接以及销毁跃迁门和加速器。

功能特点

• 在指定位置和方向上创建跳跃门和加速器，并可选择分配所有权。
• 连接或断开现有的跳跃门和加速器。
• 摧毁现存的空间跳跃门和加速器。
• 提供可用门和加速器宏ID的列表。
• 支持回调的异步命令处理。

安装

您可以通过Steam客户端下载最新版本 - Gate Manage API

或者你也可以通过 Nexus Mods 来完成 - 门管理 API

用法

该API设计供其他脚本或模组使用。它提供了一组可被调用的函数，用于执行与跳跃门和加速器相关的各种操作。

检查可用性

在使用API之前，你可以检查它在当前上下文中是否可用：

简单创建一条提示，其中包含对**<event_cue_signalled cue="md.Gate_Manage_API.Reloaded" />**的反应：

示例

<cue name="YouOnReloaded" instantiate="true">
<conditions>
<event_cue_signalled cue="md.Gate_Manage_API.Reloaded" />
</conditions>
<actions>
<debug_text text="'Gate_Manage_API: 已重新加载'" chance="100" filter="general" />
</actions>
</cue>

主要原则

通常情况下，你只需要做一件事——用参数表调用 md.Gate_Manage_API.Request 指令。如果需要获取命令结果，则应在参数表中提供回调函数。当命令完成时，回调函数将携带结果表被调用。

基本示例

<cue name="..." >
<actions>
<set_value name="$args"
exact="table[
$command = 'destroy_gate'
$gate     = @$gate,
$callback = Your_Capture_Results,
]" />
<signal_cue_instantly cue="md.Gate_Manage_API.Request" param="$args" />
</actions>
</cue>
<cue name="Your_Capture_Results" instantiate="true">
<conditions>
<event_cue_signalled/>
</conditions>
<actions>
<set_value name="$result" exact="@event.param" />
<debug_text text="'命令 %s 已完成，结果为 %s (%s)'。[@$result.$command, @$result.$result, @$result.$info]" chance="100" filter="general" />
</actions>
</cue>

标准结果字段

所有命令都会返回一个结果表，其中包含输入参数的内容以及一些额外的标准字段：

• $result：字符串，值为'success'或'error'。
• $info：字符串，关于结果的附加信息，特别在出现错误时。
• $detail：字符串，关于结果的更详细信息，特别是在发生错误时。可选，可能不存在。

命令

支持以下带有相应参数的命令：

修建传送门

在星系内的指定位置和方向创建新的跳跃门或加速器。可选择为创建的门或加速器指定一个所有者。

• $command: 字符串，必须为 'build_gate'。
• $sector：扇区对象（必填）。
• $macroId: string（必填），要创建的网关或加速器的宏ID。
• $ownerId：字符串（可选，默认值为 "'ownerless'"），可以使用字符串 "'null'" 表示无所有者。
• $offset：矢量（必需），扇区内的位置偏移。
• $rotation: 四元数（如果getRotationFromMap为false，则为必填项），表示门或加速器的朝向。
• $getRotationFromMap: 布尔值（可选，默认为 false），如果为 true，将根据扇区的地图数据确定旋转角度。
• $callback: 函数，用于调用结果的回调函数。

成功时，结果表中会返回创建的门口或加速器对象。除了输入和标准结果字段外，结果表还将包含：

• $gate：门对象，创建的门或加速器（仅成功时）。

连接门

连接两个跳跃门或加速器，使其之间可以瞬间旅行。

• $command: 字符串，必须为'connect_gates'。
• $gateSource：门对象（必需），第一个（源）门，用于连接。
• $gateTarget：门对象（必需），要连接的第二个（目标）门。
• $callback: 函数，用于调用结果的回调函数。

断开之门

断开两个已连接的跳跃门或加速通道。

• $command: 字符串，必须为 'disconnect_gates'。
• $gateSource：门对象（必填），第一个（源）门，用于断开连接。
• $gateTarget：门对象（必需），第二个（目标）门，用于断开连接。
• $callback：函数，用于调用结果并执行的回调函数。

摧毁大门

摧毁一个现有的跳跃门或加速器。

• $command: 字符串，必须是 'destroy_gate'。
• $gate：gate 对象（必需），要摧毁的门或加速器。
• $callback: 函数，用于调用获取结果的回调函数。

除了输入字段和标准结果字段外，结果表还将包含：

• $name：大门物体名称，被摧毁的大门或加速器的名称。
• $sector：星区对象，被摧毁的星门或加速器所在的星区。

mark_gate

在地图上标记跳跃门或加速器，以便于识别。

• $command：字符串，必须为'mark_gate'
• $gate: 门对象（必需），要标记的门或加速器。
• $callback：函数，用于调用并传递结果的回调函数。

取消标记门

移除地图上之前标记的跳跃门或加速器的选定范围。

• $command: 字符串，必须为 'unmark_gate'
• $gate：门对象（必填），要取消标记的门或加速器。
• $callback：函数，用于接收结果并调用的回调函数。

获取宏表

以表格形式获取跳跃门和加速器的可用宏。

• $command: 字符串，必须为 'get_macro_tables'。
• $callback：函数，用于调用结果的回调函数。

除输入和标准结果字段外，结果表还将包含：

• $gatesTable：可用跳跃门宏的表格列表。
• $acceleratorsTable：可用加速器宏的表格列表。

列表中的每个表格将包含：

• $name: 字符串，宏的名称。
• $macroId：字符串，宏的ID。
• $icon: 字符串，宏关联的图标。
• $isAccelerator：布尔值，若该宏用于加速器则为 true

不幸的是，由于游戏lua引擎的限制，至少目前，判断一个宏对应的是加速器还是跳跃门的唯一方法是检查图标字段。如果图标是mapob_transorbital_accelerator，则为加速器；如果是mapob_jumpgate，则为跳跃门。

因此，如果某个模组添加了带有不同图标的新门或加速器，该API将无法正确识别它们。

如果有人知道更好的识别宏类型的方法，请告诉我。

参考

目前，只有一个模组使用了这个 API——门控制器，从 1.16 版本及更高版本开始：

• 在 Steam 上
• 在 Nexus Mods 上

制作人员

• 作者：Chem O`Dun，来自 Nexus Mods 和 Steam 创意工坊
• *《X4：基石》*是Egosoft的商标。

致谢

• EGOSOFT - 为了游戏本身（实际上，是为了整个游戏系列）！
• 特别感谢 Forleyor 在 Lua 方面给予的帮助！感谢他让我对 Lua 产生兴趣，以及他的耐心！没有他，我绝不会接触 Lua，更不会开始制作这个模组！
• 感谢 cheapman44 在Discord上关于门控管理的讨论，这促使我制作了这个API。
• 感谢 Egosoft Discord 上 X4模组频道 的所有成员。

更新日志

[1.01] - 2025-10-18

• 已修复
  • 遗漏了 SirNukes Mod 支持 API 的依赖声明

[1.00] - 2025年10月17日

• 已添加
  • 初始公开版本