name: Overclock
main: com.goldwar.overclock.Overclock
version: 1.0.12
api-version: 1.21
author: GoldwarGlory
description: Optimize your server
website: /plugins/overclock-clearlag

commands:
  overclock:
    description: The main command for the plugin.
    usage: /overclock
    permission: overclock.admin
    aliases:
      - oc
      - overc
      - oclock

permissions:
  overclock.admin:
    default: op

# -----------------------------------------------------------------------------
# Overclock - Main Configuration
# -----------------------------------------------------------------------------
# Global plugin settings live here. Per-module settings are stored in separate
# files inside the Modules folder and are editable through /oc edit or the GUI.
#
# Message placeholders:
#   <prefix>    - The configured plugin prefix
#   <primary>   - The configured primary color
#   <secondary> - The configured secondary color
# -----------------------------------------------------------------------------

General:
  # Plugin prefix. Supports MiniMessage gradients, colors and formatting.
  prefix: "<gradient:#FF00FF:#FFFFFF>[Overclock]</gradient> "

  # Legacy Minecraft color code used for primary/accented text.
  primary-color: "d"

  # Legacy Minecraft color code used for secondary text.
  secondary-color: "f"

  # Duration, in seconds, for /overclock benchmark.
  benchmark-duration: 30

  # If true, OP players are notified when a new update is detected.
  # If false, update notifications are disabled.
  track-updates: true

Sounds:
  # Vanilla sound keys are supported, for example: ui_button_click.
  # Set sound to "" to disable a sound effect.

  click:
    sound: "ui_button_click"
    volume: 0.6
    pitch: 1.2

  nav:
    sound: "item.book.page_turn"
    volume: 0.5
    pitch: 1.0

  open:
    sound: "block.chest.open"
    volume: 0.4
    pitch: 1.4

  toggle-on:
    sound: "block.note_block.pling"
    volume: 0.6
    pitch: 1.5

  toggle-off:
    sound: "block.note_block.pling"
    volume: 0.6
    pitch: 0.8

  success:
    sound: "entity.player.levelup"
    volume: 0.5
    pitch: 1.6

  error:
    sound: "entity.villager.no"
    volume: 0.6
    pitch: 1.0

BackButton:
  # Material for the back button item. Must be a valid Bukkit Material name.
  material: "DARK_OAK_DOOR"
  # Display name of the back button. Use <primary> and <secondary> for color placeholders.
  name: "<primary>Back §7§l» <secondary>Return to previous menu"

Filler:
  # Material for inventory filler items. Must be a valid Bukkit Material name.
  material: "BLACK_STAINED_GLASS_PANE"
  # Display name of the filler item. A single space keeps it blank.
  name: " "

TpsAlert:
  # If true, send Discord webhook alerts when TPS drops below threshold.
  enabled: false
  # TPS threshold that triggers an alert.
  threshold: 15.0
  # Discord webhook URL for sending alerts. Leave empty to disable.
  webhook-url: ""

ScheduledRestart:
  # If true, automatically restart the server at the configured time.
  enabled: false
  # Time in HH:MM format (24-hour) for the scheduled restart.
  time: "04:00"
  # Minutes before restart to send warnings. Empty list disables warnings.
  warning-minutes:
    - 60
    - 30
    - 15
    - 5

# -----------------------------------------------------------------------------
# ChunkPreventer
# -----------------------------------------------------------------------------
# Prevents players from entering chunks that are not loaded yet. This avoids
# movement desync and load spikes caused by forcing chunks too aggressively.
# -----------------------------------------------------------------------------

ChunkPreventer:
  # If true, players are blocked from entering unloaded chunks.
  # If false, players can move into unloaded chunks normally.
  enabled: true

  # If true, players receive the message below when movement is blocked.
  # If false, movement is still blocked silently.
  send-message: true

  # Message sent when a player tries to enter an unloaded chunk.
  message: "<prefix><secondary>This chunk is not loaded yet. <primary>Please wait."

  # Worlds where this module should not run.
  disabled-worlds: []

