CoreExtractionX Configuration Reference

0. Before You Configure

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

1. 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.

2. 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.

3. 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.

4. `config.yml`

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

# ============================================================
# 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.

5. `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.

# ============================================================
# 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.

6. `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.

7. `plugin.yml`

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

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

8. Permissions

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

If a rule permission is absent or blank, settings.permission is used. If the resolved permission is blank, no permission is required.

9. Troubleshooting Quick Reference

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.

Reload failed

Check console for a fatal global enum error.
Fix 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.

10. Production Validation Checklist

Run /cex reload.
Confirm loaded/skipped counts are expected.
Mine one default ore from each section.
Test a wrong tool and a Silk Touch tool.
Test permissions with a non-op account.
Test protection compatibility with a cancelled block break.
Restart once after replacing the jar.

Configuration Reference