GetPerWorldPlugin

What is GetPerWorldPlugin?

GetPerWorldPlugin is a lightweight yet powerful Paper plugin that allows server administrators to restrict specific plugins to specific worlds. It creates a "per-world plugin" experience without actually loading/unloading plugins per world.

### The Problem It Solves

Many Minecraft servers use multiple worlds for different purposes:
- Survival world with economy plugins
- Creative world without economy
- Minigame worlds with specific plugins
- Hub world with limited features

Without GetPerWorldPlugin, all plugins work in all worlds, which can cause:
- Economy exploits (earning money in creative)
- Skill grinding in unintended worlds
- Command spam in hub/lobby areas
- Gameplay inconsistencies

### The Solution

GetPerWorldPlugin intercepts commands before they execute and checks:
1. Does this command belong to a restricted plugin?
2. Is the player in an allowed world for that plugin?

If not allowed → Block the command silently

---

## Key Features

### ✅ Default Allow Behavior
<br> If a plugin is NOT in the config → It works EVERYWHERE<br> If a plugin IS in the config → It ONLY works in listed worlds<br>

This means you only configure what you want to restrict, not what you want to allow.

### ✅ Whitelist Approach
Unlike blacklist systems where you block specific worlds, GetPerWorldPlugin uses a whitelist:
- List the worlds where the plugin SHOULD work
- All other worlds are automatically blocked

### ✅ Complete Command Blocking
- Execution Blocking: Commands are cancelled before they run
- Tab Completion Hiding: Restricted commands don't appear in tab suggestions
- Alias Support: Blocks all aliases of a command automatically

### ✅ Performance Optimized
- Configuration cached in memory (no file reads per command)
- Command-to-plugin mapping cached after first lookup
- Minimal overhead on command execution

### ✅ Bypass Permission
Administrators can bypass all restrictions with a single permission.

### ✅ Hot Reload
Reload configuration without restarting the server.

### ✅ Debug Mode
Enable detailed logging to troubleshoot restriction issues.

### ✅ Multiverse Compatible
Works seamlessly alongside Multiverse-Core for world management.

---

## How It Works

### Flow Diagram

<br> Player types command (e.g., /mcmmo)<br> ↓<br> [PlayerCommandPreprocessEvent]<br> ↓<br> Does player have bypass permission?<br> YES → Allow command, exit<br> NO → Continue<br> ↓<br> Identify which plugin owns this command<br> NULL → Allow (vanilla command), exit<br> Plugin Found → Continue<br> ↓<br> Is this plugin in restriction list?<br> NO → Allow (default allow), exit<br> YES → Continue<br> ↓<br> Is player's current world in allowed list?<br> YES → Allow command, exit<br> NO → BLOCK command, send message<br>

### Tab Completion Flow

<br> Player opens tab completion<br> ↓<br> [PlayerCommandSendEvent]<br> ↓<br> For each command in the list:<br> ↓<br> Does player have bypass? → Keep all<br> ↓<br> Get owning plugin of command<br> ↓<br> Is plugin restricted AND world not allowed?<br> YES → Remove from tab list<br> NO → Keep in tab list<br>

---

## Installation

### Requirements
| Requirement | Version |
|-------------|---------|
| Minecraft Server | 1.21.1 - 1.21.8 |
| Server Software | Paper (or forks like Purpur) |
| Java | 21 or higher |

### Steps

1. Download the GetPerWorldPlugin.jar file

2. Place the JAR in your server's plugins/ folder

3. Start/Restart your server

4. Configure the plugin by editing plugins/GetPerWorldPlugin/config.yml

5. Reload with /getperworld reload or restart server

### Optional Dependencies
| Plugin | Purpose |
|--------|---------|
| Multiverse-Core | World management (soft dependency) |

---

## Configuration Guide

### Config File Location
<br> plugins/GetPerWorldPlugin/config.yml<br>

### Complete Configuration Example

