MapManager-Core v4

MapManager-Core is a map management plugin for Paper creative and building servers. It manages map metadata, roles, and access, uses Multiverse-Core for world operations, and synchronizes builder permissions with LuckPerms.

v3 is no longer supported. Please use v4 for future updates and fixes.

Features

• Create maps, import existing worlds, initialize maps, and safely delete them.
• Manage admins and builders by map group, with visitors assigned to individual maps.
• Configure public access, display names, spawn points, block physics, and explosion damage.
• Check access during teleports, login, respawn, and after role removal.
• Load active maps on demand when players teleport to them.
• Store map and role data in JSON or MySQL.
• Migrate v3 map and role data.
• Resume interrupted world operations from saved recovery requests and retry pending LuckPerms synchronization.

Installation

Install compatible versions of:

• Paper.
• LuckPerms.
• Multiverse-Core.
• VoidGen when creating or importing void maps.

The project targets Java 21 and declares Minecraft API version 1.20. The selected server and dependencies must also support your runtime.

Stop the server and back up your worlds, LuckPerms data, and plugins/MapManager-Core/. Place the v4 plugin JAR in plugins/, remove any older MapManager-Core JAR, and start the server.

On first start, the plugin generates config.yml and language files in plugins/MapManager-Core/. The default JSON backend stores data in maps.json.

The plugin creates the LuckPerms worldbase group if it is missing. Existing worldbase configuration is preserved.

Upgrading from v3

Before starting v4, keep both old files in plugins/MapManager-Core/:

• worlds.json
• groups.json

With the default configuration, v4 detects these files during startup, backs them up, and migrates their data. Migration errors prevent the plugin from enabling. Once migration is complete, subsequent starts do not repeat it.

To preview migration before applying it, set migration.dry-run: true before starting v4. Review v3-migration-report.json, then run /mapadmin migration apply from the console.

Map Roles

Set the map group with group=<id> when creating or importing a map. Maps in the same group share admins and builders; visitor lists and map settings remain separate.

Public maps allow all players to enter without creating visitor grants or providing builder permissions.

MMC roles and public access determine map entry. OP status and LuckPerms multiverse.access.<map> permissions do not replace MMC roles. Player commands do not require custom Bukkit permission nodes.

The Multiverse default world always permits entry. MMC does not apply map roles, per-map physics or explosion settings, or worldbase permission projection to that world.

Configure LuckPerms Groups

worldbase

MMC gives map admins and builders world-specific access to worldbase through their map group.

Add permissions that builders should receive inside their maps, such as WorldEdit or permissions from your protection plugin:

/lp group worldbase permission set worldedit.selection.pos true

If missing, worldbase is created with inheritance from default. Specific building permissions must be configured by the server administrator.

MapManager-Core manages map membership and access. Block placement and breaking protection are provided by your protection plugins.

MMC saves role changes before synchronizing them with LuckPerms. If synchronization is pending, the MMC role has already taken effect; the permission queue retries in the background and survives restarts.

Configuration

Configuration is stored in plugins/MapManager-Core/config.yml.

The following excerpt shows the main settings:

language: zh_CN

storage:
  type: json
  mysql:
    host: localhost
    port: 3306
    database: mapmanager
    username: mapmanager
    password: change-me
    use-ssl: true

deletion:
  allowed-world-name-regex: '.*_bak$'

creation:
  blocked-world-name-regex: '.*_bak$'

access-control:
  strict-map-entry: true

• language supports zh_CN and en_US. Editable language files are stored in langs/.
• storage.type supports json and mysql. For MySQL, create the database and account first; the plugin creates the tables.
• Switching an existing storage backend or MySQL target requires an explicit storage migration.
• strict-map-entry enables automatic access checks for external teleports, login, respawn, world changes, and role removal. Disabling it does not disable access checks in /world tp or /wtp.
• Both name patterns match the entire map name. By default, creation and import reject names ending in _bak, while the delete command only accepts that suffix.

Restart the server after changing configuration.

Physics, explosions, and public access are configured per map. Changes made through map commands are saved automatically.

Usage

Create a map and assign an admin from the console or through RCON:

/mapadmin create buildworld flat normal alias=BuildWorld group=buildteam admin=Steve

Use admin= to add a map-group admin. If omitted, no new admin is assigned; an existing group's admins still apply.

Steve can enter the map:

/wtp buildworld

While inside the map, an admin can manage members and settings:

/world builder add Alex
/world visitor add Pat
/world setspawn
/world setname Building World
/world public true

Newly created and imported maps are private, with physics and explosion damage disabled. Running init also disables physics and explosions while preserving public access and roles.

Enabling physics or explosions requires confirmation within 10 seconds:

/world physics true
/world physics true confirm

/world explosion true
/world explosion true confirm

Disabling either setting requires no confirmation.

Commands

<...> is required and [...] is optional.

Player Commands

Member changes and setting commands apply to the current map and require its MMC admin role. Players allowed to enter the map can view its role lists.

Console and RCON Commands

These commands are restricted to the console and RCON. Players, including OPs, cannot execute them. Results and deletion confirmation codes are written to the server console.

Deletion checks protected worlds, online players, map state, and directory safety in addition to the configured name pattern.

Storage exports do not replace a complete backup of the plugin directory, world files, and database.

Creation and Import Options

Generator types:

• flat: flat terrain; the default.
• normal: standard vanilla terrain.
• void: void terrain; requires VoidGen.

Supported environments are normal, nether, and the_end. The default is normal. The reserved environment sift is currently unsupported.

Map names must contain 4–16 lowercase letters, digits, underscores, or hyphens. Group IDs must contain 1–16 of the same characters and cannot be default or worldbase. Reserved and configured blocked map names are rejected.

flat.height is only available for flat and cannot be combined with generator-settings. It specifies the grass surface's absolute Y coordinate, within the target world's actual height range.

Import accepts generator type and environment, plus alias, group, and admin. It does not accept generation parameters.

The imported world must be directly inside the server root directory and contain valid level.dat data. Worlds with a newer data version than the server are rejected. Existing chunks are preserved; the selected generator and environment configure the world and subsequent generation.

/mapadmin import oldbuild normal normal group=buildteam admin=Steve