📦 SIRIUS Ui 维基

适用 Minecraft 26.1.1 | 数据驱动型界面框架（版本 0.3.1）

SIRIUS Ui 是一款模组，允许您通过简洁的 JSON 配置与纹理资源自定义 Minecraft 的标题画面、游戏选择画面、暂停屏幕以及死亡屏幕。无需编写 Java 代码，即可轻松添加图像、按钮、背景以及动态布局。

总览

SIRIUS Ui 将硬编码的界面替换为基于 JSON 的动态渲染系统。资源包可覆写下列文件：

• assets/sirius_ui/screens/title_screen.json — 标题画面布局
• assets/sirius_ui/screens/game_selection_screen.json — 游戏选择画面布局
• assets/sirius_ui/screens/pause_screen.json — 暂停屏幕布局
• assets/sirius_ui/screens/death_screen.json — 死亡屏幕布局
• assets/sirius_ui/buttons/*.json — 按钮样式定义
• 任意 PNG 纹理文件

资源包结构

您的资源包必须遵循下述精确的文件夹层次：

📦 您的资源包/
└── 📁 assets/
    └── 📁 sirius_ui/
        ├── 📁 screens/
        │   ├── 📄 title_screen.json
        │   ├── 📄 game_selection_screen.json
        │   ├── 📄 pause_screen.json
        │   └── 📄 death_screen.json
        ├── 📁 buttons/
        │   ├── singleplayer.json
        │   ├── multiplayer.json
        │   └── ...
        └── 📁 textures/
            └── 📁 gui/
                ├── custom_logo.png
                ├── btn_normal.png
                └── ...
└── 📄 pack.mcmeta

pack.mcmeta 示例：

{
  "pack": {
    "pack_format": 26,
    "description": "SIRIUS Ui 自定义界面资源包"
  }
}

屏幕配置

每个屏幕 JSON 的根对象为 screen，其可包含以下字段：

• panorama — 背景配置（对象或字符串）
• graphicsDraw — 背景图层数组（可选）
• elements — 界面元素数组（必填）
• copyright — 版权文本对象（仅标题画面使用，可选）

背景（panorama）

支持三种形式：

• "panorama": "vanilla" — 原版动态全景背景
• "panorama": "none" — 纯黑背景
• "panorama": { "type": "image", "texture": "命名空间:路径/图片名" } — 自定义图像，会自动缩放并居中填充屏幕（保持宽高比，类似 CSS background-size: cover）。纹理路径示例："sirius_ui:textures/gui/background.png"。

背景图层（graphicsDraw）

graphicsDraw 是一个数组，每个元素定义一个彩色矩形，绘制于背景与常规元素之间。可用于制作遮罩、装饰线、半透明层等。每个矩形对象包含：

元素（elements）

elements 数组可包含以下三种类型的对象，每个对象必须包含 "type" 字段来区分类型。

🖼️ Logo 元素（type: "logo"）

用于显示静态图片（如 Mod 徽标、装饰图）。

🔘 Button 元素（type: "button"）

可交互按钮，支持不同状态纹理、文字、动作。

📝 Text 元素（type: "text"）

显示文本，支持静态本地化键、动态游戏数据、缩放、阴影、颜色自定义。

版权信息（copyright）

仅标题画面可使用，用于在屏幕底部显示版权文字。对象字段：

按钮样式（button style）

按钮样式文件（例如 buttons/default.json）必须包含顶层对象 button，其字段如下：

动作（action）

按钮的 action 字段是一个对象，包含 type 和特定参数。支持以下动作类型：

坐标系与表达式

原点

原点 (0,0) 位于屏幕左上角。X 轴向右递增，Y 轴向下递增。

元素锚点

position 字段定义的是元素的左上角，而非其中心。

正确的居中表达式：

"x": "(width - elementWidth)/2"
"y": "(height - elementHeight)/2"

表达式变量与运算

表达式支持以下变量：

• width — 当前屏幕宽度（缩放后的像素）
• height — 当前屏幕高度
• elementWidth — 元素自身的宽度（对于按钮，来自 size.width；对于文本，为渲染后的文本宽度，受 scale 影响）
• elementHeight — 元素自身的高度（同理）

支持运算符：+ - * / ( )，除法为整数截断。快捷写法：

• "center" → "(width - elementWidth)/2"（仅用于 x 坐标）
• "bottom-20" → "height - elementHeight - 20"（仅用于 y 坐标）

常用对齐公式

配置范例

以下是一个完整的死亡屏幕配置，展示了上述所有特性：

{
  "screen": {
    "panorama": "vanilla",
    "graphicsDraw": [
      { "x": "0", "y": "0", "width": "width", "height": "height", "color": "#88000000" },
      { "x": "width/2 - 140", "y": "height/2", "width": 280, "height": 1, "color": "#88FF0000" }
    ],
    "elements": [
      {
        "type": "text",
        "text_key": "deathScreen.title",
        "position": { "x": "center", "y": "height/5" },
        "color": "#FF0000",
        "scale": 2.5,
        "shadow": true
      },
      {
        "type": "text",
        "dynamicType": "death_cause",
        "position": { "x": "width/2 - 140", "y": "height/2 - 30" },
        "color": "#FFFFFF"
      },
      {
        "type": "text",
        "dynamicType": "score",
        "position": { "x": "width/2 + 140", "y": "height/2 - 30" },
        "color": "#FFFFAA"
      },
      {
        "type": "button",
        "text_key": "deathScreen.respawn",
        "style": "sirius_ui:buttons/death/button_re.json",
        "position": { "x": "width/2 - 130", "y": "height * 3 / 4" },
        "size": { "width": 120, "height": 20 },
        "action": { "type": "respawn" }
      },
      {
        "type": "button",
        "text_key": "deathScreen.titleScreen",
        "style": "sirius_ui:buttons/death/button_quit.json",
        "position": { "x": "width/2 + 10", "y": "height * 3 / 4" },
        "size": { "width": 120, "height": 20 },
        "action": { "type": "exit_to_title" }
      }
    ],
    "copyright": {
      "textKey": "auui.copyright",
      "position": { "x": "width - 10", "y": "height - 10" },
      "color": "#666666"
    }
  }
}

疑难排解