袖珍岛屿

袖珍岛屿

个人创建的空间作为实际生成的世界存在,不与他人共享,除非你愿意!即使你丢弃模组和常规的Minecraft世界,它也会保留!

交通

Pocket Islands

一个适用于 Fabric、Forge 和 NeoForge 的 Minecraft 模组,为每位玩家提供其专属的持久化口袋维度岛屿。

支持的版本:

Minecraft Fabric Forge NeoForge
1.20.1 ✓ ✓
1.20.4 ✓
1.21.11 ✓ ✓

功能特性

  • 口袋岛屿:每位玩家获得自己独立的岛屿维度
  • 持久化:岛屿在主世界重置后依然存活
  • 基于传送门的访问:搭建传送门框架,用绿宝石激活
  • 邀请系统:邀请好友参观你的岛屿
  • 虚空生成:纯净的虚空世界,附带一座初始岛屿

需求

  • Minecraft 1.20.1、1.20.4 或 1.21.11
  • Fabric: Fabric Loader(1.20.x 需 0.15.0+,1.21.x 需 0.18.4+)和 Fabric API
  • Forge(1.20.1): Forge 47 或更高版本。无需其他组件:Infiniverse 已打包在 jar 中
  • NeoForge(1.21.11): NeoForge 21.11.45 或更高版本。无需其他组件:Infiniverse 已打包在 jar 中
  • 客户端和服务端都必须安装本模组

服务端

  1. 在服务器上安装 Fabric Loader、Forge 或 NeoForge
  2. 下载适用于你的 MC 版本和加载器的 Pocket Islands JAR
  3. 放入服务器的 mods/ 文件夹
    • 在 Fabric 上,请确保此处也安装了 Fabric API
  4. 启动服务器

客户端

  1. 安装 Fabric Loader、Forge 或 NeoForge
  2. 下载适用于你的 MC 版本和加载器的 Pocket Islands JAR
  3. 放入你的 mods/ 文件夹
    • 在 Fabric 上,请确保此处也安装了 Fabric API
  4. 启动 Minecraft

重要: 模组必须同时安装在客户端和服务端。详情请参阅 FAQ。

加载器差异

在所有加载器上岛屿的工作方式相同,但有以下例外:

Fabric Forge 1.20.1 / NeoForge 1.21.11
运行时维度 Fantasy(打包) Infiniverse(打包)
权限 通过 fabric-permissions-api 使用 LuckPerms,否则使用 OP 等级 通过加载器的 PermissionAPI 使用 LuckPerms,否则使用 OP 等级
岛屿时钟 独立时钟;doDaylightCycle: false 会冻结它 跟随主世界;doDaylightCycle 对岛屿无效
世界种子(OVERWORLD/FLAT 岛屿) 每个岛屿独立 主世界的种子。虚空岛屿不受影响

控制台和命令方块始终使用 OP 等级进行 /pi 权限判定。

不支持将整个世界在加载器之间迁移:切换加载器会替换整个整合包。单个岛屿可以迁移:将 world/dimensions/personalworlds/ 复制到另一台服务器(相同 Minecraft 版本),岛屿无需转换即可打开。岛屿注册表、返回位置和邀请保留在各服务器自己的世界中。OVERWORLD/FLAT 岛屿的新区块随后会按另一加载器的种子生成(参见上表)。

使用方法

创建传送门

此行为可配置,本说明使用默认配置。

使用下界砖搭建一个框架(4 宽 x 5 高):

N N N N
N     N
N     N
N     N
N N N N

用绿宝石右键点击框架内部以激活。

进入你的岛屿

走进已激活的传送门即可进入你的口袋岛屿。首次进入时,你的岛屿会根据传送门类型的岛屿层生成。新岛屿上没有返回传送门。

返回

最快的返回方式是跳下你的岛屿:在 Y=0 以下,你会在受到任何虚空伤害之前被传送回你进入的位置。

若要通过传送门返回,请在你的岛屿上搭建一个框架并像第一个那样激活它(需带上框架方块和激活物品)。进入它会将你带回原来的位置。

命令

玩家命令:

  • /pi invites - 查看你的邀请(发送的和收到的)
  • /pi invite <player> - 邀请玩家前往你的岛屿
  • /pi invite <player> always - 以“始终欢迎”状态邀请(若已启用)
  • /pi uninvite <player> - 撤销玩家的邀请
  • /pi togglewelcome <player> - 切换现有邀请的“始终欢迎”状态(若已启用)
  • /pi portals - 查看所有已配置的传送门类型及你的岛屿状态