yaml<br> #######################################################<br> # GetPerWorldPlugin Configuration #<br> #######################################################<br> <br> # =====================================================<br> # PLUGIN RESTRICTIONS<br> # =====================================================<br> # Format:<br> # PluginName:<br> # - allowed_world_1<br> # - allowed_world_2<br> #<br> # IMPORTANT:<br> # - Plugin names are CASE-SENSITIVE<br> # - World names are case-insensitive<br> # - If a plugin is NOT listed, it works everywhere<br> # =====================================================<br> <br> plugin-restrictions:<br> <br> # McMMO only works in survival worlds<br> mcMMO:<br> - survival<br> - survival_nether<br> - survival_the_end<br> <br> # Jobs plugin restricted to main survival<br> Jobs:<br> - survival<br> <br> # Slimefun in its own dedicated world<br> Slimefun:<br> - slimefun_world<br> - slimefun_nether<br> <br> # AureliumSkills only in RPG world<br> AureliumSkills:<br> - rpg_world<br> - rpg_dungeons<br> <br> # Economy commands only in survival<br> EssentialsX:<br> - survival<br> - survival_nether<br> - survival_the_end<br> - shops<br> <br> # Disable all CMI commands except in survival<br> CMI:<br> - survival<br> <br> # =====================================================<br> # BLOCKED MESSAGE<br> # =====================================================<br> # Shown when a player tries a restricted command<br> # <br> # Color Codes:<br> # &amp;0-9, &amp;a-f = Colors<br> # &amp;l = Bold, &amp;o = Italic<br> # &amp;n = Underline, &amp;m = Strikethrough<br> # &amp;r = Reset<br> # =====================================================<br> <br> blocked-message: "&amp;c&amp;lBlocked! &amp;7This command is not available in this world."<br> <br> # Alternative message examples:<br> # blocked-message: "&amp;8[&amp;c✖&amp;8] &amp;7This feature is disabled here."<br> # blocked-message: "&amp;e⚠ &amp;7You cannot use that command in this world!"<br> # blocked-message: "&amp;7(&amp;c!&amp;7) &amp;fCommand restricted to survival worlds."<br> <br> # =====================================================<br> # DEBUG MODE<br> # =====================================================<br> # Enable for detailed console logging<br> # Useful for troubleshooting restrictions<br> # WARNING: Can spam console on busy servers<br> # =====================================================<br> <br> debug: false<br>

### Finding Plugin Names

To find the exact plugin name (case-sensitive):

1. Run /plugins in-game
2. Look at the plugin list
3. Use the EXACT name shown (including capitalization)

Examples:
| Shown in /plugins | Use in Config |
|-------------------|---------------|
| mcMMO | mcMMO |
| Jobs | Jobs |
| EssentialsX | EssentialsX |
| Slimefun | Slimefun |
| AureliumSkills | AureliumSkills |

### Finding World Names

To find world names:

<br> /getperworld list # If you have the plugin<br> /mv list # If using Multiverse<br> /worlds # Various world plugins<br>

Or check your server's world folders.

---

## Commands

### Main Command
<br> /getperworld [subcommand]<br>

Aliases: /gpw, /perworld

### Subcommands

| Command | Description | Permission |
|---------|-------------|------------|
| /getperworld help | Show help menu | getperworld.admin |
| /getperworld reload | Reload configuration | getperworld.admin |
| /getperworld list | List all restrictions | getperworld.admin |
| /getperworld info <plugin> | Show plugin restriction details | getperworld.admin |

### Command Examples

Reload Configuration:
<br> /getperworld reload<br> &gt; [GetPerWorld] Configuration reloaded successfully! (12ms)<br> &gt; [GetPerWorld] Loaded 5 plugin restriction(s).<br>

List All Restrictions:
<br> /getperworld list<br> &gt; [GetPerWorld] Restricted Plugins (3):<br> &gt; • mcMMO → survival, survival_nether, survival_the_end<br> &gt; • Jobs → survival<br> &gt; • Slimefun → slimefun_world<br>

Check Specific Plugin:
<br> /getperworld info mcMMO<br> &gt; [GetPerWorld] Restriction info for mcMMO:<br> &gt; Allowed Worlds: survival, survival_nether, survival_the_end<br>

---

