GUISlot 槽位 / GUISlot

槽位是什么 / What a Slot Is

GUI 里每个格子是一个槽位，用 new GUISlot(...) 创建。槽位决定这个格子显示什么（图标、名字、说明），以及点击时做什么（回调，下一章）。

Each cell in a GUI is a slot, created with new GUISlot(...). A slot decides what it shows (icon, name, lore) and what happens on click (callbacks, next chapter).

---

创建槽位 / Creating a Slot

两种写法：

Two forms:

var empty = new GUISlot();                  // 空槽位，图标是 AIR
var icon = new GUISlot(Material.DIAMOND);   // 用 Material 作为图标

也可以传入 ItemStack：

Or pass an ItemStack:

var item = new ItemStack(Material.DIAMOND, 5);
var slot = new GUISlot(item);

用 ItemStack 时，图标会带上数量、附魔、NBT 等完整信息。用 Material 时是普通物品。

With an ItemStack, the icon carries stack size, enchantments, NBT. With a Material, it is a plain item.

空槽位显示为空气（无图标），点击不响应。填充空槽位做装饰或占位是常见用法。

Empty slots show as air and ignore clicks. Using empties for spacing or decoration is common.

---

图标字段 / Icon Fields

槽位有两个相关的字段名：icon 和 item。它们等价——同一个底层值。

Slots have two related field names: icon and item. They are equivalent — the same underlying value.

slot.icon = Material.DIAMOND;
slot.item = Material.EMERALD;        // 等价写法

var m1 = slot.icon;
var m2 = slot.item;                  // 读到同一个值

推荐统一用 icon，语义更明确。

Prefer icon consistently — clearer semantics.

改图标之后要 update 才会生效——和槽位本身一样，不刷新看不到变化。

Changing the icon requires an update — like everything else, changes need a refresh.

---

name：显示名 / name: Display Name

name 是图标下方的文字（或者悬浮时显示）。支持颜色码：

name is the text shown on the icon. Color codes work:

slot.name = "§a钻石";
slot.name = "§c点击领取奖励";

不设置 name 时，显示 Bukkit 的默认名称（例如 "Diamond"、"Paper"）。

Without name, the default Bukkit name shows (e.g. "Diamond", "Paper").

name 是单个字符串，不是列表。多行文本请用 lore。

name is a single string, not a list. Use lore for multiple lines.

---

lore：说明文本 / lore: Description Lines

lore 是多行文本，显示在图标名字下方。用列表赋值：

lore is multiple lines shown below the name. Assign a list:

slot.lore = {
    "§7价格: §e100 金币",
    "§7点击购买"
};

每行一个字符串，从上到下显示。空字符串 "" 会显示为空行。

One string per line, top to bottom. Empty strings render as blank lines.

读取 lore 返回一个列表：

Reading lore returns a list:

var lines = slot.lore;
int count = lines.size();

不设置 lore 时，没有说明文本。

Without lore, there is no description.

动态修改 / Modifying Dynamically

lore 是整体赋值的。想改一行，先取出来、修改、再赋值回去：

lore is replaced as a whole. To edit one line, read, modify, reassign:

var lines = slot.lore;
lines.set(0, "§a新内容");
slot.lore = lines;

不能写 slot.lore[0] = "x"——那会修改一个临时列表，不会影响槽位。

Not slot.lore[0] = "x" — that mutates a temporary list, not the slot.

---

一个完整的例子 / A Complete Example

int main() {
    var gui = new GUI(1, "§6商店");

    // 中央放一个钻石
    var diamondSlot = new GUISlot(Material.DIAMOND);
    diamondSlot.name = "§b钻石";
    diamondSlot.lore = {
        "§7单价: §e50 金币",
        "§a点击购买"
    };
    gui[0][4] = diamondSlot;

    // 两侧放装饰用的玻璃
    var glass = new GUISlot(Material.GRAY_STAINED_GLASS_PANE);
    glass.name = " ";
    gui[0][0] = glass;
    gui[0][8] = glass;

    gui.updateAll();
    gui.open(@p);
}

glass.name = " " 是一个常见技巧：给装饰用的玻璃设置一个空格名，避免显示默认的 "Gray Stained Glass Pane"。

glass.name = " " is a common trick: give decorative glass a single-space name to hide the default "Gray Stained Glass Pane".

---

槽位的字段一览 / Slot Fields at a Glance

字段	类型	说明
icon 或 item	Material / ItemStack	图标
name	string	显示名
lore	list	说明文本
onLeftClick	lambda	左键回调（下一章）
onRightClick	lambda	右键回调（下一章）
onShiftLeftClick	lambda	Shift 左键回调
onShiftRightClick	lambda	Shift 右键回调

Field	Type	Meaning
icon or item	Material / ItemStack	the icon
name	string	display name
lore	list	description lines
onLeftClick	lambda	left-click callback (next chapter)
onRightClick	lambda	right-click callback
onShiftLeftClick	lambda	shift-left-click callback
onShiftRightClick	lambda	shift-right-click callback

---

常见错误 / Common Mistakes

错误一：直接修改 lore 的某一行

slot.lore[0] = "新内容";        // ✗ 无效

要用"读出-修改-写回"的模式。

错误二：忘记刷新

slot.name = "新名字";
gui.open(p);                    // ✗ 玩家看到旧名字

改任何槽位字段后都要 update / updateAll。

错误三：用 slot.name 拼多行

slot.name = "第一行\n第二行";     // ✗ 不会换行

Minecraft 的物品名不支持换行。用 lore。

Mistake 1: Editing a lore line in place

Read, modify, reassign.

Mistake 2: Forgetting to refresh

Change any slot field → update / updateAll.

Mistake 3: Multi-line name

Minecraft item names do not wrap. Use lore.

---

小结 / Summary

• 创建：new GUISlot(图标) 或 new GUISlot()。

• 图标：slot.icon = Material.XXX。

• 显示名：slot.name = "文本"，支持颜色码。

• 说明文本：slot.lore = {"行1", "行2"}。

• 修改后要 update / updateAll。

• name 单行，lore 多行。

• Create: new GUISlot(icon) or new GUISlot().

• Icon: slot.icon = Material.XXX.

• Name: slot.name = "text", color codes work.

• Lore: slot.lore = {"line1", "line2"}.

• Refresh after changes.

• name is one line; lore is many.

---

下一步 / Next Steps

下一章 [点击回调 / Click-Callbacks] 讲怎么让点击产生效果。

Next, [点击回调 / Click-Callbacks] shows how clicks trigger actions.

---