Pocket Islands

A Minecraft mod for Fabric, Forge and NeoForge that gives each player their own persistent
pocket dimension island.

Supported Versions:

| Minecraft | Fabric | Forge | NeoForge |
|———–|——–|——-|———-|
| 1.20.1 | ✓ | ✓ | |
| 1.20.4 | ✓ | | |
| 1.21.11 | ✓ | | ✓ |

Features

Pocket Islands: Each player gets their own isolated island dimension
Persistence: Islands survive main world resets
Portal-Based Access: Build a portal frame, activate with emerald
Invitation System: Invite friends to visit your island
Void Generation: Clean slate void worlds with a starter island

Requirements

Minecraft 1.20.1, 1.20.4, or 1.21.11
Fabric: Fabric Loader (0.15.0+ for 1.20.x, 0.18.4+ for 1.21.x) and Fabric API
Forge (1.20.1): Forge 47 or newer. Nothing else: Infiniverse is bundled in the jar
NeoForge (1.21.11): NeoForge 21.11.45 or newer. Nothing else: Infiniverse is bundled in the jar
Both client and server must have the mod installed

Server

Install Fabric Loader, Forge or NeoForge on your server
Download the Pocket Islands JAR for your MC version and loader
Place in the server’s mods/ folder

On Fabric, make sure Fabric API is also installed here

Start the server

Client

Install Fabric Loader, Forge or NeoForge
Download the Pocket Islands JAR for your MC version and loader
Place in your mods/ folder

On Fabric, make sure Fabric API is also installed here

Launch Minecraft

Important: The mod must be installed on both client and server. See
FAQ for details.

Loader Differences

Islands work the same on every loader, with these exceptions:

Console and command blocks always use OP levels for /pi permissions.

Moving a whole world between loaders is not supported: switching loaders replaces
the entire modpack. Individual islands can move: copy world/dimensions/personalworlds/ to
the other server (same Minecraft version) and the islands open without conversion. The
island registry, return positions and invitations stay with each server’s own world. New
chunks of OVERWORLD/FLAT islands then generate with the other loader’s seed (see the
table above).

Usage

Creating a Portal

This can be configured, this explanation uses the default configuration.

Build a frame using Nether Bricks (4 wide x 5 tall):

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

Right-click the inside of the frame with an Emerald to activate.

Entering Your Island

Walk into the activated portal to enter your pocket island. On first entry, your
island is generated from your portal type’s island layers. There is no return portal
on a new island.

Returning

The quickest way back is to jump off your island: below Y=0 you’re teleported back to
where you entered, before taking any void damage.

To return by portal instead, build a frame on your island and activate it like the
first one (bring the frame blocks and activation item). Entering it takes you back to
your original location.

Commands

Player commands:

/pi invites – View your invitations (sent and received)
/pi invite <player> – Invite a player to your island
/pi invite <player> always – Invite with Always Welcome status (if enabled)
/pi uninvite <player> – Revoke a player’s invitation
/pi togglewelcome <player> – Toggle Always Welcome for an existing invitation (if enabled)
/pi portals – View all configured portal types and your island status

Admin commands (op level 2+):

/pi admin list – List all islands
/pi admin info <player> – View island details
/pi admin tp <player> – Teleport to an island
/pi admin delete <player> [confirm] – Delete an island (op 4)

Debug commands (op level 4):

/pi debug perf enable – Enable performance monitoring
/pi debug perf disable – Disable performance monitoring
/pi debug perf status – Show performance status
/pi debug perf reset – Reset performance counters

Note: You should not need the debug commands, but they may be useful for
checking.

Configuration

Config file: config/pocketislands.json

Pocket Islands offers extensive customization options, particularly for **island
composition**. You can define multiple portal types, each creating islands with
different materials and properties.

Example Configuration

{
    "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
    }
}

Configuration Options

Portal Types (Island Customization)

Define multiple portal types to create islands with different materials:

