JSON UI 入门指南

guide

简介

WARNING

JSON UI 已被标记为弃用，建议迁移至 Ore UI。请注意，所有使用 JSON UI 的附加包在未来几年内都将失效。与 JSON UI 不同，Ore UI 是硬编码实现的，无法通过资源包修改。

TIP

本页仅包含 JSON UI 基础概念。如需完整技术文档，请查阅 JSON UI 技术文档。

游戏用户界面采用数据驱动设计，支持自定义修改。通过 JSON UI 我们可以调整部分界面的渲染效果，甚至在一定程度上改变其交互行为。所有原版 UI 文件都存储在 RP/ui/... 目录中。

JSON UI 可能包含以下文件类型：

系统文件

这些是 JSON UI 的内置文件：

_global_variables.json - 用于声明默认变量供后续使用
_ui_defs.json - 用于引用 UI 使用的文件

界面屏幕

这些文件包含渲染特定界面所需的元素：

hud_screen.json - 显示主游戏界面，包含快捷栏等游戏元素
inventory_screen.json - 显示玩家物品栏界面
其他屏幕文件

模板文件

这些文件存储可被其他命名空间（如屏幕）复用的 UI 元素：

ui_common.json - 包含通用元素（如设置界面的按钮模板）
ui_template_*.json - 包含结构化组织的可复用元素

UI 定义文件

_ui_defs.json 以数组形式引用所有 JSON UI 文件。

例如新建 RP/ui/button.json 和 RP/my_ui/main_menu.json 后，需在定义文件中如下声明：

RP/ui/\_ui_defs.json

json

{
    "ui_defs": ["ui/button.json", "my_ui/main_menu.json"]
}

注意事项：

必须填写从资源包根目录开始的完整路径（包括 .json 扩展名）
只需声明新增的自定义文件，原版文件和其他第三方 JSON UI 会自动合并
支持在 RP/ui/... 目录外使用自定义路径
可使用非 .json 扩展名，只要文件内容符合 JSON 格式

全局变量

在 _global_variables.json 中定义变量 "$info_text_color" 并赋值为 [0.8, 0.8, 0.8]：

RP/ui/\_global_variables.json

json

{
    "$info_text_color": [0.8, 0.8, 0.8]
}

其他 UI 文件即可引用该变量：

vanilla/my_ui/file1.json

json

{
  "some_info": {
    ...
    "text": "你好",
    "color": "$info_text_color"
  }
}

vanilla/my_ui/file2.json

json

{
  "info": {
    ...
    "text": "信息",
    "color": "$info_text_color"
  }
}

注意事项：

可在文件中定义多个变量，用逗号分隔
这些变量是常量且单向传递，无法通过修改影响其他命名空间

命名空间

命名空间是 UI 文件的唯一标识符，用于跨文件访问元素。新建命名空间时必须确保名称唯一。

示例：在命名空间 one 中定义元素 foobar：

vanilla/ui/file_a.json

json

{
  "namespace": "one",

  "foobar": {...}
}

然后在命名空间 two 中引用该元素：

vanilla/ui/file_b.json

json

{
  "namespace": "two",

  "fizzbuzz@one.foobar": {...}
}

跨命名空间引用需遵循格式：

json

"[元素名]@[命名空间].[被引用元素名]"

界面屏幕

屏幕文件包含特定场景下调用的用户界面（如 inventory_screen.json 对应物品栏界面）。这些文件包含游戏直接访问的根元素。

屏幕的特殊性在于其数据只能被访问，不能被其他屏幕共享。

UI 元素

UI 元素是 JSON UI 的基本数据单元。同一命名空间内元素名称必须唯一以避免冲突。

示例：创建会显示"Hello World"文本的标签元素：

vanilla/ui/example_file.json

json

{
    "test_element": {
        "type": "label",
        "text": "Hello World"
    }
}

元素类型

type 属性支持的值包括：

label - 文本对象
image - 根据路径渲染图像
button - 可交互的点击元素
panel - 可重叠存放其他元素的容器
stack_panel - 非重叠排列元素的容器
grid - 以模板元素为基础生成行列布局
factory - 基于硬编码值和变量生成元素
custom - 需配合 renderer 属性使用
screen - 游戏直接调用的根面板元素

动画效果

使用 anim_type 替代 type 可创建动画元素，这些动画可被其他非动画元素引用。

vanilla/ui/example_file.json

json

{
  "namespace": "example_nm",

  "anim_size": {
    "anim_type": "size",
    "easing": "linear",
    "from": [ "100%", 27 ],
    "to": [ "100% + 3px", 30 ],
    "duration": 1.25
  },

  "anim_alpha": {
    "anim_type": "alpha",
    "easing": "linear",
    "from": 1,
    "to": 0.5,
    "duration": 2
  },

  "test_animated_element": {
    ...
    "anims": [
      "@example_nm.anim_size",
      "@example_nm.anim_alpha"
    ]
  }
}

动画类型

anim_type 支持的动画类型：

alpha - 透明度动画（浮点值）
offset - 位移动画（数组）
size - 尺寸动画 [宽, 高]
flip_book - 翻页动画（整数值）
uv - UV贴图动画
color - 颜色动画（0.0-1.0的RGB值）
wait - 等待动画
aseprite_flip_book - 精灵表动画（详见文档）
clip - 裁剪动画

运算符使用

JSON UI 支持在 size、offset 等属性中使用运算符，结合 $变量 和 #绑定。可用运算符包括：

