Skip to content

Configuration reference

Configuration contracts

For first-time setup and a plain-language file map, see the server admin quick guide. Configuration is read when Paper starts; restart Paper after edits. Existing config.yml, scopes.yml, and general-xp.yml receive missing shipped defaults on startup, while existing skills.yml, items.yml, and world-access.yml are deliberately preserved and are not automatically merged. Back up files before changing balance or applying a preset.

Command aliases

Add optional server-specific command labels under commands.<plugin.yml-command>.aliases in config.yml. Use bare labels without /:

commands:
  mcprogression:
    aliases: [levels, level]
  skills:
    aliases: [myskills]
  mcpadmin:
    aliases: [leveladmin]

This adds /levels, /level, /myskills, and /leveladmin; the built-in /mcprogression, /mcp, /skills, /mcpadmin, and /mcpa commands remain available. Aliases call the same handlers, permission checks, and tab completion as their built-in command. This setting works for each command declared by McProgression in plugin.yml, including commands added in future releases.

Paper does not let an alias take over a command already registered by Minecraft or another plugin. Conflicting aliases are skipped and listed in the startup log. Labels may contain letters, digits, _, and -; invalid labels are skipped with a warning. Unknown command names under commands are also reported and ignored. Restart Paper after editing aliases; existing config.yml files receive these defaults automatically during startup.

Skills and XP

skills.yml is the source of truth for enabled skills, level caps, award sources, and balance. The ten shipped skills are Mining, Farming, Woodcutting, Combat, Cooking, Smithing, Fishing, Crafting, Agility, and Herblore. Each skill supports an independent maximum level and one of three XP curves:

  • linear: XP required to advance at level L is base + growth * (L - 1).
  • quadratic: XP required to advance is base + growth * (L - 1)^2.
  • explicit: xp.thresholds.<level> stores the exact cumulative XP threshold.

These starter values are tunable proposals. Test the pacing on your server before treating them as a balanced curve. McProgression can award configured XP for block breaks, mature crops, breeding and taming, player-attributed mob/player kills, fishing, cooking, smithing, crafting, travel, exploration, and jumping. Global XP is persisted in the configured YAML, SQLite, MySQL, or PostgreSQL backend, with per-world award totals available for scoped leaderboards. The startup audit reports enabled activities that are not supported, and those activities do not award XP. The optional tool-tier modifier scales block-break XP and is capped by configuration. See Agility discovery and jump XP and General XP for details.

The project should keep XP award rules, level thresholds, ranks, and item requirements independent. A custom skill can be added in configuration without code edits when its event type is already supported; a new event type still needs an adapter implementation.

Combat mob-kill XP is configured per entity under skills.yml; anti-abuse.spawn-reason-xp adjusts it by spawn reason. Percentages use 100 for normal XP, 10 for 10%, and 0 to disable that reason. The shipped settings grant regular, trial, and ominous spawner mobs 10% of normal mob XP. default-percent applies when no reason override exists, and any runtime CreatureSpawnEvent.SpawnReason can be configured by enum name. Reason names are stored in entity persistent data, so the source survives chunk unloads and restarts. Entities already alive before this tracking is installed have no known reason and use default-percent. The older mob-spawner-kills option remains a fallback only when an explicit reason percentage is absent. Indirect damage and player-kill XP have separate policies.

World and ranking scopes

scopes.yml keeps player progression global by default while allowing leaderboards to select:

  • one global server scope covering configured worlds;
  • one scope per exact world name; or
  • any number of named world groups, each with an explicit world list.

A world can participate in more than one board. No world-name pattern matching is implicit. Player profiles are currently global; scopes.yml changes leaderboard views only.

The shipped default-skills field was removed because no current leaderboard command reads it; choose a skill explicitly with /mcp top <skill> [leaderboard] [page]. Existing deployed copies may retain the old field, but it has no effect. The separate tablist section controls Paper player-list ordering.

Item policy

items.yml has a configurable default action policy and exact per-material overrides. The player-attributed adapters expose CRAFT, PLACE, BREAK, STRIP, USE, SHOOT, CONSUME, PICKUP, CONTAINER, STORE, ACQUIRE, DROP, EQUIP, SMELT, BREW, ENCHANT, REPAIR, ANVIL, GRIND, TRADE, SMITH, STONECUT, CARTOGRAPH, and LOOM. Actorless automation has separate settings: furnace-family recipes, Crafter output, generic inventory transfers, brewing, and dispenser actions all default to deny-gated; furnace and brewing also support station-owner. See each key under progression.automation in config.yml and the automation policy. Rules may require every condition in all-of, or any condition in any-of; each condition references a skill and minimum level.

On startup and /mcpadmin audit, the plugin regenerates plugins/McProgression/material-policy-runtime.csv from the actual running Paper Material enum. It contains one row per material and action-policy columns for all three packaged presets plus the current active files, along with item/block status, the 26.3 catalog check and the event adapter map. The CSV is an exhaustive material/action register; it does not claim that every visual variant or event path has been client-tested.

The distinction between possession and use is intentional: the same item may be craftable at level 0, but using it can require one or several skills. Built-in starter rules and presets leave EQUIP unrestricted so players can freely select and carry items; crafting and actual use can still have skill requirements. Server owners can add an EQUIP rule when they explicitly want to restrict selection or wearing gear. Selecting a hotbar slot is an EQUIP action; a denied selection snaps back, and repeated denial notices are rate-limited by chat-output.equip-denial-cooldown-seconds (default 2 seconds). Existing items.yml files are preserved on upgrade, so existing servers should remove unwanted EQUIP entries manually or apply a preset. Remaining enforcement boundaries include death drops, commands, loot, and direct plugin inventory writes, which do not share one cancellable actor-aware event. The current starter policy defaults unlisted items to allowed so a missing rule does not unexpectedly make the server unplayable.

Station behavior should be recipe-scoped where possible. The furnace starter example leaves crafting/placement open, unlocks charcoal at Smithing 1, and food recipes at Cooking 10. Level-zero ore and processing outputs provide the Smithing XP path. Campfires provide the level-zero Cooking path and smokers unlock at Cooking 5. These are configurable example defaults, not final balance approval.

Upgrade and configuration audit

The compatibility warning compares the server's Minecraft version with:

  • minimum-supported-version: the declared minimum runtime line;
  • maximum-validated-version: the newest version that has passed the required compatibility matrix;
  • a bundled material catalog used to flag items that may need review on newer server versions.

The configured minimum and validated versions are shown in config.yml. McProgression warns when the server is newer than the configured validated version; the warning does not prevent startup. Review the warning and run /mcpadmin audit after changing server versions.

At startup and with /mcpadmin audit, McProgression checks version settings, CoreProtect availability, skill and XP settings, leaderboard worlds, item requirements, and compatibility gaps between enabled settings and supported features. It also flags materials introduced by newer Minecraft versions for review.

Findings are warnings, not automatic changes or server shutdowns. They are logged at startup and summarized to players with permission mcprogression.admin.alerts (default false, including for operators). Grant that node only to staff who should receive configuration and compatibility alerts.

Check compatibility warnings after a server update and run /mcpadmin audit before opening the server to players.