frameBlock — Block used for portal frames (e.g., "minecraft:nether_bricks")
activationItem — Item used to activate portals (e.g., "minecraft:emerald")
islandLayers — Customize your starter island platform (up to 5 layers, top to bottom)
Example: ["minecraft:grass_block", "minecraft:dirt", "minecraft:stone"]
Create themed islands: grass/dirt/stone, netherrack/soul_sand/basalt, end_stone, etc.
Each portal type creates a unique island composition
Each layer is 1 block thick, for 2 dirt block layers, repeat the material in the array
portalColor — Color of the portal effect (default: "red")
Available colors: "white", "light_gray", "gray", "black", "brown", "red", "orange", "yellow", "lime", "green", "cyan", "light_blue", "blue", "purple", "magenta", "pink"
Helps visually distinguish different portal types

Invitations

maxInvitationsPerPlayer — Maximum invitations per player (-1 for unlimited)
enableAlwaysWelcome — Enable the Always Welcome feature (default: false, requires restart)

Always Welcome Feature

By default, visitors can only enter your island when you are online and present
on your island. The Always Welcome feature allows island owners to grant
specific guests permanent access, bypassing these restrictions.

Enabling the Feature

Set enableAlwaysWelcome to true in your config and restart the server:

{
    "enableAlwaysWelcome": true
}

Note: This setting requires a server restart to take effect. When disabled,
all Always Welcome commands are hidden and existing flags are ignored.

Using Always Welcome

Once enabled, island owners have two ways to grant Always Welcome status:

Option 1: Invite with Always Welcome

/pi invite Steve always

This creates a new invitation with Always Welcome enabled immediately.

Option 2: Toggle existing invitation

/pi togglewelcome Steve

This toggles the Always Welcome status on an existing invitation. Run it again
to disable.

Viewing Always Welcome Status

Use /pi invites to see your sent invitations. When the feature is enabled,
each invitation shows a clickable star indicator:

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

Click the star to toggle the status directly from the chat.

Access Control Behavior

Notes:

Admins (OP level 2+) always bypass all visit restrictions
The island owner can always access their own island
Always Welcome guests still need an active invitation (uninviting removes access)

Performance

unloadEmptyDimensionDelayTicks — Delay before unloading empty dimensions (default: 600 = 30 seconds)
cleanupIntervalTicks — How often to check for empty dimensions (default: 600 = 30 seconds)

Chunk Sanitizer

sanitizeChunksOnLoad — Purge orphaned block entities and unknown container items on chunk load (default: false; opt-in)
sanitizeRemoveOrphanBlocks — Also remove blocks left without valid support (fires, torches, redstone, snow layers) during sanitization (default: false; only used when sanitizeChunksOnLoad is enabled)

Visual Effects

enableTeleportParticles — Show particle effects during teleportation
enableTeleportSounds — Play sound effects during teleportation
enablePortalActivationEffects — Show effects when activating portals
enableInvitationNotifications — Play sounds for invitation notifications

Advanced Options

consumeActivationItem — Whether the activation item is consumed on portal activation (default: false)

Dimension Game Rules

Pocket dimensions inherit all game rules from the overworld by default. You can override specific rules using the dimensionGameRules configuration:

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

This configuration will:

Force keepInventory to true (players keep items on death)
Force randomTickSpeed to 3 (crop and plant growth multiplier)
Force doMobSpawning to false (mobs cannot spawn naturally)
All other rules inherit from the overworld

Version-Specific Game Rule Names:

Minecraft 1.21.x renamed many game rules. Use the appropriate names for your server version:

Default behavior:

1.20.x: {"doMobSpawning": false} — Creates void islands with no mobs
1.21.x: {"spawn_mobs": false} — Same behavior with renamed rule

NOTE: The intended behavior is that mob spawning is disabled in the

pocket dimension, it makes no sense to enable it as it is a VOID type world

but if you want to, you can enable it. Just set doMobSpawning / spawn_mobs

to true in the configuration.

_This is an unsupported feature, and will not be accepted as a bug._

To inherit all rules from the overworld without changes, use an empty map:

{
    "dimensionGameRules": {}
}

Creating Multiple Portal Types

You can define multiple portal types to create different island themes. Players
can choose which type of island they want by using different portal materials:

{
    "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"
        }
    ]
}

Note: The first portal type a player uses determines their island
composition permanently.

Reloading Configuration

Use /pi admin reload to reload the configuration without restarting the
server. Changes to portal types only affect newly created islands.