运算符名称	符号	示例
加法	+	`"100% + 420px"` `($text + ' 我的')` `($index + 2)`
减法	-	`"100% - 69px"` `($text - ' 我的')` `($index - 13)`
乘法	*	`($var * 9)` `(#value * 5)`
除法	/	`($var / 12)` `(#value / 2)`
等于	=	`($var = 12)` `($var = '文本')` `(#name = '凋灵')`
大于	>	`(#value > 13)`
小于	<	`($var < 4)`
大于等于	>=	`(#value >= 2)`
小于等于	<=	`(#value <= 2)`
逻辑与	and	`($is_school and $is_open)`
逻辑或	or	`($is_cool or $is_awesome)`
逻辑非	not	`(not #name)` `(not (#name = 'text'))` `(not $name)`

变量系统

变量不仅限于 _global_variables.json 文件，可直接在各命名空间中使用以实现数据传递。

定义变量

使用 $ 前缀声明变量，支持整数、浮点数、布尔值、字符串和数组类型：

vanilla/ui/example_file.json

json

{
  "test_element": {
    ...
    // 定义变量
    "$array_var": [10, 10],
    "$string_var": "示例文本",
    "$float_var": 1.0,
    "$template_ref": "my_button.template_button",

    // 使用变量
    "size": "$array_var",
    "text": "$string_var",
    "alpha": "$float_var",

    // 变量引用子元素
    "controls": [
      { "child@$template_ref": {} }
    ]
  }
}

继承变量

变量可从其他元素继承并覆盖：

vanilla/ui/example_file.json

json

{
  "base_element": {
    ...
    "$cool_var": 1,
    "$rad_var": false
  },

  // 继承后修改部分变量
  "derived_element@base_element": {
    "$cool_var": 2  // $rad_var 保持不变
  }
}

注意：派生元素的属性会完全覆盖原元素。

数据绑定

绑定用于将硬编码值关联到元素。示例：通过绑定显示硬编码文本：

vanilla/ui/example_file.json

json

{
    "label": {
        "type": "label",
        "text": "#hardtext",
        "bindings": [
            {
                "binding_name": "#hardtext"
            }
        ]
    }
}

或使用绑定名覆盖：

vanilla/ui/example_file.json

json

{
    "label": {
        "type": "label",
        "text": "#display_text",
        "bindings": [
            {
                "binding_name": "#hardtext",
                "binding_name_override": "#display_text"
            }
        ]
    }
}

绑定类型

绑定支持多种交互场景，例如根据开关状态显示面板：

json

{
  "panel": {
    ...
    "bindings": [
      {
        "binding_type": "view",
        "source_control_name": "my_toggle", // 源元素名
        "source_property_name": "#toggle_state", // 获取开关状态
        "target_property_name": "#visible" // 控制显隐
      }
    ]
  }
}

当开关激活时，#toggle_state 为 true，面板即显示。

条件渲染

通过变量和绑定可以实现精细的条件渲染控制，分为变量条件渲染和绑定条件渲染两种方式。

变量条件渲染

示例：当动作栏文本不是"hello world"时显示：

vanilla/ui/hud_screen.json

json

{
    "hud_actionbar_text/actionbar_message": {
        "$atext": "$actionbar_text",
        "visible": "(not ($atext = 'hello world'))"
    }
}

执行 /title @s actionbar hello world 时消息将隐藏。

绑定条件渲染

示例：当标题文本不是"hello world"时显示：

RP/ui/hud_screen.json

json

{
    "hud_title_text/title_frame/title": {
        "modifications": [
            {
                "array_name": "bindings",
                "operation": "insert_back",
                "value": {
                    "binding_type": "view",
                    "source_property_name": "(not (#text = 'hello world'))",
                    "target_property_name": "#visible"
                }
            }
        ]
    }
}

字符串格式化

JSON UI 支持多种字符串格式化操作符，假设有变量 "$var": "abcdefghijklmn"：

'%.7s' → 取前7字符 → abcdefg
'%04s' → 长度≥4时返回原串 → abcdefghijklmn
'%7.4s' → 取4字符并左填充空格 → abcd
'%-7.4s' → 取4字符并右填充空格 → abcd
'%15s' → 长度≤15时左填充空格 → abcdefghijklmn
'%-15s' → 长度≤15时右填充空格 → abcdefghijklmn

按钮映射

button_mappings 可重定义不同输入设备（键鼠/触摸/手柄）的控件映射：

json

{
    "sample_button@common.button": {
        "$button_id": "button_id",
        "button_mappings": [
            {
                "to_button_id": "$button_id",
                "mapping_type": "pressed"
            },
            {
                "from_button_id": "button.menu_ok",
                "to_button_id": "$button_id",
                "mapping_type": "focused"
            }
        ]
    }
}

映射类型

focused - 鼠标悬停时触发
pressed - 点击/按压时触发
global - 元素存在时全局触发

常用按钮ID

键鼠：

按钮ID	对应输入
`button.menu_select`	鼠标左键
`button.menu_secondary_select`	鼠标右键
`button.menu_ok`	回车键

手柄：

按钮ID	对应输入
`button.controller_select`	X/A键
`button.menu_secondary_select`	Y键

非侵入式修改

使用 modifications 属性可最小化修改原版 UI，提升兼容性：

操作类型	描述
`insert_front`	数组头部插入
`insert_back`	数组尾部追加
`replace`	替换目标元素
`remove`	删除目标元素

修改示例

在控件列表头部插入新元素：

json

{
    "array_name": "controls",
    "operation": "insert_front",
    "value": [
        {
            "new_element@namespace.template": {}
        }
    ]
}

替换指定绑定：

json

{
    "array_name": "bindings",
    "operation": "replace",
    "where": {
        "binding_name": "#old_binding"
    },
    "value": {
        "binding_name": "#new_binding"
    }
}