# -----------------------------------------------------------------------------
# ChunkUnloader
# -----------------------------------------------------------------------------
# Unloads chunks that no longer have nearby players. This reduces memory usage
# and prevents old areas from staying active for no reason.
# -----------------------------------------------------------------------------

ChunkUnloader:
  # If true, chunk unload protection and cleanup tasks are enabled.
  # If false, chunks unload only through vanilla/server behavior.
  enabled: true

  # Ticks to wait after the last player leaves before a chunk can unload.
  unload-delay-ticks: 100

  # If true, unused chunks are scanned and unloaded automatically.
  # If false, only direct unload logic is used.
  auto-unload-unused-chunks: true

  # Ticks between automatic unused-chunk scans.
  cleanup-task-period-ticks: 200

  # Maximum chunks to unload during one cleanup run. Keeps cleanup work bounded.
  max-unloads-per-run: 20

  # Player safety radius in chunks. 1 protects a 3x3 area around each player.
  max-safe-chunk-radius: 1

  # If true, chunks with active ender pearls are protected from unloading.
  # If false, ender pearl chunks can unload like normal chunks.
  protect-ender-pearl-chunks: true

  # Worlds where this module should not run.
  disabled-worlds: []

# -----------------------------------------------------------------------------
# DropCollector
# -----------------------------------------------------------------------------
# Sends selected drops and XP directly into player inventories. This reduces
# dropped-item and XP-orb spam while keeping gameplay smooth.
# -----------------------------------------------------------------------------

DropCollector:
  # If true, DropCollector features are enabled.
  # If false, blocks, mobs and XP drop normally.
  enabled: true

  direct-xp:
    # If true, block break XP is given directly to the player.
    # If false, block break XP drops as orbs.
    on-block-break: true

    # If true, mob kill XP is given directly to the killer.
    # If false, mob kill XP drops as orbs.
    on-mob-kill: true

    # Multiplier applied before XP is given. 1.0 keeps vanilla XP amount.
    xp-multiplier: 1.0

    # If true, creative-mode players do not receive direct XP.
    # If false, creative-mode players can receive direct XP.
    ignore-creative-mode: true

  block-drops:
    # If true, block drops are sent directly to the breaker inventory.
    # If false, block drops fall on the ground normally.
    enabled: true

    # If true, Silk Touch tools bypass direct pickup.
    # If false, Silk Touch drops are also sent directly to inventory.
    ignore-silk-touch: false

    # If true, Fortune tools bypass direct pickup.
    # If false, Fortune drops are also sent directly to inventory.
    ignore-fortune: false

    # If true, creative-mode players do not use block direct pickup.
    # If false, creative-mode players can use block direct pickup.
    ignore-creative-mode: true

    # If true, only materials in list use direct pickup.
    # If false, every material except list uses direct pickup.
    invert: false

    # Block materials used by the invert filter.
    list: [BEACON, ENDER_CHEST, SHULKER_BOX]

  mob-drops:
    # If true, mob drops are sent directly to the killer inventory.
    # If false, mob drops fall on the ground normally.
    enabled: true

    # If true, creative-mode players do not use mob direct pickup.
    # If false, creative-mode players can use mob direct pickup.
    ignore-creative-mode: true

    # If true, only entities in list use direct pickup.
    # If false, every entity except list uses direct pickup.
    invert: false

    # Entity types used by the invert filter.
    list: [WARDEN, ENDER_DRAGON, WITHER]

  # Worlds where block/mob direct pickup is disabled.
  disabled-drop-worlds: []

  # Worlds where direct XP is disabled.
  disabled-xp-worlds: []

  messages:
    # Message sent when an item cannot fit in the player's inventory.
    inventory-full: "<prefix><secondary>Your inventory is full."

  # Materials that should never be auto-picked up by DropCollector.
  # These items always drop on the ground even when block-drops or mob-drops are enabled.
  # Useful for quest items, special drops, or materials players should collect manually.
  blacklisted-materials: []

  # If true, only materials in the blacklist are auto-picked up (whitelist mode).
  # If false, materials in the blacklist are skipped (blacklist mode).
  invert-blacklist: false

