Complete configuration reference

Configuration Reference

Complete CoreExtractionX YAML references, first setup path, reload boundaries, runtime model, permissions, troubleshooting, and production checks.

0. Before You Configure

Minimum requirements are Paper 1.21.11+, Java 21+, and CoreExtractionX installed on a Paper server. Configure and test extraction rules on a staging world before enabling broad custom behavior on a live server.

CoreExtractionX is Paper-only and designed for survival mining. It does not add progression, economy, GUI, vein mining, auto mining, or a protection-plugin dependency.

1. First Setup Flow

  1. Stop the server and place the CoreExtractionX jar in the server plugins folder.
  2. Start the server once so CoreExtractionX generates config.yml, ores.yml, and messages.yml.
  3. Join a staging world and mine a default ore before editing anything. This confirms the jar, Paper version, Java version, and permissions are working.
  4. Edit ores.yml first when you want to change what happens to mined blocks.
  5. Edit config.yml only when you need global permission behavior, Silk Touch behavior, world filtering, drop spawn behavior, replacement physics, or XP preservation.
  6. Edit messages.yml only when you want to change command and status messages.
  7. Run /cex reload or /coreextractionx reload.
  8. Check the reload message and server console for loaded/skipped rule counts and warnings.
  9. Test with a normal tool, a Silk Touch tool, a non-op player, and a protected region if your server uses protection plugins.

2. Which File To Edit

  • ores.yml is the main file for day-to-day setup. Use it for source blocks, replacement blocks/items, extraction mode, DROP amounts, optional per-rule permissions, and optional per-rule Silk Touch behavior.
  • config.yml is for global runtime behavior. Settings here affect every rule unless a rule explicitly overrides the relevant option.
  • messages.yml is for text shown by the plugin. MiniMessage tags use angle brackets, while CoreExtractionX placeholders use braces such as {loaded} and {skipped}.
  • plugin.yml is bundled inside the jar. It is useful as a reference for commands, aliases, permissions, and plugin metadata, but it is not a file you edit in the server plugin folder.

File Layout

plugins/CoreExtractionX/
  config.yml
  ores.yml
  messages.yml

inside CoreExtractionX jar:
  plugin.yml

config.yml, ores.yml, and messages.yml are generated under the plugin data folder. plugin.yml is bundled inside the jar and documents commands, aliases, permissions, and plugin identity.

3. Reload vs Restart

Use /coreextractionx reload or /cex reload for normal YAML edits. Restart when replacing the jar, changing Paper/Minecraft version, or validating a clean boot.

Fatal global enum errors safe-disable extraction logic, but reload commands remain available so the config can be fixed without a full restart.

4. Runtime Model

CoreExtractionX only runs for survival players. World filtering can allow all worlds, whitelist specific worlds, or blacklist specific worlds. Cancelled block break events are ignored.

  • Only players in SURVIVAL are handled. Creative, spectator, and adventure behavior stays vanilla.
  • If another plugin cancels the block break first, CoreExtractionX does nothing. This keeps protection plugins in control.
  • REPLACEMENT mode reads natural drops once, cancels the vanilla break, replaces the block, damages the main-hand tool normally, spawns the preserved drops manually, and can preserve vanilla XP as orbs.
  • DROP mode lets the block break normally, then adds the configured replacement item stacks after vanilla drops are generated.
  • Invalid enabled block rules are skipped with warnings, while valid rules continue loading.
  • Fatal global config enum errors safe-disable extraction logic, but the reload command stays available.

5. Common Starter Changes

When adding a new rule, copy the fully documented disabled stone template in ores.yml, rename the key to the source block material, then set enabled: true after the values are valid.

Disable one default ore

blocks:
  diamond_ore:
    enabled: false

Replace a mined block in the world

blocks:
  copper_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: STONE

Add one extra item in DROP mode

blocks:
  stone:
    enabled: true
    mode: DROP
    replacement: GRAVEL
    drop:
      amount-mode: FIXED
      fixed-amount: 1

Require a permission for one rule

blocks:
  ancient_debris:
    permission: "coreextractionx.extract.ancient_debris"

Disable CoreExtractionX in specific worlds

world-filter:
  mode: BLACKLIST
  worlds:
    - creative_world
    - event_world

6. config.yml

Complete bundled default for global runtime settings, permission behavior, Silk Touch behavior, world filtering, manual drop location, replacement physics, and XP preservation.

Edit this file carefully because global enum mistakes are fatal config errors. When that happens, extraction logic safe-disables until the config is fixed and reloaded.