管理员命令(op 等级 2+):

  • /pi admin list - 列出所有岛屿
  • /pi admin info <player> - 查看岛屿详情
  • /pi admin tp <player> - 传送到某个岛屿
  • /pi admin delete <player> [confirm] - 删除某个岛屿(op 4)

调试命令(op 等级 4):

  • /pi debug perf enable - 启用性能监控
  • /pi debug perf disable - 禁用性能监控
  • /pi debug perf status - 显示性能状态
  • /pi debug perf reset - 重置性能计数器

注意: 你应当不需要使用调试命令,但它们可能对检查有帮助。

配置

配置文件: config/pocketislands.json

Pocket Islands 提供丰富的自定义选项,尤其是针对岛屿构成。你可以定义多种传送门类型,每种类型创建具有不同材料和属性的岛屿。

示例配置

{
    "portalTypes": [
        {
            "frameBlock": "minecraft:nether_bricks",
            "activationItem": "minecraft:emerald",
            "islandLayers": [
                "minecraft:grass_block",
                "minecraft:dirt",
                "minecraft:stone"
            ],
            "portalColor": "red"
        }
    ],
    "consumeActivationItem": false,
    "maxInvitationsPerPlayer": 20,
    "enableAlwaysWelcome": false,
    "unloadEmptyDimensionDelayTicks": 600,
    "cleanupIntervalTicks": 600,
    "sanitizeChunksOnLoad": false,
    "sanitizeRemoveOrphanBlocks": false,
    "enableTeleportParticles": true,
    "enableTeleportSounds": true,
    "enablePortalActivationEffects": true,
    "enableInvitationNotifications": true,
    "dimensionGameRules": {
        "doMobSpawning": false
    }
}

配置选项

传送门类型(岛屿自定义)

定义多种传送门类型以创建具有不同材料的岛屿:

  • frameBlock — 用于传送门框架的方块(例如 "minecraft:nether_bricks")
  • activationItem — 用于激活传送门的物品(例如 "minecraft:emerald")
  • islandLayers — 自定义你的初始岛屿平台(最多 5 层,从上到下)
    • 示例:["minecraft:grass_block", "minecraft:dirt", "minecraft:stone"]
    • 创建主题岛屿:草方块/泥土/石头、下界岩/灵魂沙/玄武岩、末地石等
    • 每种传送门类型创建独特的岛屿构成
    • 每层厚度为 1 个方块,若需要 2 层泥土方块,在数组中重复该材料
  • portalColor — 传送门效果的颜色(默认:"red")
    • 可用颜色:"white"、"light_gray"、"gray"、"black"、"brown"、"red"、"orange"、"yellow"、"lime"、"green"、"cyan"、"light_blue"、"blue"、"purple"、"magenta"、"pink"
    • 帮助在视觉上区分不同的传送门类型

邀请

  • maxInvitationsPerPlayer — 每位玩家最大邀请数(-1 表示无限)
  • enableAlwaysWelcome — 启用“始终欢迎”功能(默认:false,需要重启)

“始终欢迎”功能

默认情况下,访客只能在你在线且位于你的岛屿上时进入。始终欢迎功能允许岛主授予特定访客永久访问权限,绕过这些限制。

启用该功能

在配置中将 enableAlwaysWelcome 设为 true 并重启服务器:

{
    "enableAlwaysWelcome": true
}

注意: 此设置需要重启服务器才能生效。禁用时,所有“始终欢迎”命令都会被隐藏,现有的标记也会被忽略。

使用“始终欢迎”

启用后,岛主有两种方式授予“始终欢迎”状态:

方式 1:以“始终欢迎”邀请

/pi invite Steve always

这会立即创建一个启用了“始终欢迎”的新邀请。

方式 2:切换现有邀请

/pi togglewelcome Steve

这会切换现有邀请的“始终欢迎”状态。再次运行可禁用。

查看“始终欢迎”状态

使用 /pi invites 查看你发送的邀请。启用该功能后,每个邀请会显示一个可点击的星形指示器:

Sent (players who can visit you):
  - Steve [★] [Revoke]    ← Green star: Always Welcome ON
  - Alex  [☆] [Revoke]    ← Gray star: Always Welcome OFF

