Kinetic - Lag Preventer

version: 1

# This is the main configuration for Kinetic. Comments explain what each option does,
# expected units/ranges, and any trade-offs.

# Proximity & Nearest-Player Cache (Module 1)
# Grid-based cache used by the Budget Engine and other modules to quickly
# approximate nearest-player distances. See design doc §6.1.
proximity:
  cell-size: 32            # blocks per grid cell
  move-threshold: 1.25     # min player movement to trigger cell update
  neighbor-radius-cells: 2 # how many neighbor rings to search for players
  track-cross-world: false # if false, only same-world players are considered

# Dynamic AI Budgeter (Module 3). Paces AI actions to fit within a tick budget.
dab:
  enabled: true
  activation-dist-mod: 8     # distance multiplier to consider entities "active" relative to players
  power: 2.0                 # non-linear shaping for priority decay; higher skews toward nearby entities
  base-period-ticks: 1       # default period between AI ticks when unconstrained
  min-period-ticks: 1        # lower bound; never schedule AI more frequently than this
  max-period-ticks: 40       # upper bound; never delay AI beyond this
  blacklist-entities: []     # EntityType names that are always throttled (even if whitelisted)
  whitelist-entities: []     # If non-empty, only these EntityTypes are considered by the budgeter
  exempt-nametagged: true    # Named mobs are treated as important; less likely to be throttled
  exempt-tamed: true         # Tamed mobs are treated as important; less likely to be throttled

  # Per-World Budget System - Advanced resource allocation per world
  per-world-budgets:
    enabled: false            # Enable separate budget pools per world
    default-budget: 2500      # Default budget for worlds not explicitly configured
    worlds:                   # Specific world budget overrides
    # world: 5000           # Example: higher budget for main world
    # world_nether: 1500    # Example: lower budget for Nether
    # world_the_end: 1000   # Example: minimal budget for End

  # Player-Specific Exemptions - Advanced player bypass system
  player-exemptions:
    enabled: false            # Enable individual player exemption system
    exempt-ops: true          # Operators are automatically exempt
    exempt-names:             # Specific player names to exempt
    # - "AdminPlayer"
    # - "BuilderUser"
    exempt-permissions:       # Permissions that grant exemption
      - "Kinetic.budget.exempt"
      # - "staff.moderator"
    exempt-patterns:          # Regex patterns for player names (case-insensitive)
    # - "^Admin.*"          # All players starting with "Admin"
    # - ".*Builder$"        # All players ending with "Builder"
  hard-freeze:
    enabled: false
    min-player-distance: 64  # entities beyond this distance may be frozen (AI stopped)
    recheck-period-ticks: 40 # cadence to re-evaluate freeze eligibility
    max-entities-per-tick: 400 # upper bound on entities processed per pass
    fov:
      enabled: true
      fov-degrees: 110       # player field-of-view size for visibility consideration
      require-los: true       # require line-of-sight when determining visibility
      max-distance: 96        # max distance for FOV checks
    wake-on-damage:
      enabled: true
      duration-ticks: 80      # temporarily unfreeze when damaged
    always-active-types: []   # EntityTypes never frozen; e.g., VILLAGER if desired
  per-action-multipliers:
    PATHFIND: 1.0
    TARGET: 1.2
    BREED: 2.0
    REPLENISH: 2.0
    ANGER: 1.5
  tps-adaptation:
    enabled: true
    threshold: 18.5           # below this TPS, increase throttling aggressiveness
    multiplier: 1.5           # scale applied to periods when TPS under threshold
  jitter:
    enabled: true
    percent: 0.1              # randomize periods slightly to avoid burst alignment
  cleanup-interval-ticks: 1200 # periodic purge of internal bookkeeping

# Spawn controls. Provides soft per-chunk caps and distance/TPS guards.
spawns:
  enabled: true
  per-chunk-soft-cap:
    MONSTER: 70        # approximate soft caps per chunk category
    CREATURE: 50
    WATER_AMBIENT: 30
  tps-guard:
    enabled: true
    threshold: 18.5     # below this TPS, deny a portion of otherwise-allowed spawns
    denial-percent: 0.35 # fraction of spawns denied when below threshold (0..1)
  far-deny:
    enabled: true
    min-player-dist: 96 # deny spawns farther than this from any player