# ============================================================
# CoreExtractionX configuration
# ============================================================
#
# This file contains only global runtime settings.
# Edit ores.yml for block extraction rules.
# Edit messages.yml for player-facing messages.

config-version: 1

settings:
  enabled: true
  debug: false

  # CoreExtractionX only runs for SURVIVAL players.
  # This is intentionally not configurable in v1.

  # Global permission required to use CoreExtractionX.
  # If empty, no global permission is required.
  #
  # Per-block permission overrides can be configured inside each rule in ores.yml.
  # If a block-specific permission is missing or empty, this global permission is used instead.
  permission: "coreextractionx.use"

  # What should happen when a player does not have the required permission?
  #
  # VANILLA = CoreExtractionX does nothing and the block breaks normally.
  # DENY    = the block break is cancelled.
  no-permission-behavior: VANILLA

  # What should happen when the player uses a Silk Touch tool?
  #
  # VANILLA = CoreExtractionX does nothing and vanilla handles the block break.
  # DENY   = the block break is cancelled.
  silk-touch-behavior: VANILLA

world-filter:
  # DISABLED  = CoreExtractionX works in every world.
  # WHITELIST = CoreExtractionX works only in the listed worlds.
  # BLACKLIST = CoreExtractionX works in every world except the listed worlds.
  mode: DISABLED

  worlds: []

  # Example:
  # mode: BLACKLIST
  # worlds:
  #   - disabled_world
  #   - creative_world

  # Example:
  # mode: WHITELIST
  # worlds:
  #   - world
  #   - world_nether

# Controls where CoreExtractionX manually spawns items.
drop-spawn:
  # HIT_FACE     = drops are spawned near the face of the block the player is looking at.
  # BLOCK_CENTER = drops are spawned at the broken block center.
  mode: HIT_FACE

  # Max raytrace distance used to find the block face.
  raytrace-distance: 6.0

  # Offset applied from the block center toward the hit face.
  face-offset: 0.75

replacement:
  # Whether block physics should be applied when setting the replacement block.
  # false is recommended to avoid unwanted block updates.
  apply-physics: false

experience:
  # In REPLACEMENT mode, CoreExtractionX cancels vanilla block breaking
  # after reading the original vanilla XP. When enabled, it respawns that XP as orbs.
  preserve-vanilla-exp: true

Global enum mistakes are fatal config errors. When that happens, extraction logic safe-disables but reload commands remain available.

7. ores.yml

Complete bundled default for block extraction rules. Keys under blocks: are dynamic material names. Disabled rules are skipped before material validation so the included template can stay harmless.

This is the file most server owners edit first. Block keys are Bukkit/Paper Material names, read case-insensitively. A source key must be a valid block material when the rule is enabled. In REPLACEMENT mode, replacement must be a block material. In DROP mode, replacement must be an item material.

# ============================================================
# CoreExtractionX ore and block extraction rules
# ============================================================
#
# This file controls which blocks CoreExtractionX handles when mined.
# Global behavior defaults are configured in config.yml.
# Player-facing messages are configured in messages.yml.
#
# Block keys are dynamic.
# Any valid block material can be added here.
#
# Material names must be valid Bukkit/Paper Material enum names.
# Block keys are read case-insensitively and should be lowercase by convention.
#
# Each enabled block rule uses one mode:
#
# REPLACEMENT:
#   The mined source block is replaced in the world by another block.
#   CoreExtractionX manually spawns the source block's natural drops.
#
# DROP:
#   The mined source block breaks normally.
#   CoreExtractionX adds an extra configured item drop after vanilla drops are generated.