点击星形可直接在聊天中切换状态。

访问控制行为

邀请类型 岛主在线 + 在岛 岛主在线 + 不在岛 岛主离线
标准 ✓ 允许 ✗ 拒绝 ✗ 拒绝
始终欢迎 ✓ 允许 ✓ 允许 ✓ 允许

说明:

  • 管理员(OP 等级 2+)始终绕过所有访问限制
  • 岛主始终可以访问自己的岛屿
  • “始终欢迎”访客仍需有效的邀请(取消邀请会移除访问权限)

性能

  • unloadEmptyDimensionDelayTicks — 卸载空维度前的延迟(默认:600 = 30 秒)
  • cleanupIntervalTicks — 检查空维度的频率(默认:600 = 30 秒)

区块清理器

  • sanitizeChunksOnLoad — 在区块加载时清除孤立的方块实体和未知的容器物品(默认:false;需主动启用)
  • sanitizeRemoveOrphanBlocks — 在清理过程中同时移除失去有效支撑的方块(火、火把、红石、雪层)(默认:false;仅在启用 sanitizeChunksOnLoad 时使用)

视觉效果

  • enableTeleportParticles — 传送时显示粒子效果
  • enableTeleportSounds — 传送时播放音效
  • enablePortalActivationEffects — 激活传送门时显示效果
  • enableInvitationNotifications — 播放邀请通知音效

高级选项

  • consumeActivationItem — 激活传送门时是否消耗激活物品(默认:false)

维度游戏规则

默认情况下,口袋维度继承主世界的所有游戏规则。你可以使用 dimensionGameRules 配置覆盖特定规则:

{
    "dimensionGameRules": {
        "keepInventory": true,
        "randomTickSpeed": 3,
        "doMobSpawning": false
    }
}

此配置将会:

  • 强制 keepInventory 为 true(玩家死亡时保留物品)
  • 强制 randomTickSpeed 为 3(作物和植物生长倍率)
  • 强制 doMobSpawning 为 false(生物无法自然生成)
  • 所有其他规则继承自主世界

版本特定的游戏规则名称:

Minecraft 1.21.x 重命名了许多游戏规则。请为你的服务器版本使用适当的名称:

功能 1.20.x (camelCase) 1.21.x (snake_case)
死亡保留物品栏 keepInventory keep_inventory
生物生成 doMobSpawning spawn_mobs
作物/植物生长速度 randomTickSpeed random_tick_speed
生物物品掉落 doMobLoot mob_drops
方块掉落 doTileDrops block_drops
生物破坏 mobGriefing mob_griefing
立即重生 doImmediateRespawn immediate_respawn

默认行为:

  • 1.20.x:{"doMobSpawning": false} — 创建无生物生成的虚空岛屿
  • 1.21.x:{"spawn_mobs": false} — 重命名规则后的相同行为

注意: 预期行为是在口袋维度中禁用生物生成, 因为它是 VOID 类型世界,启用它没有意义, 但如果你愿意,可以启用它。只需在配置中将 doMobSpawning / spawn_mobs 设为 true。

这是不受支持的功能,不会被接受为漏洞报告。

要原样继承主世界的所有规则且不做更改,请使用空映射:

{
    "dimensionGameRules": {}
}

创建多种传送门类型

你可以定义多种传送门类型以创建不同的岛屿主题。玩家可以通过使用不同的传送门材料来选择他们想要的岛屿类型:

{
    "portalTypes": [
        {
            "frameBlock": "minecraft:nether_bricks",
            "activationItem": "minecraft:emerald",
            "islandLayers": [
                "minecraft:grass_block",
                "minecraft:dirt",
                "minecraft:stone"
            ],
            "portalColor": "red"
        },
        {
            "frameBlock": "minecraft:blackstone",
            "activationItem": "minecraft:nether_star",
            "islandLayers": [
                "minecraft:netherrack",
                "minecraft:soul_sand",
                "minecraft:basalt"
            ],
            "portalColor": "red"
        },
        {
            "frameBlock": "minecraft:end_stone_bricks",
            "activationItem": "minecraft:ender_pearl",
            "islandLayers": [
                "minecraft:end_stone"
            ],
            "portalColor": "cyan"
        }
    ]
}