# -----------------------------------------------------------------------------
# EntityCleaner
# -----------------------------------------------------------------------------
# Periodically removes selected entities to reduce clutter and prevent TPS loss.
# Exclusions protect valuable items, pets, named mobs and important entities.
# -----------------------------------------------------------------------------

EntityCleaner:
  # If true, automatic cleanup runs on the configured interval.
  # If false, automatic cleanup is disabled.
  auto-clean: true

  # Minutes between automatic cleanup cycles.
  clean-interval: 10

  # Seconds before cleanup when players should be warned.
  warns-before-cleanup: [60, 30, 10, 5, 3, 2, 1]

  messages:
    announce-in:
      # If true, cleanup warnings and results are sent in chat.
      # If false, chat announcements are disabled.
      chat: true

      # If true, cleanup warnings are shown in the actionbar.
      # If false, actionbar announcements are disabled.
      actionbar: true

      # If true, cleanup warnings/results use title and subtitle.
      # If false, title announcements are disabled.
      title-subtitle: false

    warnings:
      # If true, warnings are sent at warns-before-cleanup times.
      # If false, cleanup happens without countdown warnings.
      enabled: true

      # Warning message. Supports <prefix>, <primary>, <secondary> and <time>.
      message: "<prefix><secondary>Entity cleanup in <primary><bold><time></bold> <secondary>seconds."

      # Title shown when title-subtitle is enabled.
      title: "<gradient:#00c6ff:#0072ff><bold>CLEANER</bold></gradient>"

      # Subtitle shown when title-subtitle is enabled. Supports <time>.
      subtitle: "<secondary>Cleaning in <primary><bold><time></bold><secondary>s"

      # If true, warning sounds play with each cleanup warning.
      # If false, warnings are silent.
      sound: true

  clear-complete:
    # Completion message. Supports <prefix>, <primary>, <secondary> and <count>.
    message: "<prefix><secondary>Removed <primary><bold><count></bold> <secondary>entities."

    # Title shown when title-subtitle is enabled.
    title: "<gradient:#00ff87:#60efff><bold>CLEANUP COMPLETE</bold></gradient>"

# -----------------------------------------------------------------------------
# EntityOptimizer
# -----------------------------------------------------------------------------
# Reduces entity tick cost by disabling AI for entities outside the configured
# activation range. Excluded entities and worlds are never optimized.
# -----------------------------------------------------------------------------

EntityOptimizer:
  # If true, far entities can be optimized.
  # If false, entities keep normal AI behavior.
  enabled: true

  # Ticks between optimization scans. 20 ticks = 1 second.
  task-interval-ticks: 40

  # Range from players where entities stay fully active.
  activation-range: 32.0

  # If true, AI is disabled for entities outside activation range.
  # If false, the module tracks entities but does not change AI.
  disable-ai: true

  # If true, tamed pets are never optimized.
  # If false, pets can be optimized like other entities.
  skip-pets: true

  # Entity types that should never be optimized.
  excluded-entities: []

  # Worlds where this module should not run.
  disabled-worlds: []

# -----------------------------------------------------------------------------
# ExplosionOptimizer
# -----------------------------------------------------------------------------
# Reduces explosion lag by controlling block damage, dropped items and chain
# reactions from TNT or end crystals.
# -----------------------------------------------------------------------------

