Creating GUI - HimxhMC/HimDSL GitHub Wiki

创建 GUI / Creating a GUI

GUI 是什么 / What a GUI Is

GUI 是虚拟物品栏界面——玩家点击某个按钮打开一个箱子界面，里面有一些图标，点击图标触发脚本逻辑。常用于商店、菜单、投票、领取奖励等。

A GUI is a virtual inventory UI — the player clicks something, a chest-like menu opens with icons, and clicking an icon triggers script logic. Common for shops, menus, votes, and rewards.

HimDSL 用 new GUI(行数, 标题) 创建：

HimDSL creates them with new GUI(rows, title):

var gui = new GUI(3, "主菜单");

  • 行数 —— 1 到 6 之间的整数，每行 9 格。

  • 标题 —— 显示在界面顶部的文字。

  • rows — an integer from 1 to 6; each row holds 9 slots.

  • title — the text shown at the top.

行数超出 1~6 会报错。3 行是最常见的尺寸，45 个格子够放大部分菜单。

Out-of-range rows error. Three rows is the most common size — 45 slots fits most menus.

打开与关闭 / Opening and Closing

用 gui.open(玩家) 让某个玩家打开界面：

Use gui.open(player) to open the GUI for a player:

var p = @p;
gui.open(p);

gui.close(p) 让界面关闭：

gui.close(p) closes it:

gui.close(p);

这两个操作都是延迟到下一 tick执行的。你会发现脚本调用 open 后，紧接着的代码里玩家还没打开界面——这是设计上的需要，避免在事件处理中直接操作界面造成的冲突。

Both operations are delayed to the next tick. Right after open, the player has not yet opened the GUI — a deliberate design avoiding conflicts when opening during event handling.

行列坐标 / Row-Column Coordinates

界面用 [行][列] 定位每个格子。行从 0 开始，列也是 0 开始。

Slots are addressed with [row][col]. Rows and columns both start at 0.

gui[0][0]      // 左上角
gui[0][8]      // 右上角
gui[2][4]      // 第 3 行第 5 列

gui[r] 返回这一行的列表（9 个槽位）。gui[r][c] 返回具体的槽位引用。

gui[r] returns the row as a list of 9 slots. gui[r][c] returns a specific slot reference.

放一个图标 / Placing an Icon

一个可用的 GUI 需要三步：创建槽位、放入格子、刷新。

A working GUI takes three steps: create slot, place it, refresh.

int main() {
    var gui = new GUI(1, "示例");
    var slot = new GUISlot(Material.DIAMOND);

    gui[0][4] = slot;           // 放入正中间
    gui.update(0, 4);           // 让这一格刷新

    var p = @p;
    gui.open(p);
}

gui[0][4] = slot 只是把 slot 登记到这一格。真正显示在玩家界面上，需要 update 或 updateAll 把数据写入 Bukkit 的物品栏。

gui[0][4] = slot only registers the slot. To show it, update or updateAll writes the data into the Bukkit inventory.

一次刷新所有格子 / Refreshing Everything

gui.update(r, c) 刷新一格；gui.updateAll() 刷新全部：

gui.update(r, c) refreshes one slot; gui.updateAll() refreshes all:

gui.updateAll();                // 简单、常用
gui.update(0, 4);               // 只刷新一格
gui.update(1, 0);               // 另一格

updateAll 是默认选择。它一次写好所有格子，代码简单，不容易漏。只有明确知道只改了一格且关心性能时才用 update——但真正需要优化的场景极少。

updateAll is the default. It writes every slot in one go, simple and complete. Reach for update only when you know one slot changed and care about performance — which is rare.

GUI 的字段 / GUI's Fields

gui 有两个只读字段：

gui has two read-only fields:

int r = gui.rows;               // 行数
string t = gui.title;           // 标题

只读——创建后不能改行数或标题。需要不同尺寸时，创建一个新的 GUI。

Read-only — rows and title cannot be changed after creation. Create a new GUI for a different layout.

一个简单的例子 / A Simple Example

一个显示"你好"的菜单：

A menu that says "hello":

int main() {
    var gui = new GUI(1, "问候");
    var slot = new GUISlot(Material.PAPER);
    slot.name = "§e你好";

    gui[0][4] = slot;
    gui.updateAll();

    var p = @p;
    gui.open(p);
}

§e 是 Minecraft 的颜色码，让文字显示为黄色。几乎所有显示文本的地方都支持颜色码：标题、槽位名、lore。

§e is a Minecraft color code for yellow. Almost every display text accepts color codes: titles, slot names, lore.

常见错误 / Common Mistakes

错误一：忘记刷新

gui[0][4] = slot;
gui.open(p);                    // ✗ 玩家看到空界面

open 不会自动刷新格子。先 updateAll 再 open。

错误二：行数写错

var gui = new GUI(7, "太大");    // ✗ 报错
var gui = new GUI(0, "太小");    // ✗ 报错

行数必须在 1~6 之间。

错误三：列越界

gui[0][9] = slot;               // ✗ 越界，列是 0~8

每行固定 9 格。

Mistake 1: Forgetting to refresh

open does not refresh slots. Call updateAll first.

Mistake 2: Wrong row count

Rows must be between 1 and 6.

Mistake 3: Out-of-range column

Columns are 0 to 8.

小结 / Summary

  • 创建：new GUI(行数, 标题)，行数 1~6。

  • 定位：gui[行][列]，从 0 开始，每行 9 格。

  • 打开：gui.open(玩家)；关闭：gui.close(玩家)。

  • 刷新：gui.updateAll() 或 gui.update(r, c)。

  • open 前必须先刷新。

  • 字段 gui.rows、gui.title 只读。

  • Create: new GUI(rows, title), rows 1–6.

  • Address: gui[row][col], 0-based, 9 per row.

  • Open: gui.open(player); close: gui.close(player).

  • Refresh: gui.updateAll() or gui.update(r, c).

  • Refresh before open.

  • Fields gui.rows, gui.title are read-only.

下一步 / Next Steps

下一章 [GUISlot 槽位 / GUISlot] 详细讲槽位能装什么、显示什么。

Next, [GUISlot 槽位 / GUISlot] covers what a slot holds and displays.