merging:
  entities:
    enabled: false
    # Merge search radius (blocks) around the spawn for compatible mobs.
    radius: 8.0
    # Max stack size per entity unless overridden in per-type below.
    max-stack-size: 32
    # Also set a custom name like "Zombie x8" on the stacked mob (optional visual).
    show-name: true
    # Do not stack mobs that already have a custom name.
    skip-named: true
    # Optional allow/deny controls. If whitelist is non-empty, only those types will stack.
    # Types are Bukkit EntityType names, e.g., ZOMBIE, SKELETON, CREEPER, etc.
    whitelist-types: []
    blacklist-types: [VILLAGER, ENDER_DRAGON, WITHER, WARDEN, ELDER_GUARDIAN, IRON_GOLEM] # never stack these types
    # Per-type overrides
    per-type:
      SLIME:
        max-stack-size: 8
      MAGMA_CUBE:
        max-stack-size: 8
    hologram:
      enabled: true
      # Vertical offset above the entity. Adjust per version/model.
      offset: 0.75
      # Base format when no per-type override is set.
      # Placeholders:
      #  - {amount}: stack size (supports styles below)
      #  - {type}: Bukkit EntityType pretty name (e.g., "Zombie")
      format: "x{amount}"
      # Formatting style for {amount}: plain | thousands | compact
      #  - plain: 1200
      #  - thousands: 1,200
      #  - compact: 1.2k
      format-style: plain
      # Optional per-entity-type overrides. Keys are Bukkit EntityType names.
      # Example:
      # per-type:
      #   ZOMBIE: "{type} x{amount}"
      #   SKELETON: "{type} x{amount}"
      per-type: {}
  items:
    enabled: true
    # Merge search radius (blocks) for item entities.
    radius: 2.5
    # If true, only items with identical metadata (lore, enchants, model data) stack together.
    respect-metadata: true
    # Perform nearby scan in a background-friendly way; world mutations still on main thread.
    async-scan: true
    # Allow item entities on the ground to exceed vanilla stack size (inventory stacks unaffected).
    allow-oversize: false
    # Cap for an item entity's merged count (visual + physics). Inventory stacks are unaffected.
    max-entity-stack: 512
    hologram:
      enabled: true
      # Vertical offset above the entity. Adjust per version/model.
      offset: 0.75
      # Base format when no per-material override is set.
      # Placeholders:
      #  - {amount}: stack size (supports styles below)
      #  - {material}: Bukkit Material pretty name (e.g., "Diamond")
      #  - {name}: item display name if present, else {material}
      format: "x{amount}"
      # Formatting style for {amount}: plain | thousands | compact
      format-style: plain
      # Optional per-material overrides. Keys are Bukkit Material names.
      # Example:
      # per-material:
      #   DIAMOND: "{name} x{amount}"
      #   COBBLESTONE: "{material} x{amount}"
      per-material: {}
  xp:
    enabled: true
    # Merge search radius (blocks) for XP orbs.
    radius: 3.0
    # Maximum vanilla XP orb size when splitting/merging (typical max value is 11).
    max-orb-size: 11
    hologram:
      enabled: true
      offset: 0.75
      # Placeholders:
      #  - {amount}: total xp value (supports styles below)
      #  - {type}: constant "XP"
      format: "{amount} xp"
      # Formatting style for {amount}: plain | thousands | compact
      format-style: plain

blocks:
  # Pacing for block updates to prevent cascades when far from players.
  # Higher cooldowns reduce churn but delay propagation.
  physics-cooldown-ticks: 3
  # Slow down fluid updates when far from players to reduce server load.
  throttle-fluids: true
  # Leaves decay pacing: immediate | defer | defer_far. defer_far delays when not near players.
  leaves-decay: defer_far
  # Plant growth pacing: immediate | defer | defer_far.
  plant-growth: defer_far
  pistons:
    # Limit concurrent piston actions per tick to mitigate lag machines.
    limit-per-tick: 2
    # Detect and inhibit piston engine patterns. May affect redstone contraptions; use with care.
    anti-engines: false

hoppers:
  # Hopper optimization module: batch and cap item moves to reduce per-tick cost.
  enabled: true
  # Batch pulls/pushes in this tick window for better locality.
  batch-window-ticks: 4
  # Global cap of item moves per tick across all hoppers.
  max-moves-per-tick: 128
  # Radius around hopper to scan for item entities to suck in.
  pickup-scan-radius: 1.0

async:
  # Size of worker thread pool for safe async tasks. Typically = CPU cores / 2..cores.
  worker-threads: 2

  # Enhanced WorkerPool Configuration
  core-threads: 4                    # Core number of worker threads
  max-threads: 8                     # Maximum worker threads when busy
  max-queue-size: 100                # Maximum queued tasks before rejection

  # Task timeout and performance settings
  task-timeout-ms: 30000             # Default task timeout (30 seconds)
  keep-alive-time-ms: 60000          # Thread keep-alive time (1 minute)
  queue-warning-threshold: 0.8       # Queue utilization warning threshold (80%)

  # Monitoring and health checks
  monitoring:
    enabled: true                    # Enable comprehensive monitoring
    health-check-interval-ms: 300000 # Periodic health checks (5 minutes)

  # Fallback execution when pool is overloaded
  fallback-execution: true           # Execute rejected tasks on main thread as fallback

  # Performance tuning
  allow-core-timeout: true           # Allow core threads to timeout and terminate
  thread-priority-offset: -1         # Thread priority offset from normal (-1 = slightly lower)