ExplosionOptimizer:
  # If true, explosion optimization rules are enabled.
  # If false, explosions behave normally.
  enabled: true

  # Y-level above which block damage is cleared. Use 320 to disable this check.
  clear-block-damage-above-y: -5

  # If true, block drops from explosions are removed.
  # If false, exploded blocks can drop items normally.
  clear-block-drops: true

  # Worlds where this module should not run.
  disabled-worlds: []

  # Blocks protected from explosion damage.
  protected-blocks: [CHEST, TRAPPED_CHEST, DRAGON_EGG, DRAGON_HEAD]

  # If true, only entities in damage-entities can take TNT/crystal damage.
  # If false, entities in damage-entities are protected instead.
  invert-entity-filter: true

  # Entity types used by invert-entity-filter.
  damage-entities: [PLAYER, ENDER_DRAGON, WITHER, WARDEN]

  # If true, TNT can trigger nearby TNT.
  # If false, TNT chain reactions are blocked.
  tnt-chain: false

  # If true, end crystals can trigger nearby end crystals.
  # If false, crystal chain reactions are blocked.
  crystal-chain: false

# -----------------------------------------------------------------------------
# GraveMaker
# -----------------------------------------------------------------------------
# Stores player drops in a grave on death, shows optional holograms, and removes
# expired graves safely after their configured timer.
# -----------------------------------------------------------------------------

GraveMaker:
  # If true, graves are created when players die.
  # If false, players drop items normally.
  enabled: true

  # If true, text holograms are shown above each grave.
  # If false, graves are created without holograms.
  holograms-enabled: true

  # First hologram line. Supports <player>, <primary>, <secondary>, <despawn_timer>.
  hologram-one: "<primary><player>'s <secondary>Grave"

  # Second hologram line. <despawn_timer> updates live until the grave expires.
  hologram-two: "<secondary>Grave despawns in <primary><despawn_timer>"

  # Time before a grave expires. 12000 ticks = 10 minutes.
  despawn-time-ticks: 12000

  # If true, expired grave contents are dropped on the ground.
  # If false, expired grave contents are deleted with the grave.
  drop-items-on-grave-expiration: false

  # If true, graves never expire automatically.
  # If false, graves despawn after despawn-time-ticks.
  prevent-grave-despawn: false

  # If true, only the dead player can open their grave.
  # If false, any player can open any grave.
  owner-only-access: true

  # Worlds where this module should not run.
  disabled-worlds: []

# -----------------------------------------------------------------------------
# HopperOptimizer
# -----------------------------------------------------------------------------
# Reduces hopper lag by freezing idle hoppers, delaying full-output retries,
# handling hopper minecarts and limiting transfer bursts.
# -----------------------------------------------------------------------------

HopperOptimizer:
  # If true, hopper optimization rules are enabled.
  # If false, hoppers and hopper minecarts behave normally.
  enabled: true

  # If true, hopper minecarts are optimized too.
  # If false, only block hoppers are optimized.
  include-hopper-minecarts: true

  # If true, idle hoppers are frozen briefly after they run out of work.
  # If false, idle hoppers keep checking every tick.
  freeze-idle: true

  # If true, hoppers pushing into full inventories wait before retrying.
  # If false, full hoppers retry every transfer tick.
  lock-when-full: true

  # Worlds where this module should not run.
  disabled-worlds: []

  advanced:
    # Ticks an idle block hopper waits before probing again.
    idle-freeze-ticks: 30

    # Ticks a hopper waits after its destination is full.
    full-lock-ticks: 32

    # Ticks before checking an empty source inventory again.
    empty-source-ticks: 16

    # Hopper minecart wait time before rescanning for ground items.
    minecart-empty-scan-ticks: 20

    # Hopper minecart wait time before searching for a container again.
    minecart-container-scan-ticks: 20

    # If true, hoppers read by comparators are not idle-frozen.
    # If false, comparator hoppers can be idle-frozen.
    skip-idle-freeze-if-comparator: true

    # If true, redstone-powered hoppers are skipped by optimizer checks.
    # If false, powered hoppers are still inspected.
    skip-powered-hoppers: true

    # If true, block hopper transfers are capped by batch-transfer-amount.
    # If false, block hoppers use vanilla transfer amounts.
    batch-transfer: true

    # If true, hopper minecart transfers are capped by batch-transfer-amount.
    # If false, hopper minecarts use vanilla transfer amounts.
    minecart-batch-transfer: true

    # Maximum items moved per transfer when batching is enabled.
    batch-transfer-amount: 32

