# LOD Server Support — Paper/Folia server defaults.
# Edit this file, then run /vsslod reload. Settings marked [restart] wait for restart.
# Reload changes policy for new work; existing jobs/reads drain and cache trimming can lag.
# Distances are radii. 1 chunk = 16 blocks; 1 MiB = 1,048,576 bytes.
config_version: 1 # Local settings schema version, independent of the network protocol.

# Serves distant terrain to compatible clients beyond vanilla's view distance.
# This does not increase the server's simulation distance or keep distant chunks ticking.
service:
  enabled: true # [restart] Enable the server's LOD service.
  require_permission: false # Require both lss.use and vss.use; nodes default to allowed.

# Larger radii reveal more terrain, but cover more columns and can increase
# generation, transfer, cache and disk work. Doubling a radius covers roughly four
# times the area; a large configured radius does not mean it fills instantly.
lod:
  distance:
    default_chunks: 512 # Fallback for dimensions not listed below; range 1–2048.
    by_dimension: # These are fresh-install defaults; migration preserves existing limits.
      "minecraft:overworld": 512 # Overworld radius in chunks.
      "minecraft:the_nether": 64 # Nether radius in chunks.
      "minecraft:the_end": 512 # End radius in chunks.
    by_world: {} # Paper world-name overrides; take priority over dimension entries.

# Lets LOD requests create terrain that does not yet exist in the world.
# This costs world-generation CPU time and grows the normal world files, independently
# of the LOD store. With generation off, existing terrain can still be served.
# Higher concurrency can fill missing terrain sooner, but competes with gameplay.
generation:
  enabled: true # Generate missing terrain; disabling stops new jobs, existing jobs finish.
  concurrency:
    global: 40 # Maximum concurrent generations across the server; range 1–512.
    per_player: 40 # Maximum per player; cannot exceed the global limit.
  timeout_ticks: 1200 # New jobs only; 60 seconds at 20 TPS, longer under lag; range 20–12000.

# Limits and schedules LOD traffic so it shares resources with normal gameplay.
# Bandwidth limits count uncompressed payload work, so they also limit client decode
# work; compressed network traffic can be much smaller. Lower limits slow terrain fill.
network:
  bandwidth:
    per_player_mib_per_second: 5 # Raw MiB/s before compression; 0 clamps to 1 KiB/s, not unlimited.
    global_mib_per_second: 50 # Shared raw MiB/s budget; 0 clamps to 1 KiB/s, not unlimited.
  send_queue_limit_per_player: 1024 # Admission ceiling; lowering it lets existing work drain.
  ping_backstop: true # Reduce LOD traffic when player latency indicates congestion.
  send_pacing: true # Spread LOD sends across ticks to reduce bursts.
  yield_to_vanilla: true # Let normal game traffic take transport priority; applies next flush.

# Keeps previously downloaded terrain up to date when the world changes.
# Shorter dirty-broadcast intervals show edits sooner but can send updates more often.
# Region summaries let returning clients validate cached areas without downloading
# every column again; they describe freshness, not the terrain itself.
updates:
  # Tick-driven: 200 ticks = 10 seconds at 20 TPS, longer under lag.
  dirty_broadcast_interval_ticks: 200 # 0 disables pushes, not invalidation; otherwise 20–6000.
  region_summaries: true # Accept new region-validation requests; accepted requests can finish.

storage:
  # Reader threads and concurrent reads control pressure on world-file access.
  # More parallel reads can improve throughput, but can also compete with gameplay
  # for disk and CPU. Automatic sizing accounts for the active read path and store.
  disk:
    reader_threads: 0 # [restart] 0 = automatic; explicit range 1–64.
    max_concurrent_reads: 0 # 0 = automatic, based on the active reader pool and store.
    background_priority: true # [restart] Use background-priority reads where supported.
    split_background_reads: true # [restart] Separate background read work where supported.
  # This RAM cache holds column freshness timestamps, not complete terrain.
  # More capacity can avoid repeated timestamp lookups, at the cost of server memory.
  # Reducing capacity trims gradually; it does not clear the entire cache on reload.
  timestamp_cache_mib_per_dimension: 0 # 0 = automatic from the largest active LOD radius.
  # Briefly remembering missing columns avoids repeatedly checking unavailable terrain.
  # A longer lifetime can delay another lookup for newly available data on a memo hit.
  miss_memo_ttl_seconds: 30 # 0 disables; maximum 60. Changing this clears old miss memos.
  # Persistent cache of prepared LOD columns, reused across players and restarts.
  # Cache hits reduce repeated world-file parsing, serialization and, when the
  # client's format supports reuse, compression. Store reads still use disk I/O.
  # Tradeoff: extra disk space and writes as terrain is cached or updated. A fully
  # warmed store can be comparable in size to the region files; actual use depends
  # on the world and how much terrain has been cached. This is rebuildable data.
  # Off still allows normal LOD serving, but loses this reuse. Disabling the store
  # does not delete its existing files or reclaim their disk space.
  lod_store:
    enabled: true # [restart] Fresh installs enable this; migration preserves old behavior.
    # Smaller limits retain less prepared terrain, so evicted columns may need
    # processing again. This bounds live database data, not total filesystem use:
    # SQLite journal files and space awaiting reclamation can add overhead.
    # Lowering the cap evicts gradually; reload does not instantly free filesystem space.
    max_size_mib: 0 # 0 = unlimited; positive range 64–1,048,576 MiB.
    # Periodically recheck saved-world freshness to catch edits without a Bukkit event.
    # Shorter intervals find these saved edits sooner but perform more checks.
    # Unsaved changes still have to reach the world files before this path can see them.
    resweep_interval_seconds: 300 # 0 disables future periodic sweeps; an active sweep can finish.