packets:
  # Packet-level optimizations. Some features require ProtocolLib.
  enabled: false
  # If true, features that need ProtocolLib will be disabled when missing.
  protocollib-required: true
  hide-far-entities:
    # Hide entities beyond max-distance from the player to reduce client load (server-authoritative).
    enabled: true
    # Distance threshold in blocks.
    max-distance: 96
    # Never hide player entities.
    exempt-players: true
    # Never hide tamed mobs owned by the player.
    exempt-tamed: true
  sound-throttle:
    # Limits repeated identical sounds per tick to reduce spam.
    enabled: true
    # Per-player cap of sound packets per tick before throttling kicks in.
    max-per-tick: 5
    # Optional spatial de-duplication: limit repeated identical-location sounds per tick
    de-duplicate:
      enabled: true
      bucket-radius: 8
      max-per-bucket: 2
  particle-throttle:
    # Limits particle packet rate by cluster.
    enabled: true
    # Maximum packets per nearby cluster per tick.
    max-per-cluster: 20
  chunk-streaming:
    # Paces chunk data packets to avoid bursts on join/fast travel.
    enabled: true
    # Allow more chunks per tick to prevent starving initial render or fast travel
    max-per-tick: 8
    # Do not throttle chunk packets for new players to guarantee world bootstrap
    warmup-ticks: 200
    prioritize-player-heading: true
    # Only enable pacing when TPS is under this threshold
    tps-guard:
      enabled: true
      threshold: 18.5
    # Gradually ramp per-player allowance after warm-up to avoid burst
    ramp:
      enabled: true
      base: 4
      max: 8
      step: 1
      period-ticks: 40
  metadata-rate-limit:
    # Rate-limits frequent entity metadata updates; whitelist critical indices to avoid desync.
    enabled: false
    # Minimum ticks between metadata updates per entity.
    interval-ticks: 5
    # Metadata indices to always pass (bypass rate limit) to avoid desync on critical state.
    # Common indices: 0=flags, 1=air, 2=custom name, 3=custom name visible, 4=silent, 5=no gravity, etc.
    # Adjust per-version as needed. Leave empty to not bypass anything.
    whitelist-indexes: [0, 1]
  player-idle-compression:
    # When player idle past threshold, scale down loud/visual packet budgets.
    enabled: true
    # Seconds of inactivity before considered idle.
    idle-threshold-seconds: 60
    # When a player is idle past the threshold, scale down per-tick packet caps
    sound-scale: 0.5        # 0.05..1.0, multiplied with sound max-per-tick
    particle-scale: 0.5     # 0.05..1.0, multiplied with particle max-per-cluster

performance:
  # Global work budget per tick (internal units). Lower = stricter throttle.
  tick-budget-per-tick: 5000
  priorities:
    # Relative share of the budget per subsystem. Higher = more time allocated.
    AI: 40
    HOPPERS: 30
    PHYSICS: 30
  shared-budget:
    # When enabled, unused budget in one subsystem can be borrowed by others.
    enabled: false
    AI: 40

debug:
  # Extra logging for diagnostics; increases console spam.
  verbose: false
  # Probability [0..1] to sample events for telemetry when enabled.
  sampling-rate: 0.05
  # Enable in-game admin commands for debugging.
  commands-enabled: true

# Plugin-level entity visibility culling (approx async tracker behavior)
tracker:
  visibility:
    enabled: false
    radius: 96.0
    exempt-players: true
    include-types: []      # if non-empty, only these Bukkit EntityType names are considered
    exclude-types: [ITEM_FRAME, PAINTING] # never considered for hide/show decisions
    max-players-per-tick: 4
    # Upper bound on hide/show ops processed per tick across all tracked players.
    max-ops-per-tick: 400
    # How often to run the visibility pass.
    period-ticks: 20
    # If true, hologram ArmorStands will also be hidden/shown per-player following the same rules.
    # This prevents holograms from rendering for entities that are culled for that player.
    integrate-holograms: true

# Region profiles & integrations
regions:
  worldguard:
    # List of WorldGuard region IDs where packet suppression is bypassed
    exempt-packets: []

# TickService Configuration
tick-service:
  # TPS Monitoring Settings
  tps-monitoring:
    # Enable real-time TPS monitoring and calculation
    enabled: true
    # TPS threshold below which warnings are issued (default: 15.0)
    warning-threshold: 15.0

  # Health Check Settings
  health-checks:
    # Enable comprehensive health monitoring of the tick service
    enabled: true
    # Maximum allowed missed ticks before triggering health warnings (default: 100)
    max-missed-ticks: 100