注意: 玩家使用的第一种传送门类型将永久决定其岛屿构成。

重新加载配置

使用 /pi admin reload 无需重启服务器即可重新加载配置。对传送门类型的更改仅影响新创建的岛屿。

翻译

Pocket Islands 对所有面向用户的消息使用 Fabric 的标准语言文件系统。这允许服务器管理员和整合包作者自定义消息或添加不同语言的翻译。

语言文件位置

语言文件位于:

src/main/resources/assets/personalworlds/lang/

模组默认包含英语(美国)翻译:

lang/en_us.json

添加自定义语言

要添加对其他语言(例如德语、荷兰语、西班牙语)的支持:

  1. 使用适当的语言环境代码创建一个新的语言文件:

    • 德语使用 de_de.json
    • 荷兰语使用 nl_nl.json
    • 西班牙语使用 es_es.json
    • 查看 Minecraft Wiki - Language 获取所有语言环境代码
  2. 复制 en_us.json 的内容作为模板

  3. 翻译消息值(保持键不变):

{
    "pocketislands.message.invite_sent": "Eingeladen %s zu deiner Dimension",
    "pocketislands.message.invite_received": "%s hat dich zu ihrer Dimension eingeladen",
    // ...
}
  1. 将文件放入你的资源包或模组 JAR 的 assets/personalworlds/lang/ 中

自定义消息

要在保持英语语言的同时自定义消息:

  1. 创建资源包或直接编辑 assets/personalworlds/lang/en_us.json
  2. 修改翻译值(每行右侧)
  3. 保持翻译键(左侧)不变
  4. 字符串参数使用 %s,数字使用 %d

示例:

{
    "pocketislands.message.invite_sent": "You invited %s to your island!",
    "pocketislands.message.invite_received": "%s wants you to visit their island!"
}

可用的翻译键

所有翻译键均在 lang/en_us.json 中有文档说明。键类别包括:

  • pocketislands.message.* — 面向玩家的消息(邀请、驱逐、传送)
  • pocketislands.command.* — 命令反馈和信息
  • pocketislands.command.error.* — 错误消息
  • pocketislands.invitations.* — 邀请列表 UI 文本
  • pocketislands.command.perf.* — 性能监控消息
  • pocketislands.command.list.* — 管理员列表命令输出
  • pocketislands.command.info.* — 管理员信息命令输出
  • pocketislands.command.delete.* — 管理员删除命令警告
  • pocketislands.command.portals.* — 传送门类型列表和岛屿状态

技术细节

维度存储

每个口袋岛屿存储在:

world/dimensions/personalworlds/pw_<uuid>/

其中 <uuid> 是玩家的 UUID(不含连字符)。

元数据恢复

每个维度文件夹包含一个 .metadata 文件,在主注册表损坏时支持恢复。该文件包含:

  • 所有者 UUID
  • 所有者名称
  • 维度 ID
  • 创建时间戳
  • 出生点
  • 生成器类型

已处理的边缘情况

  • 玩家在口袋岛屿中断开连接:位置保留,即使维度已卸载,重连时维度也会恢复
  • 离线时维度被卸载:玩家会被恢复到其岛屿,若恢复失败则回退到床出生点或世界出生点
  • 服务器崩溃:恢复处理器检查权限并在需要时疏散
  • 两名玩家同时进入传送门:并发传送门防护可防止竞态条件
  • 返回位置被阻挡:安全出生点查找器会定位附近的安全位置
  • 离线时邀请被撤销:玩家在下次登录时被疏散,并采用回退链(返回数据 → 床 → 出生点)
  • 玩家从岛屿上掉落:在受到虚空伤害之前自动传送回
  • 未知方块或容器物品:启用 sanitizeChunksOnLoad 后,区块在加载时会被清理——孤立的方块实体(支撑方块现为空气)会被清除,容器中的未知物品会被清空。或者,按需运行 /pi admin sanitize。

性能

模组设计为高效处理 15 个以上并发岛屿:

  • 岛屿为空时自动卸载(延迟 30 秒后)
  • 虚空世界的内存高效区块生成
  • 可通过调试命令进行性能监控

致谢

首先,我要感谢我的朋友 Bktwone,他启发了这个模组, 并提供了测试该模组的平台。

  • 使用 Fantasy 构建,用于运行时维度创建
  • 使用 Fabric API 实现模组钩子