# -----------------------------------------------------------------------------
# ItemDespawnModifier
# -----------------------------------------------------------------------------
# Changes dropped-item despawn times. Common clutter can disappear faster while
# valuable items can stay longer.
# -----------------------------------------------------------------------------

ItemDespawnModifier:
  # If true, item despawn times are modified.
  # If false, items use the server's default despawn time.
  enabled: true

  # Default despawn time for items not listed below. 6000 ticks = 5 minutes.
  despawn-time-ticks: 6000

  # Worlds where this module should not run.
  disabled-worlds: []

  # Per-material despawn times in ticks.
  custom-despawn-times:
    COBBLESTONE: 600
    STONE: 600
    DIRT: 600
    GRASS_BLOCK: 600
    NETHERRACK: 600
    SEEDS: 600
    WHEAT_SEEDS: 600
    PUMPKIN_SEEDS: 600
    MELON_SEEDS: 600
    SCULK: 600
    GRAVEL: 1200
    SAND: 1200
    BLACKSTONE: 1200
    ROTTEN_FLESH: 1200
    ARROW: 1200
    SPIDER_EYE: 1200
    KELP: 1200
    BONE: 1800
    STRING: 1800
    GUNPOWDER: 1800
    NETHER_STAR: 24000
    DRAGON_EGG: 24000

# -----------------------------------------------------------------------------
# JavaGC-Runner
# -----------------------------------------------------------------------------
# Retained for backwards-compatible configuration only. Overclock never invokes
# explicit JVM garbage collection because it can cause stop-the-world pauses.
# -----------------------------------------------------------------------------

JavaGC-Runner:
  # Deprecated: ignored. The JVM always manages garbage collection normally.
  enabled: true

  # Minutes between scheduled garbage collection attempts.
  interval: 10

  # If true, memory cleanup information is logged to console.
  # If false, scheduled GC runs silently.
  debug: false

  # If true, System.runFinalization() is also requested after GC.
  # If false, only System.gc() is requested.
  force-gc: false

  # If true, GC is only triggered when heap usage exceeds the threshold percentage.
  # Prevents unnecessary GC pauses when memory usage is low.
  # Works alongside interval-based scheduling (both conditions must be met).
  use-memory-threshold: true

  # Minimum heap usage percentage required to trigger GC.
  # GC only runs if current heap usage is above this level.
  # Range: 1-99. Default 65% balances performance and memory efficiency.
  memory-threshold-percent: 65

# -----------------------------------------------------------------------------
# LagDetector
# -----------------------------------------------------------------------------
# Detects repeated lag-heavy actions in the same chunk and temporarily throttles
# that chunk before it hurts server performance.
# -----------------------------------------------------------------------------

LagDetector:
  # If true, lag-heavy chunk activity is monitored and throttled.
  # If false, no chunk cooldowns are applied.
  enabled: true

  # Maximum tracked lag actions allowed per chunk per second.
  max-lag-actions-per-second: 20

  # Maximum armor stands allowed in one chunk.
  max-armor-stands-per-chunk: 50

  # Cooldown in seconds after the first violation.
  cooldown-tier-1: 5

  # Cooldown in seconds after the second violation.
  cooldown-tier-2: 30

  # Cooldown in seconds after the third violation and higher.
  cooldown-tier-3: 300

  # Extra seconds added for each violation tier above tier 3.
  cooldown-additive-step: 300

  # Minutes without new violations before a chunk's violation tier resets.
  violation-reset-minutes: 10

  # Worlds where this module should not run.
  disabled-worlds: []