## Permissions

### Permission Nodes

| Permission | Description | Default |
|------------|-------------|---------|
| getperworld.bypass | Bypass all world restrictions | OP |
| getperworld.admin | Access admin commands | OP |
| getperworld.* | All permissions | OP |

### Permission Examples (LuckPerms)

Give bypass to VIP players:
<br> /lp group vip permission set getperworld.bypass true<br>

Give admin access to moderators:
<br> /lp group moderator permission set getperworld.admin true<br>

Remove bypass from specific player:
<br> /lp user PlayerName permission set getperworld.bypass false<br>

### Permission Inheritance

<br> getperworld.*<br> ├── getperworld.bypass<br> └── getperworld.admin<br>

---

## Use Cases & Examples

### Use Case 1: Survival-Only Skills

Scenario: You want mcMMO and Jobs to only work in survival worlds.

Config:
yaml<br> plugin-restrictions:<br> mcMMO:<br> - survival<br> - survival_nether<br> - survival_the_end<br> Jobs:<br> - survival<br> - survival_nether<br> - survival_the_end<br>

Result:
- ✅ /mcmmo works in survival
- ✅ /jobs works in survival_nether
- ❌ /mcmmo blocked in creative
- ❌ /jobs blocked in hub

---

### Use Case 2: Separate Game Modes

Scenario: Different plugins for different game modes.

Config:
yaml<br> plugin-restrictions:<br> # Survival plugins<br> mcMMO:<br> - survival<br> Jobs:<br> - survival<br> <br> # Skyblock plugins<br> ASkyBlock:<br> - skyblock<br> <br> # Prison plugins<br> Prison:<br> - prison_mines<br> - prison_cells<br> <br> # Factions plugins<br> Factions:<br> - factions_world<br>

Result: Each game mode has isolated plugins.

---

### Use Case 3: Hub World Lockdown

Scenario: Block almost everything in the hub world.

Config:
yaml<br> plugin-restrictions:<br> # All these plugins are blocked in hub<br> # because hub is NOT in their allowed worlds<br> <br> mcMMO:<br> - survival<br> <br> Jobs:<br> - survival<br> <br> Essentials:<br> - survival<br> - creative<br> <br> WorldEdit:<br> - creative<br> - build<br>

Result:
- Hub world has no plugin commands available
- Only vanilla commands and unrestricted plugins work

---

### Use Case 4: Creative World Restrictions

Scenario: Allow WorldEdit in creative, block economy.

Config:
yaml<br> plugin-restrictions:<br> # Economy blocked in creative (not in list)<br> EssentialsX:<br> - survival<br> <br> Vault:<br> - survival<br> <br> # WorldEdit allowed in creative and build worlds<br> WorldEdit:<br> - creative<br> - build_world<br> - admin_world<br> <br> # FAWE also restricted<br> FastAsyncWorldEdit:<br> - creative<br> - build_world<br> - admin_world<br>

---

### Use Case 5: Event/Minigame Worlds

Scenario: Minigame worlds with no external plugins.

Config:
yaml<br> plugin-restrictions:<br> # None of these work in minigame worlds<br> mcMMO:<br> - survival<br> <br> Jobs:<br> - survival<br> <br> EssentialsX:<br> - survival<br> - creative<br> <br> # Minigame plugin works everywhere (not listed)<br> # BedWars: works everywhere<br> # SkyWars: works everywhere<br>

---

## Technical Details

### Supported Plugin Types

| Type | Supported | Notes |
|------|-----------|-------|
| Bukkit/Spigot Plugins | ✅ Yes | Full support |
| Paper Plugins | ✅ Yes | Full support |
| Vanilla Commands | ⚪ Ignored | Cannot restrict |
| Mod Commands (hybrid) | ⚠️ Partial | Depends on registration |

### Event Priorities

| Event | Priority | Reason |
|-------|----------|--------|
| PlayerCommandPreprocessEvent | HIGHEST | Execute after other plugins modify command |
| PlayerCommandSendEvent | HIGHEST | Filter after other plugins add commands |

### Performance Metrics