blocks:

  # ------------------------------------------------------------
  # Fully documented rule template
  # ------------------------------------------------------------
  # This template is intentionally disabled.
  # Copy it when adding custom block rules.
  # Replace "stone" with the source block material you want to handle.

  stone:
    enabled: false

    # REPLACEMENT = replace the mined block in the world.
    # DROP        = let the block break normally and add an extra replacement item drop.
    mode: REPLACEMENT

    # In REPLACEMENT mode, this must be a valid block material.
    # In DROP mode, this must be a valid item material.
    replacement: COBBLESTONE

    # Optional.
    # If set, this permission is required for this specific block.
    # If missing or empty, settings.permission from config.yml is used instead.
    # permission: "coreextractionx.extract.stone"

    # Optional.
    # If missing or empty, settings.silk-touch-behavior from config.yml is used instead.
    # Valid values: VANILLA, DENY.
    # silk-touch-behavior: VANILLA

    # DROP-mode-only settings.
    # Ignored in REPLACEMENT mode.
    drop:
      # FIXED          = always drops fixed-amount.
      # RANDOM         = drops a random amount between min-amount and max-amount.
      # MATCH_DROPS    = matches the correct generated drop quantity of the block, ignoring later extra plugin drops.
      # MATCH_QUANTITY = matches the total quantity of all item drops currently present when CoreExtractionX calculates it.
      amount-mode: FIXED

      # Used only with FIXED.
      # If missing, defaults to 1.
      fixed-amount: 1

      # Used only with RANDOM.
      # min-amount may be 0.
      # max-amount must be >= 1 and >= min-amount.
      min-amount: 1
      max-amount: 3

      # Used only with RANDOM.
      # If true, final amount = randomBaseAmount * max(1, fortuneLevel + 1).
      fortune-multiplier: false

      # Used only with RANDOM.
      # 0 means no cap.
      max-final-amount: 0

  # ------------------------------------------------------------
  # Overworld stone ores
  # ------------------------------------------------------------

  coal_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLESTONE
    # permission: "coreextractionx.extract.coal_ore"
    # silk-touch-behavior: VANILLA

  copper_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLESTONE
    # permission: "coreextractionx.extract.copper_ore"
    # silk-touch-behavior: VANILLA

  iron_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLESTONE
    # permission: "coreextractionx.extract.iron_ore"
    # silk-touch-behavior: VANILLA

  gold_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLESTONE
    # permission: "coreextractionx.extract.gold_ore"
    # silk-touch-behavior: VANILLA

  redstone_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLESTONE
    # permission: "coreextractionx.extract.redstone_ore"
    # silk-touch-behavior: VANILLA

  lapis_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLESTONE
    # permission: "coreextractionx.extract.lapis_ore"
    # silk-touch-behavior: VANILLA

  diamond_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLESTONE
    # permission: "coreextractionx.extract.diamond_ore"
    # silk-touch-behavior: VANILLA

  emerald_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLESTONE
    # permission: "coreextractionx.extract.emerald_ore"
    # silk-touch-behavior: VANILLA

  # ------------------------------------------------------------
  # Deepslate ores
  # ------------------------------------------------------------

  deepslate_coal_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLED_DEEPSLATE
    # permission: "coreextractionx.extract.deepslate_coal_ore"
    # silk-touch-behavior: VANILLA

  deepslate_copper_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLED_DEEPSLATE
    # permission: "coreextractionx.extract.deepslate_copper_ore"
    # silk-touch-behavior: VANILLA

  deepslate_iron_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLED_DEEPSLATE
    # permission: "coreextractionx.extract.deepslate_iron_ore"
    # silk-touch-behavior: VANILLA

  deepslate_gold_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLED_DEEPSLATE
    # permission: "coreextractionx.extract.deepslate_gold_ore"
    # silk-touch-behavior: VANILLA

  deepslate_redstone_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLED_DEEPSLATE
    # permission: "coreextractionx.extract.deepslate_redstone_ore"
    # silk-touch-behavior: VANILLA

  deepslate_lapis_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLED_DEEPSLATE
    # permission: "coreextractionx.extract.deepslate_lapis_ore"
    # silk-touch-behavior: VANILLA

  deepslate_diamond_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLED_DEEPSLATE
    # permission: "coreextractionx.extract.deepslate_diamond_ore"
    # silk-touch-behavior: VANILLA

  deepslate_emerald_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: COBBLED_DEEPSLATE
    # permission: "coreextractionx.extract.deepslate_emerald_ore"
    # silk-touch-behavior: VANILLA

  # ------------------------------------------------------------
  # Nether ores
  # ------------------------------------------------------------

  nether_quartz_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: NETHERRACK
    # permission: "coreextractionx.extract.nether_quartz_ore"
    # silk-touch-behavior: VANILLA

  nether_gold_ore:
    enabled: true
    mode: REPLACEMENT
    replacement: NETHERRACK
    # permission: "coreextractionx.extract.nether_gold_ore"
    # silk-touch-behavior: VANILLA

  ancient_debris:
    enabled: true
    mode: REPLACEMENT
    replacement: BLACKSTONE
    # permission: "coreextractionx.extract.ancient_debris"
    # silk-touch-behavior: VANILLA

REPLACEMENT requires a replacement block. DROP requires a replacement item. Invalid enabled rules are skipped with a specific warning and do not block valid rules.

8. messages.yml

Complete bundled default for player-facing messages. Messages use Adventure MiniMessage, while plugin placeholders use {name} syntax to avoid conflicts with MiniMessage tags.

# CoreExtractionX messages.
#
# Messages use Adventure MiniMessage syntax.
# Plugin placeholders use {name} syntax to avoid conflicts with MiniMessage tags.
# Leave a message empty to disable it.