# Optimized processing paths for turning world terrain into transmitted columns.
# Compression reduces network bytes but costs CPU when a reusable frame is unavailable.
# These are expert troubleshooting switches; their effects depend on the active path.
serialization:
  selective_nbt_parse: true # Inactive on Paper's already-parsed NBT path; retained for portability.
  nbt_transcode: true # New reads: use the optimized terrain serialization path.
  compressed_columns: true # [restart] Compress columns for clients that support it.

# Allows older LOD protocol versions; these numbers are not Minecraft versions.
# Disabling a fallback restricts which clients can connect to the LOD service.
# It does not translate arbitrary modded blocks or replace a version-translation mod.
compatibility:
  protocols:
    v16: true # [restart] Accept protocol-16 clients.
    v18: true # [restart] Accept protocol-18 clients.
    v19: true # [restart] Accept protocol-19 clients.
  via_mismatch_guard: true # [restart] Guard incompatible translated-protocol sessions.

# Prevents distant terrain data from revealing blocks hidden by anti-xray policy.
# Auto follows supported detected policy; forcing off can expose hidden terrain.
# The block list and height below are fallbacks, not overrides for an adopted engine policy.
privacy:
  xray:
    mode: "auto" # [restart] "auto", "on" or "off"; auto follows detected anti-xray policy.
    max_y_blocks: 64 # [restart] Fallback mask applies below this world Y coordinate.
    hidden_blocks: # [restart] Fallback list when engine policy is unavailable; [] hides none.
      - "minecraft:copper_ore"
      - "minecraft:deepslate_copper_ore"
      - "minecraft:raw_copper_block"
      - "minecraft:gold_ore"
      - "minecraft:deepslate_gold_ore"
      - "minecraft:iron_ore"
      - "minecraft:deepslate_iron_ore"
      - "minecraft:raw_iron_block"
      - "minecraft:coal_ore"
      - "minecraft:deepslate_coal_ore"
      - "minecraft:lapis_ore"
      - "minecraft:deepslate_lapis_ore"
      - "minecraft:mossy_cobblestone"
      - "minecraft:obsidian"
      - "minecraft:chest"
      - "minecraft:diamond_ore"
      - "minecraft:deepslate_diamond_ore"
      - "minecraft:redstone_ore"
      - "minecraft:deepslate_redstone_ore"
      - "minecraft:clay"
      - "minecraft:emerald_ore"
      - "minecraft:deepslate_emerald_ore"
      - "minecraft:ender_chest"

# Sends lightweight distant-player snapshots beyond normal entity tracking range.
# This does not keep distant entities ticking. Larger ranges and more frequent
# updates can increase server work, traffic and client rendering work.
# "opt_in" shares only targets whose clients explicitly allow sharing; "on" can
# also include vanilla players. Exclusions, visibility rules and opt-outs still apply.
far_players:
  mode: "on" # "off", "opt_in" or "on"; all modes honor exclusions and sharing opt-outs.
  update_interval_ticks: 10 # 10 ticks = two updates/second at 20 TPS; range 2–100.
  distance:
    min_blocks: 0 # 0 = no additional inner ring; cannot exceed max_blocks.
    max_blocks: 2048 # Server visibility ceiling; range 128–16384 blocks.
  send_spectators: false # Include spectator targets if other privacy checks allow them.
  excluded_players: [] # Player names or UUIDs never shared; kept out of diagnostic exports.

# Bukkit event hooks invalidate cached LODs after world edits. Adding frequent
# events can improve coverage but increase work; edits without a matching event
# may remain stale until saved terrain is checked by the store's periodic resweep.
paper:
  update_events: # [restart] Bukkit events used to detect changed terrain.
    - "org.bukkit.event.block.BlockPlaceEvent"
    - "org.bukkit.event.block.BlockBreakEvent"
    - "org.bukkit.event.block.BlockExplodeEvent"
    - "org.bukkit.event.entity.EntityExplodeEvent"
    - "org.bukkit.event.block.BlockBurnEvent"
    - "org.bukkit.event.block.BlockFadeEvent"
    - "org.bukkit.event.block.BlockFormEvent"
    - "org.bukkit.event.block.BlockGrowEvent"
    - "org.bukkit.event.block.BlockSpreadEvent"
    - "org.bukkit.event.block.LeavesDecayEvent"
    - "org.bukkit.event.block.BlockPistonExtendEvent"
    - "org.bukkit.event.block.BlockPistonRetractEvent"
    - "org.bukkit.event.entity.EntityChangeBlockEvent"
    - "org.bukkit.event.world.StructureGrowEvent"