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

Role	Scope	What it can do
Admin	Map group	Manage members and settings for maps in the group. Admins also have builder and visitor access.
Builder	Map group	Enter maps in the group and receive permissions configured in worldbase for those worlds.
Visitor	Individual map	Enter the assigned map without receiving builder permissions.

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.

Command	Description
/world tp <map>	Teleport to an accessible active map, loading it if necessary.
/wtp <map>	Shortcut for /world tp.
/world admin add|remove <player-or-UUID>	Grant or revoke map-group admin access.
/world builder add|remove <player-or-UUID>	Grant or revoke map-group builder access.
/world visitor add|remove <player-or-UUID>	Grant or revoke visitor access to the current map.
/world admin info	List directly assigned admins.
/world builder info	List directly assigned builders.
/world visitor info	List directly assigned visitors.
/world public [true|false|info]	Set or view public access.
/world physics [true|false|info]	Set or view block physics. Enabling requires confirmation.
/world explosion [true|false|info]	Set or view explosion damage. Enabling requires confirmation.
/world setname <display-name>	Change the display name and Multiverse alias.
/world setspawn	Set the map spawn to your current position.
/world kick <online-player>	Send a player in the same map to the Multiverse default spawn.

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.

Command	Description
/mapadmin create <map> [type] [environment] [options...]	Create and initialize a map.
/mapadmin import <map> [type] [environment] [options...]	Import an existing world from the server root directory.
/mapadmin init <map>	Reapply initialization rules to a loaded MMC map.
/mapadmin delete <map>	Request deletion and receive a single-use six-character confirmation code.
/mapadmin delete <code>	Confirm deletion within 10 seconds.
/mapadmin load <map>	Load a registered active map.
/mapadmin recover <map>	Resume creation, import, or a previously confirmed deletion using its saved request.
/mapadmin operations	List unfinished and failed operations.
/mapadmin migration dry-run	Generate a v3 migration preview without importing data.
/mapadmin migration apply	Apply or resume v3 migration.
/mapadmin storage export <name>	Export map, role, and operation data to exports/<name>.json.

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.

Option	Description
alias=<text>	Display name; defaults to the map name.
group=<id>	Map group; defaults to the map name.
admin=<player-or-UUID>	Add a map-group admin.
flat.height=<Y>	Absolute surface Y coordinate for flat terrain.
seed=<number>	World seed.
structures=true|false	Whether to generate structures.
biome=<biome>	Generation biome.
generator=<generator>	Multiverse generator configuration.
generator-settings=<settings>	Generator settings.
property.<name>=<value>	Multiverse world property.

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