聚落 ShiroGomaSettlement
白芝麻服轻量聚落管理插件使用说明 —— 创建聚落、领袖/副领袖权限、前缀、传送点、GUI 列表、PlaceholderAPI 变量
简介
ShiroGomaSettlement 是白芝麻服的轻量聚落（阵营）管理插件。管理员或玩家可以创建聚落，设定领袖与副领袖，邀请成员加入，设置 1 字符的聚落前缀（用于聊天前缀 / TAB 列表），为聚落挂一个传送点，通过 GUI 查看和传送。所有数据独立持久化，完全不依赖领地系统。
- 玩家侧：加入聚落、查看聚落信息、传送回聚落、查看聚落列表
- 聚落长 / 副领袖：改名、改前缀、改传送点、设置副领袖、踢出成员
- 管理侧：创建 / 删除聚落、转移领袖、任意聚落改名 / 改传送点 / 踢人 / 设副领袖
- 输出：PlaceholderAPI 变量，用于聊天前缀、TAB 列表、头顶名等场景
本插件为 Bukkit / Spigot / Paper 系插件（api-version 1.16），在 Youer 这类 NeoForge + Bukkit 混合端上运行于 Bukkit 侧。软依赖 PlaceholderAPI。
安装
- 将
ShiroGomaSettlement-version.jar放入服务端plugins/文件夹 - 重启服务器
- 首次启动会自动创建
plugins/ShiroGomaSettlement/config.yml与settlements.yml
聚落结构
每个聚落由以下字段组成：
| 字段 | 说明 |
|---|---|
id | 自动生成的 UUID（内部主键，命令也能用） |
name | 聚落显示名（全局唯一） |
prefix | 1 字符前缀（含 & 颜色代码后过滤到纯文本不超过 1 个字符；可留空） |
leader | 领袖 UUID（聚落创建者自动成为领袖） |
vice-leaders | 副领袖 UUID 集合（可 0 人、多人） |
members | 普通成员 UUID 集合 |
spawn | 传送点坐标 + 世界名（可选；未设置时 /settlement warp 会提示） |
权限层级：管理员 (shirogoma.admin) > 领袖 > 副领袖 > 普通成员 > 无成员。子命令会按此约束可用范围。
玩家使用
| 操作 | 命令 |
|---|---|
| 打开聚落列表 | /settlement list（GUI：左键传送 / 右键详情） |
| 查看聚落详情 | `/settlement info [名称 |
| 传送到自己的聚落 | /settlement warp 或指定聚落 /settlement warp <名称> |
| 离开聚落 | /settlement leave（保留聚落，直到无成员再清理） |
/settlement warp 必须该聚落已设置传送点，否则会提示「该聚落未设置传送点」。成员可以传送到本聚落传送点，但不能传送到其他聚落（管理员例外）。
聚落管理命令
权限节点（来自 plugin.yml）：
| 节点 | 默认 | 作用 |
|---|---|---|
shirogoma.admin | OP | 任意操作（创建 / 删除 / 转移领袖 / 任意聚落改名改传送点改前缀踢人设副领袖） |
shirogoma.member | 所有玩家 | 基础成员权限（查看 / 传送自己的聚落 / 离开 / 加入） |
子命令 + 权限矩阵（admin 全能覆盖）：
| 命令 | 成员 | 副领袖 | 领袖 | admin | 说明 |
|---|---|---|---|---|---|
/settlement create <名称> | ✅ | 创建聚落，创建者自动成领袖；名称全局唯一 | |||
/settlement delete <名称|ID> | ✅ | 删除聚落，数据从 settlements.yml 移除 | |||
/settlement info [名称|ID] | ✅ | ✅ | ✅ | ✅ | 查看聚落详情 |
/settlement list | ✅ | ✅ | ✅ | ✅ | 打开聚落列表 GUI |
/settlement invite <玩家> [聚落] | ✅ | ✅ | ✅ | 邀请玩家加入；玩家必须在线（管理员可指定任意聚落） | |
/settlement leave | ✅ | ✅ | ✅ | ✅ | 离开当前聚落 |
/settlement setleader <玩家> [聚落] | ✅ | 转移领袖；目标必须已是该聚落成员 | |||
/settlement setname <新名称> [聚落] | ✅ | ✅ | 改名；领袖改自己的，admin 改任意的；名称全局唯一 | ||
/settlement setprefix [前缀] [聚落] | ✅ | ✅ | 设置或清除 1 字符前缀；过滤颜色代码后纯文本 ≤ 1 字符 | ||
/settlement setviceleader <玩家> [聚落] | ✅ | ✅ | 切换副领袖身份（toggle）；不能设领袖自己 | ||
/settlement kick <玩家> [聚落] | ✅ | ✅ | ✅ | 踢出成员（不能踢领袖）；踢到副领袖先撤副领袖身份 | |
/settlement setwarp [聚落] | ✅ | ✅ | ✅ | 把传送点设在你当前位置；admin 可指定任意聚落 | |
/settlement delwarp [聚落] | ✅ | ✅ | ✅ | 清除传送点 | |
/settlement warp [名称] | ✅ | ✅ | ✅ | ✅ | 传送到聚落传送点 |
前缀的「1 字符」限制是过滤 &X / §X 颜色代码之后的纯文本长度，所以可以写 &6白（过滤后只剩「白」，刚好 1 字），不能写 白芝麻（过滤后 3 字）。留空表示清除前缀。
GUI 列表
/settlement list 会打开一个聚落列表界面：
- 左键 某格 → 传送到该聚落的传送点（必须已设置传送点，否则提示）
- 右键 某格 → 打开聚落详情，列出领袖、副领袖、成员数、前缀
GUI 的每格图标由代码根据聚落动态生成（领袖 / 副领袖 / 普通成员身份会显示不同标识）。
PlaceholderAPI 变量
需要安装 PlaceholderAPI。扩展标识符为 settlement（不是 shirogoma）。
| 变量 | 输出 |
|---|---|
%settlement_prefix% | 按 prefix-format 包裹的带颜色前缀；无前缀时为空 |
%settlement_prefix_raw% | 过滤颜色代码后的纯文本前缀 |
%settlement_prefix_raw_full% | 按 prefix-format-raw 包裹的纯文本前缀 |
%settlement_name% | 聚落名称 |
%settlement_title% | 同 %settlement_prefix%，兼容旧版变量名（按 title-format 包裹） |
配置（config.yml）
# %settlement_prefix% 的包裹格式，{prefix} 被替换为带颜色前缀
prefix-format: "&7[{prefix}&7]"
# %settlement_prefix_raw_full% 的包裹格式（纯文本）
prefix-format-raw: "[{prefix}]"
# %settlement_title% 的包裹格式（兼容旧变量）
title-format: "&7[{prefix}&7]"{prefix}替换为带颜色的前缀（&6白这种，不会被过滤）- 没前缀时
%settlement_prefix%/%settlement_title%/%settlement_prefix_raw_full%都会返回空串，不会输出[] - 变量的颜色代码（
&）由调用方（聊天 / TAB / 头顶）自行解析
数据存储
plugins/ShiroGomaSettlement/settlements.yml— 聚落列表（领袖 UUID、副领袖列表、成员列表、名称、前缀、传送点坐标 + 世界名）- 每次
create/delete/ 改名 / 前缀 / 传送点 / 成员变更后自动保存
插件没有显式 reload 子命令（plugin.yml 里也没声明），改完数据直接重启服务器即可。
常见问题
Q：创建聚落为什么提示「没有权限」？
创建聚落只给了 shirogoma.admin（OP）；普通玩家不能创建，只能被邀请加入，或者由管理员先建个空聚落再拉人。
Q：前缀设成 &7白芝麻 被拒了？
过滤颜色代码后变成 3 个字符了（「白芝麻」），超过 1 字上限。试试 &7白 或 &7[S] 这种。
Q：成员能看到但不能传送？
检查该聚落有没有通过 /settlement setwarp 设传送点；没设时所有成员都传不进去。
Q：领袖能被踢吗？
不能。要让领袖出局，必须先让管理员 /settlement setleader <新领袖> <聚落> 转移，再由新领袖踢旧领袖。
Q：为什么我看不到任何 PlaceholderAPI 变量？
检查三件事：① 服务端是否加载了 PlaceholderAPI；② 玩家是否已加入聚落（没加入时所有 settlement_* 变量返回空串）；③ 聊天格式 / TAB 列表插件是否配置了 %settlement_prefix%。
Q：admin 能否改任意聚落？
可以。shirogoma.admin 覆盖所有权限检查，/settlement setname <新名> <聚落> 这种命令第三个参数指定任意聚落 ID / 名称即可。
Q：改名时 setleader / setviceleader / kick / invite 命令的 <玩家> 参数支持离线玩家吗？
支持。内部 resolvePlayer 先查在线，查不到就遍历 Bukkit.getOfflinePlayers()，离线玩家也能设为领袖或踢出。但被邀请加入时玩家必须在线（/settlement invite）。