跳到主要内容

resource（资源）

resource 是按实体存的一个数值：它的边界，以及显示方式。它不关心这个数从哪来、做什么用。把一个数值变成修炼资源的东西——境界链入口、自然恢复、灵气标记、修为换算、可用性门禁——全在 aura 里，由灵气定义通过 resource 字段指回这个数值。没有对应灵气定义的数值就是一个普通计数器。

文件位置​

数值文件放在数据包的 data/<namespace>/saturn/resource/。文件名对应它的 ID，例如 data/example/saturn/resource/qi.json 的 ID 是 example:qi。

字段​

字段类型默认说明
default_valueNumberProvider必填新建附件时的当前值。
minNumberProvider0数值下限。
maxNumberProvider必填数值上限。
icon图标引用无可选图标，画在灵气轮盘里这一条数值上。
particle_colorRGBColor#FFFFFF灵力射线使用的粒子颜色。写 #RRGGBB（整数或 [r,g,b] 浮点数组也接受），一律按不透明处理。
bars资源条数组[]内联资源条；为空时不显示该数值。

数值可以做这些事：作为消耗数组里的 saturn:resource 条目被扣掉（见共享数据类型 · Cost）、用 mxt:resource_compare 比较（判定"当前值 ≥ 你写的 min"，没有上界比较）、在公式里以 caster_<压平后的数值 id> 读取（见公式变量）、用 mxt:add_resource 行为增减、把该值所对应的灵气（aura 定义）存入物品。能进物品的是灵气：存取接口交换的是灵气身份，所以没有灵气定义的计数器存不进物品，但它照样能进玩家自己的池子，因为池子按值开键。

初始化和每次变更都重新求值 min 与 max。两个都是有限数、并且 min <= max，这次操作才写得进去；不成立就整个失败，不写入、也不退回默认值。变更量本身不是有限数同样不写入。

越界的变更被钳到边界，而不是被拒绝：钳制只改落下来的结果，不让这次操作失败。

max 可以写成公式：

// data/example/saturn/resource/qi.json
{
  "default_value": 0,
  "max": "100 + realm_rank * 20 + absorbed_aura * 0.1",
  "particle_color": "#66CCFF",
  "bars": [
    {
      "context": "mxt:self_hud",
      "anchor": "left",
      "order": 0,
      "renderer": {"type": "mxt:boss_bar", "bar_index": 1}
    }
  ]
}

公式里能用的境界变量（realm_rank、absorbed_aura、level）只在这条数值对应的灵气定义的链里存在。

需要按玩家条件选择不同的上限时用 mxt:conditional：按顺序检查分支，fallback 只能写数字或表达式字符串，在没有玩家或所有分支都不匹配时使用；不写 fallback 返回 0。

resource.bars​

bars 是 resource 的内联数组，不是独立的数据包注册表。

context 使用固有注册表 saturn:resource_bar_context 里的 ID。上下文对象从实体或客户端状态里提取当前值、最小值、最大值和最近变更时间，并用传入的资源 ID 生成显示名。内置五项固定，数据包只能选，不能自己加：mxt:self_hud、mxt:target_overlay、mxt:boss_overlay 读实体上存下来的数值，mxt:environment_concentration、mxt:actual_concentration 改读客户端同步过来的灵气池。两种浓度上下文分别是"只算环境模板"与"环境、库存、方块、阵法全都算上"；例如语言文件里 saturn.resource.example.qi 写的是「灵气」时，两条会分别显示成「环境灵气浓度」与「实际灵气浓度」。

字段类型默认说明
context上下文 idmxt:self_hud从哪取数：提取数值、生成名称并决定布局。
anchorleft / right必填落在自我 HUD 的左列还是右列。
orderInteger0同一列里越小越靠近原版热键栏。
visibility可见性对象mxt:always什么时候显示。
renderer绘制器对象必填怎么画。
value_displayEnumnone数值文本的显示方式：none、current、current_and_maximum、percentage。
maximumPositive Double上下文最大值只覆盖资源条的显示上限，不改变服务端或上下文的实际数值。

三个读取已存数值的上下文（mxt:self_hud、mxt:target_overlay、mxt:boss_overlay）在这条数值还没被初始化时不给值，那条资源条不画。maximum 不是有限正数时视同没写，照旧用上下文的最大值，加载期不报错。

两个浓度上下文要求这条数值有灵气定义：没有定义、或这个池子的最大值与当前值都不为正，就不给值，资源条也不画。它们报的最小值恒为 0，最近变更时间没有记录。

自我 HUD 的两列由玩家拖动，位置存在客户端配置里，数据包只决定这一条落进哪一列。

资源条走 NeoForge 的 GUI Layer，只画在左列或右列，不占屏幕中央。

绘制器​

绘制器族的全部类型、字段、默认值、范围与贴图写法见resource_bar_render_data_type（资源条绘制器）。

可见性​

字段类型默认说明
type显示条件 id必填用哪一种显示条件。
hold_ticksLong60只有 mxt:recently_changed 读：最近变过之后还显示多久，必须非负。
minDouble必填只有 mxt:resource_range 读：包含下界，必须有限。
maxDouble必填只有 mxt:resource_range 读：包含上界，必须有限且不低于 min。
values显示条件数组必填只有 mxt:and / mxt:or 读：嵌套条件。
value显示条件必填只有 mxt:not 读：要取反的那一条。

可见性只决定画不画，绝不改数值的结算。每种显示条件读哪些字段、有哪些边界见resource_bar_visibility_type（资源条显示条件）。

两套浓度

mxt:environment_concentration 与 mxt:actual_concentration 这两个 ID 同时存在于两处：写在 bars[].context 里是资源条上下文，按上面那段读客户端同步下来的灵气池；写在资源数值提供器里是另一个类型，要有实体才读得出来，没有实体就是 0，服务端从世界状态算。完整清单见resource_value_provider_type（资源数值来源）。

显示名

数据包定义不写 translation_key，显示名由标识符自动生成：<注册表命名空间>.<类别>.<定义命名空间>.<路径>。resource 的类别就是 resource，而这张注册表由前置库提供（saturn:resource），所以注册表命名空间是 saturn、键以 saturn. 开头：example:qi 查 saturn.resource.example.qi。路径里的 / 原样进键（example:foo/bar 得到 saturn.resource.example.foo/bar），按类别分子文件夹不会多出第二套翻译键规则。

resource 定义里没有可写的文本字段：名字与描述都按上面的规则从注册 id 现算（描述就是名字键再加 .description），要给这个数值配词就翻译那两个键。