Pocket Islands

Pocket Islands

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

Supported Versions:

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

1. Install Fabric Loader, Forge or NeoForge on your server
2. Download the Pocket Islands JAR for your MC version and loader
3. Place in the server's mods/ folder
   • On Fabric, make sure Fabric API is also installed here

• Start the server

Client

1. Install Fabric Loader, Forge or NeoForge
2. Download the Pocket Islands JAR for your MC version and loader
3. 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):

1. 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",
    // ...
}

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

Customizing Messages

To customize messages while keeping the English language:

1. Create a resource pack or edit assets/personalworlds/lang/en_us.json directly
2. Modify the translation values (right side of each line)
3. Keep translation keys (left side) unchanged
4. 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