| Operation | Typical Time |
|-----------|--------------|
| Config Load | 5-20ms |
| Command Check | <0.1ms |
| Cache Lookup | <0.01ms |
| Tab Filter (100 cmds) | <1ms |

### Memory Usage

| Component | Approximate Size |
|-----------|------------------|
| Plugin Base | ~50KB |
| Config Cache | ~1KB per restriction |
| Command Cache | ~100 bytes per command |

---

## Troubleshooting

### Issue: Commands Not Being Blocked

Check 1: Plugin Name
yaml<br> # WRONG (lowercase)<br> plugin-restrictions:<br> mcmmo:<br> - survival<br> <br> # CORRECT (exact case)<br> plugin-restrictions:<br> mcMMO:<br> - survival<br>

Check 2: World Name
yaml<br> # Check your actual world folder names<br> # Use lowercase in config for safety<br> plugin-restrictions:<br> mcMMO:<br> - survival_world # Matches "Survival_World", "survival_world", etc.<br>

Check 3: Enable Debug
yaml<br> debug: true<br>
Then check console for messages like:
<br> [GetPerWorld] [Debug] Command 'mcmmo' from plugin 'mcMMO' allowed in world 'survival'.<br> [GetPerWorld] [Debug] BLOCKED: Command 'mcmmo' from plugin 'mcMMO' in world 'creative'.<br>

Check 4: Bypass Permission
<br> /lp user &lt;player&gt; permission check getperworld.bypass<br>

---

### Issue: Tab Completion Still Shows Commands

Cause: Client-side caching

Solution:
1. Player should relog
2. Or change worlds and back
3. Tab cache refreshes on world change

---

### Issue: Plugin Name Not Found

Run this command to verify:
<br> /plugins<br>

Look for the exact name. Common mistakes:

| Wrong | Correct |
|-------|---------|
| Essentials | EssentialsX or Essentials (check your version) |
| MCMMO | mcMMO |
| worldedit | WorldEdit |
| FastAsyncWorldedit | FastAsyncWorldEdit |

---

### Issue: Subcommands Not Blocked

This is expected behavior!

GetPerWorldPlugin blocks by plugin, not by individual command. If /mcmmo is blocked, all mcMMO commands are blocked:
- /mcmmo
- /mctop
- /mcstats
- /mining
- etc.

---

### Issue: High Memory/CPU Usage

Check 1: Disable debug mode
yaml<br> debug: false<br>

Check 2: Reduce restriction count if excessive

Check 3: Ensure you're on Paper (not Spigot)

---

## FAQ

### Q: Does this actually disable the plugin per world?

A: No. The plugin is still loaded and running. GetPerWorldPlugin only blocks commands from executing in restricted worlds. Background features (like mcMMO passive skills) may still function.

---

### Q: Can I block vanilla commands?

A: No. Vanilla commands don't belong to any plugin, so they cannot be identified and restricted. Use a permissions plugin for vanilla commands.

---

### Q: Does this work with command aliases?

A: Yes! When you type /mctop, GetPerWorldPlugin traces it back to mcMMO and applies mcMMO's restrictions.

---

### Q: What happens to scheduled tasks/events from blocked plugins?

A: Only commands are blocked. Plugin events, scheduled tasks, and listeners still function. This plugin is specifically for command restriction.

---

### Q: Can I restrict specific commands instead of entire plugins?

A: Not with this plugin. GetPerWorldPlugin restricts at the plugin level. For command-level control, use a permissions plugin like LuckPerms with context.

---

### Q: Does this work with BungeeCord/Velocity?

A: This is a server-side plugin. It works on each individual server. For network-wide restrictions, configure it on each server separately.

---

### Q: Is there a GUI?

A: No. Configuration is done through config.yml only. This keeps the plugin lightweight and simple.

---

### Q: Can players see they're being blocked?

A:
- Execution: Yes, they see the blocked message
- Tab Complete: No, commands are hidden (invisible restriction)

---

### Q: What's the performance impact?

A: Minimal. The plugin uses caching and efficient lookups. Typical overhead is less than 0.1ms per command.

---