Server admin quick guide

This guide is the starting point for installing and configuring McProgression on a Minecraft server running Paper.

Quick setup

1. Back up the server and install the McProgression JAR in plugins/. Install LuckPerms if you want staff commands. CoreProtect and WorldGuard are optional integrations.
2. Start Paper once to generate plugins/McProgression/, then stop the server before editing YAML.
3. Set branding.display-name, language, and time-zone in config.yml. Choose progression-presets.default (open, progressive, or long-form) before players earn progress. Keep SQLite for one server; plan any backend choice before players earn progress, and see storage before using SQL.
4. Review skills.yml and general-xp.yml. Edit items.yml or world-access.yml only if you want to add restrictions.
5. With LuckPerms, grant a trusted admin mcprogression.admin.audit; OP status alone does not grant McProgression staff access. Start Paper, check the console for warnings, run /mcpadmin audit, then test player and staff flows before opening the server.

Restart Paper after changing plugin configuration; McProgression has no reload command. Avoid Bukkit's /reload.

Minimum staff permissions

Players need no McProgression permission. Admin, reset, import, and bypass permissions default to false, including for operators. With LuckPerms, give a staff group only the actions it needs. For example, this grants an audit-only role:

lp creategroup progression-auditor
lp group progression-auditor permission set mcprogression.admin.audit true
lp user PlayerName parent add progression-auditor

Add mcprogression.admin.alerts only if the group should receive audit alerts. Preset review/apply, XP reports, reset, reset-sync, and CoreProtect preview/apply each have separate permissions. See the full permission matrix and LuckPerms examples before granting them; avoid wildcard grants.

Set branding.display-name in config.yml to customize the name shown in built-in player-facing messages and menus. The same value is used for Discord webhook usernames and default text; set integrations.discord-webhooks.username to a non-empty value to override it. This changes display text only; the JAR, data folder, commands, permissions, and PlaceholderAPI identifiers keep their technical names.

Set extra public, skill, or staff command names in config.yml under commands.<command-name>.aliases. For example, commands.mcprogression.aliases: [levels] adds /levels; the existing commands remain available. See the command alias reference for all three command roots and collision behavior. Restart Paper after editing.

Which file should I edit?

Most servers only need to start with config.yml, skills.yml, and general-xp.yml. Edit items.yml or world-access.yml only when you want to restrict actions or access.

How config updates work

McProgression preserves an existing server's progression choices during upgrades. It copies a missing file from the plugin jar, but it does not replace an existing configuration with the new defaults.

• New default settings are merged into existing config.yml, scopes.yml, and general-xp.yml while preserving values already set by the server.
• Existing skills.yml, items.yml, and world-access.yml are intentionally left as-is. Compare these files with the release's shipped examples when a new option is announced, and add it manually if you want it.
• Upgrade files are not automatically cleaned: removed or unknown keys may remain in older files, but settings that are no longer supported have no effect.
• Applying a starter preset intentionally replaces skills.yml, items.yml, and world-access.yml. Preview it first; application makes a backup and requires a restart.
• Never delete progression.db, progress.yml, or your configured SQL tables as a way to reset a config. Those contain player progression data.

Preview starter profiles safely

The starter profiles are examples with different unlock policies. They do not change player XP formulas or account data when previewed.

/mcpadmin preset list
/mcpadmin preset preview progressive

If you want to apply one, back up the plugin folder and then run:

/mcpadmin preset apply progressive

Applying a preset replaces its three gameplay files, writes a timestamped backup, and asks for a restart. Existing player progress remains in the selected storage backend. Review the preview's skill and access changes before applying.

Common changes

Change the daily boundary for XP and login rewards

Set the IANA timezone in the top-level config.yml setting time-zone, for example Europe/Brussels or UTC. This controls daily skill XP caps, General XP caps, join rewards, and login streak days. Use a timezone name rather than a fixed UTC offset so daylight-saving changes are handled.

Discord event timestamps have their own integrations.discord-webhooks.timezone setting. Changing it does not change when XP caps or login streaks reset.

Tune skill XP

In skills.yml, find a skill ID, then its activity under activities. Set the activity's xp, enabled, and, where supported, its materials, entities, or xp-by-material values. A per-material value overrides the activity's general xp; materials not listed use the general value. Setting a skill/activity to disabled stops its awards.

The xp object under a skill controls its level curve, not the amount granted by an activity. linear, quadratic, and explicit curves are described at the top of skills.yml. Treat the shipped rates as a starting balance, then verify with /mcprogression help <skill> and playtesting.

Add an item requirement

Add the exact material and action in items.yml. This example requires Mining 10 to craft a diamond pickaxe; other actions continue to use the configured fallback:

rules:
  DIAMOND_PICKAXE:
    actions:
      CRAFT:
        all-of:
          - skill: mining
            level: 10

Use all-of when every listed skill is required. Use any-of when meeting any one listed skill requirement should be enough. Check the runtime material-policy-runtime.csv after startup or /mcpadmin audit to review how the rules resolve on the current server.

Change Global Rank thresholds

In config.yml, edit global-rank.tiers. Each key (such as apprentice) is a stable tier ID; name is the displayed name and minimum-score is the required combined score. The score combines enabled skill levels and General XP converted by general-xp-per-score-point. Set that conversion to 0 if General XP should not affect Global Rank. Reward lists are optional and empty by default; see progression rewards.

Safe-editing checklist

• Keep a dated copy of the plugin configuration and database before changing progression balance or storage.
• Preserve YAML indentation and quote text containing :, #, {}, or special formatting.
• Keep skill IDs, tier IDs, and reward IDs stable after players have earned progress or rewards.
• Use /mcpadmin audit and resolve unexpected findings before opening the server to players.
• Do not enable a CoreProtect import until you have reviewed its preview and read the moderator progression guide.
• Do not paste real database passwords or Discord webhook URLs into public issue trackers or shared config examples.

More detail

• Configuration reference
• Death penalties
• Progression storage and database setup
• Agility discovery and jump XP
• General XP and login rewards
• Item, automation, and world gates
• Discord webhooks
• Command permissions and moderator controls