no-permission: "<red>You cannot extract this block.</red>"
silk-touch-denied: "<red>You cannot mine this block with Silk Touch.</red>"
reload-success: "<green>CoreExtractionX reloaded. Loaded {loaded} rules, skipped {skipped} invalid rules.</green>"
reload-failed: "<red>CoreExtractionX reload failed. Extraction logic has been disabled. Check console for details.</red>"
command-no-permission: "<red>You do not have permission to reload CoreExtractionX.</red>"
help-main: "<gray>/coreextractionx reload</gray>"
help-alias: "<gray>/cex reload</gray>"

Leave a message empty to disable it.

9. plugin.yml

Complete bundled plugin descriptor. Maven resolves ${project.version} when the release jar is built.

This descriptor is packaged inside the jar and should be treated as read-only by server owners.

name: CoreExtractionX
main: it.icewolf23x.coreextractionx.CoreExtractionX
version: ${project.version}
api-version: '1.21'
description: Config-driven block extraction and replacement rules for Paper.
author: IceWolf23X
prefix: CoreExtractionX
commands:
  coreextractionx:
    description: CoreExtractionX main command.
    usage: /coreextractionx
    aliases:
      - cex
permissions:
  coreextractionx.reload:
    description: Allows reloading CoreExtractionX configuration.
    default: op
  coreextractionx.use:
    description: Allows using CoreExtractionX extraction rules.
    default: true

10. Permissions

coreextractionx.reload
coreextractionx.use
coreextractionx.extract.<block>   # optional per-rule example

coreextractionx.reload is operator-only by default. coreextractionx.use is the default global runtime permission and is declared with default: true in plugin.yml. If your server uses a permission plugin such as LuckPerms, assign or deny it there as needed.

Per-rule permissions configured in ores.yml are optional and do not need to be predeclared in plugin.yml. If a rule does not define a permission, CoreExtractionX falls back to settings.permission in config.yml. If the resolved permission is blank, no permission is required.

no-permission-behavior: VANILLA makes unauthorized mining behave like normal Minecraft. DENY cancels the block break instead.

11. Troubleshooting Quick Reference

No files generated

  • Confirm the jar is in the server plugins folder.
  • Confirm the server is running Paper 1.21.11+ on Java 21+.
  • Check the startup log for plugin load errors.

Command works but extraction is disabled

  • Check the console for fatal global config enum errors.
  • Fix the value in config.yml, then run /cex reload.
  • Confirm settings.enabled: true.

Rule does nothing

  • Check the source block key resolves to a real block material.
  • Confirm enabled: true.
  • Confirm the world filter allows the world.
  • Check permissions and Silk Touch behavior.

Rule is skipped on reload

  • Read the console warning for the exact rule key and invalid field.
  • For REPLACEMENT, use a block material as the replacement.
  • For DROP, use an item material as the replacement and validate the drop amount settings.

Block breaks but no replacement appears

  • Confirm the rule is using mode: REPLACEMENT.
  • Confirm no protection plugin cancelled the block break first.
  • Confirm the player is in survival mode and the world passes the filter.

Silk Touch bypasses extraction

  • This is expected when Silk Touch behavior is VANILLA.
  • Use DENY globally or on a specific rule if Silk Touch mining should be blocked for that extraction behavior.

Protection plugin compatibility

  • CoreExtractionX ignores already-cancelled block breaks.
  • If a region, claim, or world protection plugin denies mining, CoreExtractionX should not replace blocks or add drops.

Drops spawn in an unexpected spot

  • Use drop-spawn.mode: BLOCK_CENTER for predictable center spawning.
  • Use HIT_FACE when you want drops to appear closer to the face the player is mining.

Reload failed

  • Fix YAML indentation first.
  • Then fix fatal global enum values such as no-permission-behavior, silk-touch-behavior, world-filter.mode, or drop-spawn.mode.
  • Run /cex reload again.

Drops appear in the wrong amount

For DROP mode, check drop.amount-mode. MATCH_DROPS uses the initial generated drop quantity; MATCH_QUANTITY uses the current event item quantity at CoreExtractionX handling time.

12. Production Validation Checklist

  • Back up config.yml, ores.yml, and messages.yml.
  • Run /cex reload.
  • Confirm loaded/skipped counts are expected.
  • Mine one default ore from each ore section you use.
  • Test at least one custom rule.
  • Test a wrong tool, Fortune tool, and Silk Touch tool.
  • Test permissions with a non-op account.
  • Test allowed and blocked worlds if world filtering is enabled.
  • Test protection compatibility with a cancelled block break.
  • Restart once after replacing the jar.