额外数据API · X4 基石Mod

.detail-panel[hidden] { display: block !important; } .detail-tabs { display: none; } /* These three panels are rendered by the browser. */ [data-versions], [data-changelog-panel], [data-comments] { display: none; }

[size=4][u]Extra Data API[/u][/size]

解答游戏自带的 getter 无法回答的 ware、macro、component 和游戏参数问题。

一个供 UI 模组使用的小型库。它为每个 UI 脚本提供一个全局的 [b]ExtraData[/b] 表，其中包含 [b]GetWareDataEx[/b]、[b]GetMacroDataEx[/b] 和 [b]GetComponentDataEx[/b]：调用形式与游戏的 [b]GetWareData[/b]、[b]GetMacroData[/b] 和 [b]GetComponentData[/b] 相同，这些 getter 能识别的每个键都会直接透传，另外还有扩展键，其答案从正在运行的游戏本身读取；[b]GetParamsDataEx[/b] 以相同形式添加游戏参数。

[code]
local name, volume, effects = ExtraData.GetWareDataEx("energycells", "name", "volume", "productioneffects")
-- effects = { default = { work = 0.43, sunlight = 1, efficiency = 1 }, terran = { work = 0.43, sunlight = 1, efficiency = 1 } }
local work = ExtraData.GetWareDataEx("hullparts", "productioneffects.default.work")
-- work = 0.37
local box, bays = ExtraData.GetMacroDataEx("pier_par_harbor_03_macro", "boundingbox", "dockingbays")
-- box = { max = { x, y, z }, centre = { x, y, z }, radius = n }; bays = three rows, one per docking bay
local magnet = ExtraData.GetComponentDataEx(playerId, "lootmagnet")
-- magnet = true while the player's loot magnet is on; playerId as every UI script has it, ConvertStringTo64Bit(tostring(C.GetPlayerID()))[/code][size=3][u][b]Features[/b][/u][/size]
[list]
[][b][b]ExtraData.GetWareDataEx(wareId, key, ...)[/b][/b] - 每个键对应一个结果，按顺序返回，与 [b]GetWareData[/b] 的返回方式完全一致。[b]GetWareData[/b] 能识别的键由 [b]GetWareData[/b] 回答；下列扩展键由本库回答。[/]
[][b][b]productioneffects[/b][/b] - 一个表，为该 ware 的每种生产方法各含一项（[b]default[/b]、[b]terran[/b] 等），每项为 [b]{ work = n, sunlight = n, efficiency = n }[/b]：游戏解析出的该方法生产效果的各乘积因子。[b]work[/b] 是模块在满劳动力时达到的劳动力加成（[b]0.43[/b] = +43%），[b]sunlight[/b] 是光照敏感度（能量电池上为 [b]1[/b]，其他地方为 [b]0[/b]），[b]efficiency[/b] 是基础因子（[b]1[/b]）。[b]GetWareData[/b]、生产模块的库条目以及任务编辑器（Mission Director）都不暴露这些；游戏只通过 [b]GetProductionModuleData[/b] 为已存在的模块报告这些值。[/]
[][b][b]productioneffects.<method>[/b][/b] - 单一方法的相同表，当该 ware 没有此方法时为 [b]nil[/b]。[/]
[][b][b]productioneffects.<method>.<type>[/b][/b] - 单个数字，[b]type[/b] 为 [b]work[/b]、[b]sunlight[/b] 或 [b]efficiency[/b]。[/]
[][b][b]ExtraData.GetMacroDataEx(macroId, key, ...)[/b][/b] - 基于 [b]GetMacroData[/b] 的相同形式，另含以下扩展键：
[list]
[] [b][b]boundingbox[/b][/b] - [b]{ max = { x, y, z }, centre = { x, y, z }, radius = n }[/b]：该 macro 的包围盒，单位为米，[b]max[/b] 为相对于 [b]centre[/b] 的半尺寸。[/]
[][b][b]connections[/b][/b] - 该 macro 的所有连接，行形式为 [b]{ name, tags, position, direction, rows, macro }[/b]：[b]tags[/b] 为连接的标签名，[b]position[/b] 以米为单位、位于该 macro 的坐标系中，[b]rows[/b] 为其旋转的三行（[b]direction[/b] 是第三行），[b]macro[/b] 为连接到的 macro（如有）。[/]
[][b][b]connections.<tag>[/b][/b] - 仅包含带有该标签的连接。[/]
[][b][b]snapconnections[/b][/b] - 模块用于与其他模块吸附的连接。[/]
[][b][b]dockingbays[/b][/b] - 停靠港，不含与其共享标签的飞船存储。[/]
[][b][b]exclusionzones[/b][/b] - 带有接近区的连接，每行含该区的 [b]sizetag[/b]、[b]size[/b]（完整尺寸，单位为米）和 [b]centre[/b]。[/]
[][b][b]builderclasses[/b][/b]、[b][b]equipclasses[/b][/b]、[b][b]supplyclasses[/b][/b] - 对于建造模块，为其建造、装备和补给的舰船类别（[b]{ "ship_s", "ship_m" }[/b]，没有时为 [b]{}[/b]）；对其他任何 macro 为 [b]nil[/b]。[/]
[/list][/]
[][b][b]ExtraData.GetComponentDataEx(componentId, key, ...)[/b][/b] - 基于 [b]GetComponentData[/b] 的相同形式，另含此扩展键：
[list]
[] [b][b]lootmagnet[/b][/b] - 玩家战利品磁铁开启时为 [b]true[/b]，关闭时为 [b]false[/b]。只有玩家对象会回答；其他任何 component 都返回 [b]nil[/b]。[/]
[/list][/]
[][b][b]ExtraData.GetParamsDataEx(key, ...)[/b][/b] - 游戏参数，每个键一个结果，每次调用时实时读取，因此其他模组的补丁也会计入：
[list]
[] [b][b]exclusionzones[/b][/b] - 按标签索引的接近区形状：[b]{ [tag] = { size = { x, y, z }, centre = { x, y, z } } }[/b]。[/]
[/list][/]
[][b][b]ExtraData.Available()[/b][/b] - 三个标志：本游戏版本能否回答 ware 键、能否回答 macro 和参数键、能否回答 component 键。第三个需要玩家存在，因此在游戏仍在加载时为 [b]false[/b]。[/]
[][b][b]ExtraData.ExtendedKeys[/b][/b] - 扩展键名，按 getter 分组（[b]ware[/b]、[b]macro[/b]、[b]component[/b]、[b]params[/b]）。[/]
[]全局函数 [b]GetWareDataEx[/b]、[b]GetMacroDataEx[/b]、[b]GetComponentDataEx[/b] 和 [b]GetParamsDataEx[/b] 是相同的函数，供偏好 getter 自身风格的脚本使用。[/]
[]失败即关闭：在库无法识别的游戏版本上，每个扩展键都返回 [b]nil[/b]，并在游戏日志中写一行说明原因。绝不会写入游戏内存。[/]
[/list][size=3][u][b]Limitations[/b][/u][/size]
[list]
[]此模组需要禁用扩展设置中的 [b]Protected UI Mode[/b]。[/]
[]这些函数存在于菜单的 UI 状态（[b]ui/addons[/b]）中，几乎所有 UI 模组都在该状态运行。它们不适用于 [b]ui/core[/b] 状态的脚本。[/]
[]仅限 Windows 游戏：在原生 Linux 版本上，扩展键返回 [b]nil[/b]。通过 Proton 或 Wine 在 Linux 上运行的 Windows 游戏应该可以工作。[/]
[]已在 [b]X4: Foundations[/b] 8.00 和 9.00（GOG）上验证。本库在信任所读取的任何内容之前，会将游戏数据与游戏自带的 getter 进行比对，因此未知版本会给出 [b]nil[/b] 答案，绝不会给出错误答案。[/]
[]效果为游戏解析后的值：未定义某类型效果的方法会报告游戏该类型的默认值，[b]work[/b] 和 [b]sunlight[/b] 为 [b]0[/b]，[b]efficiency[/b] 为 [b]1[/b]。[/]
[/list][size=3][u][b]Requirements[/b][/u][/size]
[list]
[][b]X4: Foundations[/b] 8.00 或更新版本。[/]
[][b]Lua Log API[/b]，作者 Chem ODun，版本 [b]1.00[/b] 或更新。 [list] [*] 可通过 Steam 获取 - [url=https://steamcommunity.com/sharedfiles/filedetails/?id=3823580916]Lua Log API[/url][/*] [*]或通过 Nexus Mods - [url=https://www.nexusmods.com/x4foundations/mods/2473]Lua Log API[/url][/*] [/list][/*] [/list][size=3][u][b]Installation[/b][/u][/size] 你可以通过 Steam 客户端下载最新版本 - [url=https://steamcommunity.com/sharedfiles/filedetails/?id=3825599643]Extra Data API[/url] 或者通过 Nexus Mods - [url=https://www.nexusmods.com/x4foundations/mods/2519]Extra Data API[/url] [size=3][u][b]Save state[/b][/u][/size] [b]No[/b]（移除该扩展不会破坏存档）。 [size=3][u][b]Usage[/b][/u][/size] [list=1] [*]在你的模组的 [b]content.xml[/b] 中将该库添加为依赖项，使其在你的模组之前安装并加载：[/*] [/list] [code] <dependency id="ws_3825599643" optional="false" name="Extra Data API" version="100"></dependency> [/code][list=1] [*]在你的模组的 [b]ui.xml[/b] 中将该库的 UI 附加组件添加为依赖项，使 [b]ExtraData[/b] 在你的 Lua 文件运行时已存在：[/*] [/list] [code] <dependency name="extra_data_api" /> [/code][list=1] [*]从你的 Lua 代码中调用这些函数：[/*] [/list] [code] local effects = ExtraData.GetWareDataEx("refinedmetals", "productioneffects.default") if effects then local fullWorkforceOutput = baseOutput * (1 + effects.work) end [/code]对于可选依赖，请省略第 2 步：对未安装的库添加附加组件依赖会导致你的附加组件无法加载。改为在调用时查找该表： [code] local effects = ExtraData and ExtraData.GetWareDataEx("refinedmetals", "productioneffects.default")[/code][size=3][u][i]Debug output[/i][/u][/size] 该库通过 Lua Log API 写入其日志行，标签为 [b]ExtraData:[/b]。错误总是会被写入。如需更多内容，可从 Lua 设置级别：[b]ExtraData.SetDebugLevel("debug")[/b] 或 [b]ExtraData.SetDebugLevel("trace")[/b]；或从任务编辑器（Mission Director）将 [b]player.entity.$ExtraDataApiConfig.$debugLevel[/b] 设为 [b]'debug'[/b] 或 [b]'trace'[/b]，并以该级别作为参数触发 Lua 事件 [b]ExtraDataApi.SetDebugLevel[/b]。该库没有自己的 Options 页面。 [size=3][u][b]How it works[/b][/u][/size] 游戏将每个 ware、其生产方法及其效果保存在一个注册表中，而游戏自带的 [b]GetProductionMethodResources[/b] 函数首先会查找该注册表。该库在首次请求扩展键时，在运行中的游戏里找到该查找一次，顺着它找到注册表，并读取与游戏所读取的相同数据结构。在回答任何内容之前，它会将若干知名 ware 的体积和价格，以及它涉及的每种方法的时间和数量，与 [b]GetWareData[/b] 及游戏的生产方法信息所报告的内容进行比对。只要有一处不一致，就会在当前会话中关闭 ware 键。 macro 键也以相同方式工作：该库顺着游戏自带的 [b]GetMacroClass[/b] 找到 macro 注册表，并顺着建造菜单自身的代码找到接近区表。在回答之前，它会将每个连接与其名称哈希进行校验，并将若干知名 macro 与其文件进行校验，任何不匹配都会关闭 macro 键。 战利品磁铁键读取游戏自带的 [b]ToggleLootMagnet[/b] 所翻转的那个字节。该库在运行中的游戏里找到该函数的代码，顺着它找到玩家对象，要求游戏的 [b]SetLootMagnetActive[/b] 以相同方式到达同一对象，并在回答前检查该字节是单纯的 0 或 1。 [size=3][u][b]Credits[/b][/u][/size] [list] [*]作者：Chem ODun，位于 [url=https://next.nexusmods.com/profile/ChemODun/mods?gameId=2659]Nexus Mods[/url] 和 [url=https://steamcommunity.com/id/chemodun/myworkshopfiles/?appid=392160]Steam Workshop[/url][/]
[][i]"X4: Foundations"[/i] 是 [url=https://www.egosoft.com]Egosoft[/url] 的商标。[/]
[/list][size=3][u][b]Acknowledgements[/b][/u][/size]
[list]
[][url=https://www.egosoft.com]EGOSOFT[/url] - 感谢 X 系列。[/]
[/list][size=3][u][b]Changelog[/b][/u][/size]

[size=3][u][i][1.01] - 2026-10-27[/i][/u][/size]
[list]
[]新增
[list]
[] 带 [b]lootmagnet[/b] 键的 [b]GetComponentDataEx[/b]：玩家的战利品磁铁是否开启[/]
[/list][/]
[]移除
[list]
[] 对 Print Extension List 模组的依赖要求[/]
[/list][/]
[/list][size=3][u][i][1.00] - 2026-10-26[/i][/u][/size]
[list]
[]新增
[list]
[] 首个公开版本[/]
[/list][/]
[/list]

评论