# -----------------------------------------------------------------------------
# LagShield
# -----------------------------------------------------------------------------
# Applies emergency protections while TPS is low: firework cooldowns, explosion
# chain blocking, hopper throttling, passive mob AI freezing and distance scaling.
# -----------------------------------------------------------------------------

LagShield:
  # If true, LagShield protections can activate during low TPS.
  # If false, no emergency protections are applied.
  enabled: true

  # Worlds where this module should not run.
  disabled-worlds: []

  # If true, elytra firework spam is limited when TPS is below threshold.
  # If false, fireworks are never limited by LagShield.
  firework-cooldown: true

  # Ticks between firework launches while cooldown is active.
  firework-cooldown-ticks: 60

  # TPS threshold where firework cooldown starts.
  firework-cooldown-tps: 19.0

  # If true, TNT and crystal chain reactions are blocked during low TPS.
  # If false, explosion chains are never blocked by LagShield.
  block-tnt-and-crystal-chain: true

  # TPS threshold where TNT/crystal chain blocking starts.
  tnt-crystal-chain-tps: 15.0

  # If true, hoppers and hopper minecarts are throttled during low TPS.
  # If false, hopper transfers are never slowed by LagShield.
  # Uses HopperOptimizer's lock cache so both modules never double-lock.
  hoppers-slowdown: true

  # TPS threshold where hopper slowdown starts.
  hoppers-slowdown-tps: 15.0

  # Ticks a hopper waits after each blocked transfer during slowdown.
  hoppers-slowdown-ticks: 8

  # If true, passive mob AI is frozen during low TPS.
  # If false, passive mob AI is never frozen by LagShield.
  freeze-passive-mob-ai: true

  # TPS threshold where passive mob AI freezing starts.
  freeze-passive-mob-ai-tps: 15.0

  # If true, view/simulation distance is reduced during low TPS.
  # If false, distances are never changed by LagShield.
  dynamic-distance-scaling: true

  # TPS threshold where dynamic distance scaling starts.
  dynamic-distance-scaling-tps: 16.0

  # Minimum view distance while dynamic scaling is active.
  distance-scaling-min-view-distance: 3

  # Minimum simulation distance while dynamic scaling is active.
  distance-scaling-min-simulation-distance: 2

  # If true, natural mob spawning is blocked when TPS drops below threshold.
  # Prevents lag from mob spawns during server stress.
  # Works by cancelling CreatureSpawnEvent for NATURAL and SPAWNER reasons.
  disable-mob-spawning-below-tps-enabled: false

  # TPS level below which mob spawning is blocked.
  # Natural spawns are cancelled until TPS recovers above this value.
  disable-mob-spawning-below-tps-threshold: 15.0

# -----------------------------------------------------------------------------
# VillagerOptimizer
# -----------------------------------------------------------------------------
# Freezes AI for caged villagers, wakes them for trading, and refreezes them
# after trading to reduce villager tick load.
# -----------------------------------------------------------------------------

VillagerOptimizer:
  # If true, caged villagers can be optimized.
  # If false, villagers keep normal AI behavior.
  enabled: true

  # Ticks between villager cage scans. 20 ticks = 1 second.
  task-interval-ticks: 300

  # Minimum blocked sides required to count a villager as caged. Range: 1-4.
  min-blocked-sides: 3

  # If true, AI is restored when a villager is no longer caged.
  # If false, optimized villagers stay frozen until another module action changes them.
  restore-ai-when-uncaged: true

  # If true, villagers wake when players interact or trade.
  # If false, optimized villagers stay frozen during interaction.
  wake-on-interact: true

  # If true, villagers freeze again after the trade window closes.
  # If false, villagers stay awake after trading.
  refreeze-after-trade: true

  # If true, villagers with custom names are never optimized.
  # If false, named villagers can be optimized.
  skip-named-villagers: true

  # If true, optimization actions are logged to console.
  # If false, the module runs quietly.
  debug: false

  # Worlds where this module should not run.
  disabled-worlds: []