Skip to content

Item and enchantment unlock guide

Use this guide to answer two questions: what unlocks at a level? and what do I need to level to use a particular item or enchantment? The configuration builder provides both a level-by-level overview and a searchable item/action view. The search and preview run in your browser; imported YAML is not uploaded.

Start in the configuration builder

Open the configuration builder, choose a preset, or import the configuration files it recognizes: config.yml, general-xp.yml, skills.yml, items.yml, and world-access.yml. The level timeline and searchable unlock view follow the current items.yml editor state. Search by material, action, context, recipe, skill, or enchantment; inspect the requirements; then jump to the corresponding canonical YAML rule to change it. Level mode groups entries by skill and exact level while retaining the full AND/OR conditions. The player-level preview is illustrative and does not load a real player's server profile. Export and retain the files your server actually uses.

Use the level view when planning a skill ladder. Use item search when you know the item, action, or enchantment and want to find its requirement. Search results should show each action independently; for example, crafting an iron sword, equipping it, and attacking with it can have different rules.

How requirements are read

Item rules are keyed by vanilla material and action in items.yml:

rules:
  DIAMOND_SWORD:
    actions:
      CRAFT:
        all-of:
          - {skill: combat, level: 30}
      USE:
        all-of:
          - {skill: combat, level: 30}
      EQUIP:
        all-of:
          - {skill: combat, level: 30}

Each action is a separate gate. all-of means every listed condition is required; any-of means at least one listed condition is enough. Recipe and context rules can add narrower requirements to supported actions. The explorer shows the exact configured conditions rather than flattening them into a misleading single rank label.

Skill levels are authoritative for these requirements. A skill rank subtier is a friendly label derived from the skill's level thresholds, so the overview may show a label such as “Expert” alongside “Combat 30.” Global Rank is a separate overall score and does not grant an item unless a rule explicitly uses that system.

An action with no exact material/action rule inherits the configured coverage fallback. The shipped fallback is ALLOW; the explorer labels this “Allowed by server default,” not as an unlock at level 0. In the Open preset, skill-based item and world gates are bypassed. Progressive applies the shared gates, while Long-form uses the same gate levels with its slower configured XP curves.

Images, animation, and custom items

An image is illustrative; the material/action and requirement text remain the accessible source of truth. In Local item images, choose a resource-pack ZIP to preview vanilla textures, or enter a namespaced item/key ID and choose a PNG to map custom artwork. Text labels and action icons remain available as fallbacks. The ZIP and image data are processed locally in the browser and are not uploaded to the documentation site or sent to an image service. They remain in the current tab's memory; use Clear local images to remove them, or close the tab to discard them.

The importer accepts one ZIP up to 60 MB. Split archives and ZIP64 are unsupported. It reads relevant assets under assets/, with bounded entry count and expanded data size, and supports stored/deflate compression in a recent browser. Most resource packs only override some vanilla textures, so items without a matching texture use the normal text/initial fallback. The importer resolves direct texture files and common vanilla item/model references; it is a simplified preview, not Minecraft's full resource-pack renderer. .png.mcmeta frame animations are previewed when the texture and animation metadata use the supported vertical sprite layout. A static icon is used when animation data is missing or unsupported.

There is no 3D renderer, and advanced item-model predicates, blockstates, transforms, and all version-specific model behavior are not reproduced. The preview may differ from what a Minecraft client displays. A manually mapped PNG can use any namespaced ID, including custom item or key IDs, but that mapping is visual-only: it does not add a custom-item rule to McProgression or change enforcement.

The plugin's built-in item rules identify vanilla Bukkit/Paper materials. They cannot reliably distinguish two custom items that share a base material by display name or model appearance alone. A custom item needs a stable identifier and an integration that exposes that identifier to the policy engine before it can be shown as a truly enforceable custom-item rule. Keep custom-item art as a display mapping until that support exists.

Enforcement boundaries

The action label tells you which player operation is checked. It does not imply that every way to obtain or move an item is blocked. Commands, loot tables, direct plugin grants, and some automated inventory paths need explicit integrations. The item policy and supported player actions and automation policy document the current boundaries.

Enchanting has two distinct questions: whether a player can perform an enchantment operation on an item, and whether a particular enchantment may be newly applied. The broad ENCHANT item action and per-enchantment application requirements are displayed separately where configured. A newly enforced application rule does not remove enchantments players already own, and it does not automatically cover every plugin or command that modifies an item.

Per-enchantment gates are separately opt-in in items.yml. Keys use namespaced registry IDs. all-of conditions must all pass; if any-of is also present, at least one of those conditions must pass in addition to every all-of condition. An unlisted enchantment passes, and a disabled gate set has no effect:

enchantment-gates:
  enabled: true
  rules:
    minecraft:efficiency:
      any-of:
        - {skill: mining, level: 10}
        - {skill: woodcutting, level: 10}
    minecraft:mending:
      any-of:
        - {skill: smithing, level: 25}
        - {skill: mining, level: 25}

The shipped Progressive and Long-form presets include these example gates; Open explicitly disables them. Enchanting-table applications and enchantment levels increased by the anvil path are checked. Existing enchantments remain usable. Loot, trading, commands, direct plugin changes, and other unsupported paths are not covered by this setting.

Server-owner checklist

  1. Import the active server files before editing; do not export defaults over customized files.
  2. Search a material and inspect every relevant action, especially CRAFT, USE, and EQUIP.
  3. Check all-of/any-of, recipe/context conditions, and the fallback policy.
  4. Review the rank label together with the exact skill and level.
  5. Preview and export, back up the active files, then run /mcp audit and play-test each affected event on the server version you support.

The explorer describes configured policy. The runtime audit and in-game test establish whether the installed server can enforce each event path.