- 版权类型
- 二次开发
- 插件中文名称
- 星球
- 插件英文名称
- Planetoids
- 支持的核心（服务端）
- Paper
- Folia
- Purpur
- Leaves
- 语言支持
- 多语言
- 适配版本（Java）
- 最新版本
- 26.x
- 1.21
Planetoids｜把你的世界变成一片漂浮的星球
【一句话简介】
把整个世界变成星空：无数由「外壳 + 核心」组成的漂浮星球，按行星系统确定性生成，材质与密度全部可调，支持 Paper 1.21 ~ 26.3。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
【这是什么】
Planetoids 原本是 2012 年的 Bukkit 老插件（作者 Canisaur，最后更新于 Bukkit 1.4.6）。本版是它的
Paper 现代化移植：重写了区块生成、存档格式与线程模型，只保留原版的玩法与手感。
没有前置插件，没有 NMS，单个 jar 约 48 KB。
【世界长什么样】
· 世界里没有地面，只有悬浮的星球；星球之间是虚空
· 每颗星球 = 一层外壳（石头／冰／雪／玻璃／羊毛／树叶……）+ 一个内核（岩浆／水／各种矿石／原木／南瓜……）
· 出生点上方有一颗固定的「树叶包原木」星球作为落脚点，往上一跳就能站稳
· 世界按「行星系统」划分，默认 50 区块 = 800×800 格 一个系统，系统内星球互不重叠
· 全天空只有一种生物群系，可选 NORMAL（正常天空）或 END（黑色星空）
【功能特性】
· 权重化材质表：外壳和内核各自一份列表，每一项都能写权重，随机结果符合直觉
· 材质支持方块状态（例如 oak_log[axis=y]），也兼容 1.4 时代的旧写法（WOOL-0.4-6 会自动转成粉色羊毛）
· 星球数量 / 半径 / 外壳厚度 / 最小间距 / 出生点高度 / 系统大小 全部可配置
· 可选在 y=-64 铺一层平台（floor-height），适合做可跑图的地面世界
· 永久夜晚、关闭天气、禁止怪物/动物生成，均为配置开关
· /pltp 一键在星球世界与主世界之间往返
· 行星系统会落盘缓存，重启、换插件版本都不会让已有世界"变脸"
【支持版本】
· Paper：1.21 ~ 26.3（api-version 1.21，向下兼容整段区间）
· Java：服务端需 Java 21（26.x 服务端需 Java 25）
· Folia：插件可正常加载、配置、注册命令、干净卸载，生成器也按 Folia 的线程模型编写
（不使用 BukkitScheduler，跨世界传送走 teleportAsync，区块生成无共享可变状态）
注意：Folia 本身禁止插件创建世界（Server#createWorld 直接抛异常），所以自动建世界这一项在 Folia 上不可用。
想要开箱即用，建议用 Paper。
· 实测环境：Paper 1.21.4-232、Paper 26.3-229 均通过（建世界、生成区块、落盘存档）
【安装】
1. 把 Planetoids-1.0.0.jar 放进服务器的 plugins 目录
2. 重启服务器（本插件需要在启动阶段接管生成器，/reload 无效）
3. 首次启动会自动创建名为 Planetoids 的世界，并在 plugins/Planetoids/ 生成 config.yml
4. 进服后输入 /pltp 传送过去，再输入一次回到主世界
5. 首次创建世界会预生成出生点周围约 441 个区块（约 10 秒），期间控制台可能出现一次
"server has not responded for 10 seconds" 的线程转储提示，那是 Paper 的看门狗，属正常现象
【命令与权限】
命令 说明
/pltp 在星球世界与主世界之间往返（别名 /planetoidstp）
权限 planetoids.pltp（默认所有人可用）
【配置速查】
配置文件：plugins/Planetoids/config.yml（带中文注释，改完需重启）
planetoids:
autocreateworld: true # 启动时自动创建世界
worldname: Planetoids # 世界名（也是存档文件夹名）
seed: 0 # 0 = 随机
environment: NORMAL # NORMAL / END（END 为黑色星空）
alwaysnight: false # 永久夜晚
weather: false # 关闭下雨/雷暴
disablemonsters: true # 禁止怪物
disableanimals: false # 禁止动物
system-size: 50 # 行星系统边长（区块）
spawn-y: 77 # 出生点高度
planets:
density: 750 # 每个系统尝试生成多少颗（撞车就丢弃）
min-size: 4 # 半径范围
max-size: 20
min-distance: 10 # 星球之间的最小间隙
min-shell-size: 3 # 外壳厚度范围
max-shell-size: 5
floor-block: GRASS_BLOCK
floor-height: 0 # >0 时在底部铺一层平台
bedrock: false # 平台最底层换基岩
blocks:
shells: [ stone-1.0, ice-0.9, oak_leaves-0.9, ... ]
cores: [ lava-0.8, water-1.0, diamond_ore-0.4, ... ]
方块写法： <材质>[-<权重 0~1>[-<旧版数据值>]]
stone-1.0 权重 1.0，抽到即使用
ice-0.9 九成概率被接受，否则重抽
minecraft:oak_log[axis=y]-0.5 支持方块状态，权重写在最后
WOOL-0.4-6 旧版写法，data 6 自动转为 pink_wool
调参小抄：
· 更密更热闹 → density 调到 1500、min-distance 调到 6
· 空岛/跑酷风 → density 200、max-size 8
· 有大星球 → max-size 35、min-shell-size 4
· 想有地面 → floor-height: 5、bedrock: true
【想重新开一个世界】
· 只换种子：停服 → 删掉世界文件夹 Planetoids/ 与 plugins/Planetoids/systems/Planetoids/ → 启动
· 只让"没去过的地方"用新配置：停服 → 删对应的 system_x_z.pgd → 启动（已生成的区块仍是旧方块，交界有接缝）
· 干净重来（推荐）：把 worldname 改成新名字，或删世界文件夹 + 系统存档
【性能与预生成】
· view-distance 6~8 足够，星球之间没有地形细节，看太远只会白消耗性能
· 大服务器建议先用 Chunky 之类工具预生成常驻区域
· 【注意】星球之间是虚空，掉下去会摔死，建议开 keepInventory 或让玩家用 /pltp
【常见问题】
Q：改了配置但世界没变化？
A：配置在插件启用时读取一次，改完必须重启；而且已生成的行星系统和已生成的区块都不会被改写，见上面「想重新开一个世界」。
Q：控制台提示 Unknown block 'xxx', entry skipped？
A：配置里写了当前服务端版本不存在的方块。插件会跳过它并给出警告，不会崩服。
Q：Folia 上提示世界无法创建？
A：Folia 不支持插件创建世界，属服务端限制。可在其他环境准备好世界后让其存在，插件会自动接管；
或直接使用 Paper。
Q：掉进虚空了？
A：星球之间就是空的，可以把 floor-height 调大铺一层平台。
【1.0.0 更新内容】
· 从 Bukkit 1.4.6 移植到 Paper API，支持 1.21 ~ 26.3
· 区块生成改用 generateNoise + BlockData，移除旧的 MaterialData 与 BlockPopulator 阶段
· 星球系统改为按世界种子确定性生成，可安全并行生成（Folia 兼容的基础）
· 存档格式改为带版本号的二进制文件，写入使用临时文件原子替换，不再有 Java 序列化兼容问题
· 修复：原版地形/河流被叠加到星球世界的问题
· 修复：负坐标取模错误导致象限内星球位置错乱
· 修复：min-size == max-size 时随机数抛异常
· 修复：加权抽样过滤分支漏 break，"冰/羊毛外壳避开高温内核"形同虚设
· 修复：权重全为 0 时抽样死循环，可能卡死区块生成线程
· 修复：低高度世界出生点卡进方块里
· 修复：插件卸载时强制卸载世界导致玩家掉线
· 优化：星球填充从"遍历整个外接立方体"改为"只遍历相交的列"，半径 20 的星球快了一个数量级
· 配置项兼容旧版驼峰键名与旧材质写法，老 config.yml 可直接沿用
【声明】
· 玩法与算法来自原作者 Canisaur 的 Planetoids（https://github.com/Canisaur/Planetoids），
本版仅做 API 迁移与健壮性修复，保留原作者署名
· 本项目以 MIT 协议开源：https://github.com/CatGirlMaoDie/Planetoids
· 欢迎 PR / Issue；二次修改与分发请保留署名与协议
· 反馈问题时请附上：服务端版本、控制台报错、config.yml
【一句话简介】
把整个世界变成星空：无数由「外壳 + 核心」组成的漂浮星球，按行星系统确定性生成，材质与密度全部可调，支持 Paper 1.21 ~ 26.3。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
【这是什么】
Planetoids 原本是 2012 年的 Bukkit 老插件（作者 Canisaur，最后更新于 Bukkit 1.4.6）。本版是它的
Paper 现代化移植：重写了区块生成、存档格式与线程模型，只保留原版的玩法与手感。
没有前置插件，没有 NMS，单个 jar 约 48 KB。
【世界长什么样】
· 世界里没有地面，只有悬浮的星球；星球之间是虚空
· 每颗星球 = 一层外壳（石头／冰／雪／玻璃／羊毛／树叶……）+ 一个内核（岩浆／水／各种矿石／原木／南瓜……）
· 出生点上方有一颗固定的「树叶包原木」星球作为落脚点，往上一跳就能站稳
· 世界按「行星系统」划分，默认 50 区块 = 800×800 格 一个系统，系统内星球互不重叠
· 全天空只有一种生物群系，可选 NORMAL（正常天空）或 END（黑色星空）
【功能特性】
· 权重化材质表：外壳和内核各自一份列表，每一项都能写权重，随机结果符合直觉
· 材质支持方块状态（例如 oak_log[axis=y]），也兼容 1.4 时代的旧写法（WOOL-0.4-6 会自动转成粉色羊毛）
· 星球数量 / 半径 / 外壳厚度 / 最小间距 / 出生点高度 / 系统大小 全部可配置
· 可选在 y=-64 铺一层平台（floor-height），适合做可跑图的地面世界
· 永久夜晚、关闭天气、禁止怪物/动物生成，均为配置开关
· /pltp 一键在星球世界与主世界之间往返
· 行星系统会落盘缓存，重启、换插件版本都不会让已有世界"变脸"
【支持版本】
· Paper：1.21 ~ 26.3（api-version 1.21，向下兼容整段区间）
· Java：服务端需 Java 21（26.x 服务端需 Java 25）
· Folia：插件可正常加载、配置、注册命令、干净卸载，生成器也按 Folia 的线程模型编写
（不使用 BukkitScheduler，跨世界传送走 teleportAsync，区块生成无共享可变状态）
注意：Folia 本身禁止插件创建世界（Server#createWorld 直接抛异常），所以自动建世界这一项在 Folia 上不可用。
想要开箱即用，建议用 Paper。
· 实测环境：Paper 1.21.4-232、Paper 26.3-229 均通过（建世界、生成区块、落盘存档）
【安装】
1. 把 Planetoids-1.0.0.jar 放进服务器的 plugins 目录
2. 重启服务器（本插件需要在启动阶段接管生成器，/reload 无效）
3. 首次启动会自动创建名为 Planetoids 的世界，并在 plugins/Planetoids/ 生成 config.yml
4. 进服后输入 /pltp 传送过去，再输入一次回到主世界
5. 首次创建世界会预生成出生点周围约 441 个区块（约 10 秒），期间控制台可能出现一次
"server has not responded for 10 seconds" 的线程转储提示，那是 Paper 的看门狗，属正常现象
【命令与权限】
命令 说明
/pltp 在星球世界与主世界之间往返（别名 /planetoidstp）
权限 planetoids.pltp（默认所有人可用）
【配置速查】
配置文件：plugins/Planetoids/config.yml（带中文注释，改完需重启）
planetoids:
autocreateworld: true # 启动时自动创建世界
worldname: Planetoids # 世界名（也是存档文件夹名）
seed: 0 # 0 = 随机
environment: NORMAL # NORMAL / END（END 为黑色星空）
alwaysnight: false # 永久夜晚
weather: false # 关闭下雨/雷暴
disablemonsters: true # 禁止怪物
disableanimals: false # 禁止动物
system-size: 50 # 行星系统边长（区块）
spawn-y: 77 # 出生点高度
planets:
density: 750 # 每个系统尝试生成多少颗（撞车就丢弃）
min-size: 4 # 半径范围
max-size: 20
min-distance: 10 # 星球之间的最小间隙
min-shell-size: 3 # 外壳厚度范围
max-shell-size: 5
floor-block: GRASS_BLOCK
floor-height: 0 # >0 时在底部铺一层平台
bedrock: false # 平台最底层换基岩
blocks:
shells: [ stone-1.0, ice-0.9, oak_leaves-0.9, ... ]
cores: [ lava-0.8, water-1.0, diamond_ore-0.4, ... ]
方块写法： <材质>[-<权重 0~1>[-<旧版数据值>]]
stone-1.0 权重 1.0，抽到即使用
ice-0.9 九成概率被接受，否则重抽
minecraft:oak_log[axis=y]-0.5 支持方块状态，权重写在最后
WOOL-0.4-6 旧版写法，data 6 自动转为 pink_wool
调参小抄：
· 更密更热闹 → density 调到 1500、min-distance 调到 6
· 空岛/跑酷风 → density 200、max-size 8
· 有大星球 → max-size 35、min-shell-size 4
· 想有地面 → floor-height: 5、bedrock: true
【想重新开一个世界】
· 只换种子：停服 → 删掉世界文件夹 Planetoids/ 与 plugins/Planetoids/systems/Planetoids/ → 启动
· 只让"没去过的地方"用新配置：停服 → 删对应的 system_x_z.pgd → 启动（已生成的区块仍是旧方块，交界有接缝）
· 干净重来（推荐）：把 worldname 改成新名字，或删世界文件夹 + 系统存档
【性能与预生成】
· view-distance 6~8 足够，星球之间没有地形细节，看太远只会白消耗性能
· 大服务器建议先用 Chunky 之类工具预生成常驻区域
· 【注意】星球之间是虚空，掉下去会摔死，建议开 keepInventory 或让玩家用 /pltp
【常见问题】
Q：改了配置但世界没变化？
A：配置在插件启用时读取一次，改完必须重启；而且已生成的行星系统和已生成的区块都不会被改写，见上面「想重新开一个世界」。
Q：控制台提示 Unknown block 'xxx', entry skipped？
A：配置里写了当前服务端版本不存在的方块。插件会跳过它并给出警告，不会崩服。
Q：Folia 上提示世界无法创建？
A：Folia 不支持插件创建世界，属服务端限制。可在其他环境准备好世界后让其存在，插件会自动接管；
或直接使用 Paper。
Q：掉进虚空了？
A：星球之间就是空的，可以把 floor-height 调大铺一层平台。
【1.0.0 更新内容】
· 从 Bukkit 1.4.6 移植到 Paper API，支持 1.21 ~ 26.3
· 区块生成改用 generateNoise + BlockData，移除旧的 MaterialData 与 BlockPopulator 阶段
· 星球系统改为按世界种子确定性生成，可安全并行生成（Folia 兼容的基础）
· 存档格式改为带版本号的二进制文件，写入使用临时文件原子替换，不再有 Java 序列化兼容问题
· 修复：原版地形/河流被叠加到星球世界的问题
· 修复：负坐标取模错误导致象限内星球位置错乱
· 修复：min-size == max-size 时随机数抛异常
· 修复：加权抽样过滤分支漏 break，"冰/羊毛外壳避开高温内核"形同虚设
· 修复：权重全为 0 时抽样死循环，可能卡死区块生成线程
· 修复：低高度世界出生点卡进方块里
· 修复：插件卸载时强制卸载世界导致玩家掉线
· 优化：星球填充从"遍历整个外接立方体"改为"只遍历相交的列"，半径 20 的星球快了一个数量级
· 配置项兼容旧版驼峰键名与旧材质写法，老 config.yml 可直接沿用
【声明】
· 玩法与算法来自原作者 Canisaur 的 Planetoids（https://github.com/Canisaur/Planetoids），
本版仅做 API 迁移与健壮性修复，保留原作者署名
· 本项目以 MIT 协议开源：https://github.com/CatGirlMaoDie/Planetoids
· 欢迎 PR / Issue；二次修改与分发请保留署名与协议
· 反馈问题时请附上：服务端版本、控制台报错、config.yml
