[MD]
# SmallWorld 小世界插件
一个为 **Paper 26.1.2** 生存/轻 RPG 服务器设计的小世界插件。
服主可以为玩家创造**专属小世界**（相当于新增一个维度），玩家通过**一次性令牌**进入；
令牌可以交易/转交给任何人，**访客**进入主人的小世界后，对里面的内容**没有任何操作权限**（不能破坏/放置方块、不能开箱子、不能击杀怪物等），属于纯观光。
## 功能一览
| 功能 | 说明 |
| --- | --- |
| 专属小世界 | 每个玩家拥有一个独立世界，世界文件夹 `sw_<玩家UUID>`，按需懒加载 |
| 一次性令牌 | 右键令牌进入对应小世界，使用后立即消失；令牌是普通物品，可自由交易/转交 |
| 访客保护 | 非主人进入小世界后：不能破坏/放置方块、开箱子等容器、击杀怪物、拾取/丢弃物品、与实体交互 |
| 主人权限 | 小世界主人对自己的世界拥有完整权限 |
| 虚空世界 | 默认虚空生成器（含出生平台），最省服务器资源；也可配置为正常地形 |
| 世界保护 | 可防止 TNT/苦力怕爆炸、火焰蔓延、末影人搬方块等破坏小世界 |
| Multiverse 集成 | 小世界自动注册进 Multiverse 并设置别名"xxx的小世界"，`%multiverse_alias%` 正常显示，不再刷 "World not found" 警告 |
## 安装
1. 将 `SmallWorld-1.0.0.jar` 放入服务器的 `plugins/` 文件夹。
2. 重启服务器（或使用 PlugMan 类插件热加载）。
3. 服务器会生成 `plugins/SmallWorld/config.yml`，可按需修改。
> 要求：Paper 26.1.x 服务端（需 Java 25 运行环境）。
> 可选前置（软依赖，不装也完全可用）：`PlaceholderAPI`、`Multiverse-Core`。
## 与 Multiverse / PlaceholderAPI 联动
小世界由本插件直接创建，Multiverse 原本不认识它们，导致 `%multiverse_alias%` 解析失败并刷
`[PlaceholderAPI] [multiverse-core] Multiverse World not found: sw_xxx` 警告。本插件已做自动集成：
- 创建/加载小世界时自动导入 Multiverse（写入 `worlds.yml`），并设置别名（默认 `xxx的小世界`，见 `settings.world-alias`）。
- 重启后 Multiverse 自动恢复小世界，别名持久生效，警告消失。
- 兼容 Multiverse-Core 5.7.x（`org.mvplugins.multiverse` 新版 API），使用反射集成，Multiverse 版本变化不影响核心功能。
聊天格式里可用的占位符：
| 占位符 | 说明 |
| --- | --- |
| `%multiverse_alias%` | 在小世界显示 "xxx的小世界"，在其他世界显示该世界的 Multiverse 别名 |
| `%smallworld_alias%` | 本插件自带的占位符，仅在小世界时显示 "xxx的小世界"，其他世界为空 |
> 注意：如果你在聊天插件里写的是 `%multiverse-core_alias%`，请改为 `%multiverse_alias%`
> （PlaceholderAPI 的标识符是 `multiverse`，不带 `-core`，原写法不会被解析而会显示原文）。
> 如果 `%multiverse_alias%` 在你的聊天插件里仍异常，可以改用 `%smallworld_alias%`。
## 命令
### 管理员命令（需要 `smallworld.admin` 权限，默认 OP）
| 命令 | 说明 |
| --- | --- |
| `/sw create <玩家>` | 为玩家创建小世界（玩家在线或曾登录过） |
| `/sw token <主人> [数量]` | 给自己发放指定主人小世界的令牌 |
| `/sw give <主人> <玩家> [数量]` | 把令牌直接发给指定玩家 |
| `/sw tp <主人>` | 传送到某个小世界 |
| `/sw list` | 列出所有小世界及在线人数 |
| `/sw delete <主人>` | 删除小世界（不可恢复，会先传送走里面的玩家） |
### 玩家命令（`smallworld.use` 权限，默认所有玩家）
| 命令 | 说明 |
| --- | --- |
| `/sw leave` | 离开当前小世界，返回主城 |
| `/sw home` | 进入自己的小世界（无需令牌） |
### 权限节点
| 权限 | 默认 | 说明 |
| --- | --- | --- |
| `smallworld.admin` | OP | 管理命令 |
| `smallworld.use` | 所有玩家 | 使用令牌 / 离开 / 回家 |
| `smallworld.bypass` | OP | 绕过访客限制，可自由操作任意小世界内容 |
## 使用流程示例
```
1. 服主: /sw create Steve → 为 Steve 创建小世界
2. 服主: /sw give Steve Alice 1 → 给 Alice 一张 Steve 小世界的令牌
3. Alice: 右键令牌 → 传入 Steve 的小世界, 令牌消失
4. Alice: 试图破坏方块/开箱子/打怪 → 全部被拒绝 (提示无权限)
5. Alice: /sw leave → 返回主城
6. 想要再进, 需要另一张令牌
```
## 配置说明 (`config.yml`)
```yaml
world:
environment: NORMAL # NORMAL / NETHER / THE_END
generator: void # void=虚空(推荐) / normal=正常地形
seed: "" # 世界种子, 留空随机
protect-explosions: true # 防止爆炸破坏小世界
protect-environment: true # 防止火烧/蔓延/末影人搬方块等环境破坏
token:
material: GOLD_NUGGET # 令牌物品材质
name: "&6&l小世界令牌 &7(%owner%)" # 名称, %owner%=主人名字
lore: [...] # 描述, 支持 & 颜色代码
glow: true # 附魔发光效果
settings:
world-prefix: "sw_" # 世界文件夹前缀, 一般不要改
main-world: "" # 离开小世界返回的主城世界名, 留空=服务器默认世界
load-on-startup: false # 启动时是否预加载所有小世界(推荐 false, 按需加载)
world-alias: "%owner%的小世界" # 小世界在 Multiverse 的别名, %owner%=主人名字
```
## 技术说明
- 小世界使用 Bukkit `WorldCreator` 创建，属于独立维度；Paper 1.21+ 将自定义世界存储在
`world/dimensions/minecraft/sw_xxx/` 下，插件已兼容该布局（列表/删除/查找均支持）。
- 令牌通过 `PersistentDataContainer` 记录主人 UUID，`/sw delete` 后旧令牌将无法再使用。
- 访客保护通过事件监听实现：方块破坏/放置、容器与交互方块右键、实体伤害、物品拾取/丢弃、
爆炸与环境变化等均在保护范围内；主人与 `smallworld.bypass` 玩家不受限。
## 构建（开发者）
要求 JDK 25 与 Maven 3.9+：
```bash
mvn clean package
# 产物: target/SmallWorld-1.0.0.jar
```
依赖：`io.papermc.paper:paper-api:26.1.2.build.74-stable`（provided）。
[/MD]
