Guild
概述
Guild 让玩家创建公会、邀请他人、管理职级并共享银行。一切都可以通过 /guild 命令使用，你还可以添加一个在网页面板中构建的菜单，这样玩家就无需输入命令。公会有一位会长，以及任意数量的官员、成员和新人。
所有公会都存储在同一个 Guild Artifact 中，并保留在内存中以便快速读取。借助 MySQL 桥接和 Redis，每次更改都会广播到网络中的其他服务器；公会银行是数据库中单独的一行，因此两个服务器永远不会重复花掉同一笔金币。
菜单是一个 GUI 菜单。你设计它的布局和界面，把物品标记为公会按钮，扩展则会添加成员头像和邀请横幅。
功能
- 公会和角色 — 会长、官员、成员和新人，支持创建、邀请、踢出、晋升、转让和解散。
- 邀请 — 按名称邀请，通过
/guild join加入，也可以在菜单中通过搜索框接受或拒绝。 - 公会菜单 — 一个条目承载所有界面，带有成员头像、分页和标签页。
- 感知状态的按钮 — 不适用于该玩家的按钮（已在公会中时的创建、非会长时的解散）会从布局中移除。
- 公会银行 — 使用玩家的 NumericalStorage 余额存取，数据库行为原子操作。
- 跨服务器同步 — 创建、成员、角色、银行和移除都会同步到该组的每个服务器。
- 占位符 — 名称、角色、会长、规模、在线人数、银行、成员名称，以及按玩家查询。
- 管理命令 — 列出公会、查看某个公会，以及代表会长解散或踢出。
安装
- 安装负责绘制菜单的 GUI 扩展。
- 如果玩家需要使用银行，请安装 NumericalStorage 扩展。它提供存取款所使用的余额。
- 可选，适用于多个服务器：安装 MySQL 扩展，启用 Redis（或 Valkey），并在每个服务器上设置相同的
redis.group-id。公会银行同样需要 MySQL 扩展，参见公会银行。 - 将 Guild 的 JAR 放入
plugins/Typewriter/extensions/，然后重启服务器。 - 在一个 static 页面上创建一个 Guild Artifact 并发布。
guild.use 默认授予所有人，guild.admin 默认授予 OP。
快速上手
构建一个通过 /guild 打开的公会菜单：
- 在 TypeWriter 网页面板中，在一个 static 页面上添加一个 Guild Artifact。保持
artifactId为btc_guild_data。 - 添加一个 Guild Menu 条目。
/guild会打开找到的第一个 Guild Menu。 - 设置
inventoryTitle、inventoryRows和guiType，在layoutPool中构建布局并设置mainLayoutId。参见 GUI 指南。 - 在
views中声明你的界面（例如main、members、join）。将列出成员的界面 id 放入memberListViewIds，将列出待处理邀请的界面 id 放入joinListViewIds。 - 添加物品，并将
buttonType设为公会按钮：GUILD_MEMBERS和GUILD_BANK打开界面，GUILD_LEAVE和GUILD_DISBAND立即执行，PAGE_NAV用于在列表中翻页。 - 对于需要输入名称的按钮（创建、邀请、踢出、晋升、转让），请给物品设置一个
input对话框，其onInputCommands运行相应命令，例如guild create {input}。 - 发布并运行
/guild。
id 为 join 的界面就是 GUILD_JOIN 和 GUILD_PENDING_INVITES 所打开的界面。请把 join 添加到 views 和 joinListViewIds 中，并给它一个带有 input 对话框的物品，运行 guild joinsearch {input}，让玩家可以按公会名称过滤邀请。
工作原理
公会会在启动时加载到内存中。每次更改之后，公会会在后台保存到 artifact 并广播到其他服务器，由它们替换各自的副本。待处理的邀请只保存在内存中，不会被持久化。
菜单
Guild Menu 是一个 GUI 菜单，具有以下公会专属的行为。
内容面板。 在 memberListViewIds 所列出的界面上，每位成员是一个玩家头像，会长排在最前，并显示其角色和在线状态。如果你是会长，左键点击可晋升成员，右键点击则踢出成员。在 joinListViewIds 所列出的界面上，每个待处理的邀请是一面横幅：左键点击加入，右键点击拒绝。面板的位置由 contentX、contentY、contentColumns 和 contentRows 决定。
按钮。 这些 buttonType 值开箱即用：
buttonType | 点击 |
|---|---|
GUILD_MEMBERS | 打开 members 界面（guild open members）。 |
GUILD_BANK | 打开 bank 界面（guild open bank）。 |
GUILD_ALLIANCES, GUILD_WARS | 打开 allies 或 wars 界面（见下方说明）。 |
GUILD_LEAVE | 离开公会。 |
GUILD_DISBAND | 解散公会（仅限会长）。 |
GUILD_JOIN, GUILD_PENDING_INVITES | 切换到同一菜单的 join 视图。 |
NAV_BACK, NAV_CLOSE | 返回、关闭菜单。 |
PAGE_NAV | 左键向前，右键向后；名称会显示页码计数器。当一页就够用时会隐藏。 |
这些值不会附加任何动作。它们适用于你自己配置的物品（显示文本，或运行相应命令的 input 对话框）：GUILD_INFO、GUILD_MEMBER_MANAGE、GUILD_INVITE、GUILD_CREATE、GUILD_KICK、GUILD_PROMOTE、GUILD_DEMOTE、GUILD_TRANSFER、GUILD_ALLY_ADD、GUILD_ALLY_REMOVE、GUILD_WAR_DECLARE、GUILD_WAR_END、GUILD_BANK_DEPOSIT、GUILD_BANK_WITHDRAW、GUILD_ACCEPT_INVITE、GUILD_DECLINE_INVITE。
隐藏的按钮。 当物品不适用时，会从布局中移除：玩家已有公会时的 GUILD_CREATE 和 GUILD_JOIN；玩家不是会长或官员时的 GUILD_INVITE；没有公会时的 GUILD_LEAVE、GUILD_MEMBERS、GUILD_BANK、GUILD_ALLIANCES 和 GUILD_WARS；玩家不是会长时的 GUILD_DISBAND。
槽位命令。 物品可以运行 guild open [view]、guild page next|prev|<number>、guild create <name>、guild invite <name>、guild join <guild>、guild declineinvite <guild>、guild joinsearch <text>、guild leave、guild disband、guild kick <name>、guild promote <name> 和 guild transfer <name>。它们会以点击的玩家身份运行。
公会会存储盟友列表、敌人列表和等级，占位符也会提供它们，但此版本中没有任何命令或按钮可以更改它们：等级保持为 1，也没有降级命令。allies 和 wars 界面只有在你自己构建时才存在。
默认的菜单文本（标题 “Guilde”、头像 lore）是法语的，guild admin 的回复也是法语的。面向玩家的聊天消息是英语的。请在你的布局中覆盖菜单文本。
公会银行
银行作用于数据库表 btc_guild_bank 中的公会余额（该名称不遵循 table-prefix），该表会在 MySQL 数据库中自动创建。每个操作都是原子的，因此来自不同服务器的存取款不会使银行透支。
/guild deposit <amount>从玩家在 NumericalStorage 中的余额里扣除金币，并加入银行。任何成员都可以存款。/guild withdraw <amount>将金币从银行转给玩家。只有会长和官员可以取款。- 如果无法连接银行，存款会被退还，并告知玩家存储暂时不可用。
没有启用 MySQL 扩展，或没有 NumericalStorage 时，银行无法使用。
命令
所有命令都需要 guild.use。别名：/g、/guilde。不带参数的命令会打开第一个 Guild Menu，如果不存在则不输出任何内容。
| 命令 | 说明 |
|---|---|
/guild | 打开公会菜单。 |
/guild create <name> | 创建公会。名称必须为 3 到 16 个字母或数字。 |
/guild invite <player> | 邀请一位玩家（会长或官员）。 |
/guild join <guild> | 加入你受邀加入的公会。 |
/guild leave | 离开你的公会。仍有成员的会长必须先转让或解散。 |
/guild kick <player> | 踢出成员（会长，或官员踢非官员）。 |
/guild promote <player> | 将新人晋升为成员，将成员晋升为官员（仅限会长）。 |
/guild transfer <player> | 移交会长身份。原会长成为官员。 |
/guild deposit <amount> | 将金币存入公会银行。 |
/guild withdraw <amount> | 从银行取出金币（会长或官员）。 |
/guild info | 输出你公会的会长、成员数量、等级和银行余额。 |
/guild disband | 解散你的公会（仅限会长）。 |
/guild admin list | 列出所有公会（需要 guild.admin）。 |
/guild admin info <guild> | 显示某个公会。 |
/guild admin disband <guild> | 解散某个公会。其会长必须在线。 |
/guild admin kick <guild> <player> | 踢出某位成员。该公会的会长必须在线。 |
权限
| 权限 | 默认 | 授予 |
|---|---|---|
guild.use | 所有人 | 每个 /guild 命令。菜单点击会执行相同的动作，但不会检查它。 |
guild.admin | OP | /guild admin 命令。 |
占位符
用于 MiniMessage 文本的 MiniPlaceholders 标签，例如 <guild_name>。
| 占位符 | 返回值 |
|---|---|
<guild_in_guild> | 玩家在公会中时为 1，否则为 0。 |
<guild_name> | 公会名称，没有公会时为空。 |
<guild_role> | LEADER、OFFICER、MEMBER 或 RECRUIT。 |
<guild_leader> | 会长的名称。 |
<guild_size>, <guild_members> | 成员数量（两者返回相同的值）。 |
<guild_online_count> | 在本服务器上在线的成员数。 |
<guild_level> | 公会等级（目前始终为 1），没有公会时为 0。 |
<guild_bank> | 本服务器上存储的银行余额。 |
<guild_allies_count>, <guild_enemies_count> | 盟友和敌人的数量。 |
<guild_list> | 以逗号分隔的成员名称。 |
<guild_member_name:index> | 该位置的成员名称，从 0 开始。 |
<guild_of:name> | 指定名称玩家所在的公会，没有时为空。 |
条目
故障排查
重启后公会消失了。 没有发布 Guild Artifact，因此什么都没有被保存。请在 static 页面上添加它并发布。
/guild create 回复 “Guild name must be alphanumeric and between 3-16 characters.” 名称只接受字母和数字，不能有空格或下划线。
/guild 不输出任何内容。 没有 Guild Menu 条目。请创建并发布一个。诸如 /guild info 的子命令在没有它时也能使用。
存款失败并提示 “Insufficient funds”。 存款读取的是玩家的 NumericalStorage 余额。请安装 NumericalStorage，并检查玩家在那里是否有足够的金币。
“Guild bank storage is temporarily unavailable.” 无法连接银行表。请启用 MySQL 扩展（mysql.enabled: true），并在日志中检查数据库连接。存款会被退还。
在一个服务器上创建的公会在另一个服务器上缺失。 每个服务器都需要相同的 redis.group-id、唯一的 redis.server-name，以及 mysql.enabled: true，这样 artifact 才会被共享。没有 group-id 就不会广播任何内容。
成员头像或邀请横幅没有出现。 当前界面没有列在 memberListViewIds 或 joinListViewIds 中。当 views 为空时，菜单会使用 view：请将其设为 members 或 join。
相关扩展
- MySQL — Redis 消息传递以及公会银行背后的数据库。
- GUI — 公会菜单所使用的布局、视图和
input对话框。 - NumericalStorage — 银行所使用的玩家余额。
- Friend 和 Party — 其他社交系统。