Translations

Pocket Islands uses Fabric’s standard language file system for all user-facing
messages. This allows server admins and modpack creators to customize messages
or add translations for different languages.

Language File Location

Language files are located at:

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

The mod includes an English (US) translation by default:

lang/en_us.json

Adding Custom Languages

To add support for another language (e.g., German, Dutch, Spanish):

Create a new language file with the appropriate locale code:

de_de.json for German
nl_nl.json for Dutch
es_es.json for Spanish
See Minecraft Wiki – Language for all locale codes

Copy the contents of en_us.json as a template

Translate the message values (keep the keys unchanged):

{
    "pocketislands.message.invite_sent": "Eingeladen %s zu deiner Dimension",
    "pocketislands.message.invite_received": "%s hat dich zu ihrer Dimension eingeladen",
    // ...
}

Place the file in assets/personalworlds/lang/ in your resource pack or mod JAR

Customizing Messages

To customize messages while keeping the English language:

Create a resource pack or edit assets/personalworlds/lang/en_us.json directly
Modify the translation values (right side of each line)
Keep translation keys (left side) unchanged
Use %s for string parameters, %d for numbers

Example:

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

Available Translation Keys

All translation keys are documented in lang/en_us.json. Key categories include:

pocketislands.message.* — Player-facing messages (invitations, ejections, teleports)
pocketislands.command.* — Command feedback and info
pocketislands.command.error.* — Error messages
pocketislands.invitations.* — Invitation list UI text
pocketislands.command.perf.* — Performance monitoring messages
pocketislands.command.list.* — Admin list command output
pocketislands.command.info.* — Admin info command output
pocketislands.command.delete.* — Admin delete command warnings
pocketislands.command.portals.* — Portal types listing and island status

Technical Details

Dimension Storage

Each pocket island is stored at:

world/dimensions/personalworlds/pw_<uuid>/

Where <uuid> is the player’s UUID without dashes.

Metadata Recovery

Each dimension folder contains a .metadata file that enables recovery if the
main registry is corrupted. This file contains:

Owner UUID
Owner name
Dimension ID
Creation timestamp
Spawn point
Generator type

Edge Cases Handled

Player disconnects in pocket island: Position preserved, dimension restored on reconnect even if unloaded
Dimension unloaded while offline: Player is restored to their island with fallback to bed spawn or world spawn if restoration fails
Server crashes: Recovery handler checks permissions and evacuates if needed
Two players enter portal simultaneously: Concurrent portal guard prevents race conditions
Return position is blocked: Safe spawn finder locates nearby safe position
Invitation revoked while offline: Player evacuated on next login with fallback chain (return data → bed → spawn)
Player falls off island: Automatically teleported back before taking void damage
Unknown blocks or container items: With sanitizeChunksOnLoad enabled, chunks are sanitized on load — orphaned block entities (backing block is now air) are purged, unknown items in containers are cleared. Alternatively, run /pi admin sanitize on demand.

Performance

The mod is designed to handle 15+ concurrent islands efficiently:

Islands unload automatically when empty (after 30s delay)
Memory-efficient chunk generation for void worlds
Performance monitoring available via debug commands

Credits

First of all I want to credit my friend, Bktwone, for inspiring this mod as well

as providing a platform to test this mod.

Built with Fantasy for runtime dimension creation
Fabric API for mod hooks

介绍

Pocket Islands

Features

Requirements

Server

Client

Loader Differences

Usage

Creating a Portal

Entering Your Island

Returning

Commands

Configuration

Example Configuration

Configuration Options

Portal Types (Island Customization)

Invitations

Always Welcome Feature

Enabling the Feature

Using Always Welcome

Viewing Always Welcome Status

Access Control Behavior

Performance

Chunk Sanitizer

Visual Effects

Advanced Options

Dimension Game Rules

Creating Multiple Portal Types

Reloading Configuration

Translations

Language File Location

Adding Custom Languages

Customizing Messages

Available Translation Keys

Technical Details

Dimension Storage

Metadata Recovery

Edge Cases Handled

Performance

Credits

常见问题

Pocket Islands 支持哪些 Minecraft 版本？

Pocket Islands 怎么安装？

评论