快速上手

从零开始，5 分钟内在 Behemiron 中运行你的第一个 UI 面板。

前置条件

• Minecraft Forge 开发环境（JDK 17+）
• Behemiron 引擎已安装（服务端 + 客户端）
• 基本的 Kotlin / Java 开发经验

1. 项目结构

Behemiron 插件的典型目录结构：

plugins/Behemiron/
├── ui/                    # BUIServerAPI 模板文件
│   └── my-panel.xml
├── sound/                 # 音效文件
├── hotkeys/               # 热键配置
│   └── gameplay.yml
└── config.yml             # 主配置

2. Hello World — 第一个 UI

创建 plugins/Behemiron/ui/hello.xml：

<template>
  <Panel class="panel">
    <Label text="Hello, Behemiron!" />
    <Button @click="onClose">关闭</Button>
  </Panel>
</template>

<script>
function onClose() {
  closeUI()
}
</script>

<style>
.panel {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 10;
  width: 240;
  height: 140;
  padding: 20;
  background: bss-sdf(8, #1e1e2e, #313244, 1);
}
</style>

在服务端通过命令打开：

/behemiron ui open <player> hello

3. 添加响应式数据

让面板展示来自服务端的玩家数据：

<template>
  <Panel class="panel">
    <Label :text="'等级: ' + internalSyncStore.get('sync:level')" />
    <ProgressBar id="hpBar" class="hp" />
    <Button @click="onClose">关闭</Button>
  </Panel>
</template>

<script>
onMounted(() => {
  const bar = document.getElementById("hpBar")
  const hp = internalSyncStore.get("sync:hp") || 20
  const maxHp = internalSyncStore.get("sync:maxHp") || 20
  bar.setRange(0, maxHp)
  bar.setProgress(hp)
})

function onClose() {
  closeUI()
}
</script>

<style>
.panel {
  display: flex;
  flex-direction: column;
  gap: 8;
  width: 260;
  height: 160;
  padding: 16;
  background: bss-sdf(8, #1e1e2e, #313244, 1);
}
.hp {
  width: 100%;
  height: 16;
}
</style>

4. 添加音效反馈

<Button @click="onConfirm">确认</Button>

function onConfirm() {
  Sound.play("ui/confirm")
  closeUI()
}

音效路径规则

音效 ID 必须是 sound/ 目录下的相对路径，禁止带 behemiron: 或 sound/ 前缀。 正确写法：ui/confirm，错误写法：sound/ui/confirm。

5. 添加热键

在 plugins/Behemiron/hotkeys/gameplay.yml 中配置服务端热键：

bindings:
  open_panel:
    context: gameplay
    pattern: "H"
    trigger: press
    cooldownMs: 500
    action: |-
      behemiron ui open hello

在 UI 脚本中注册客户端热键：

onMounted(() => {
  Hotkeys.register({
    pattern: "ESCAPE",
    trigger: "press"
  }, () => {
    closeUI()
  })
})

下一步

方向	链接
深入 UI 系统	UI 系统总览
学习 IoC 容器	IoC 容器
进入 UI 二开路线	BUIServerAPI 二开路线
探索特效系统	特效系统
查阅 API 参考	参考索引