Configuration

General Settings

The main configuration file is located at /plugins/SimpleClaimSystem/config.yml. Reload after editing with /scs reload.

# Logger verbosity
logger: NORMAL            # NORMAL | DEBUG

# Language file (from /langs)
lang: "en_US.yml"

# Update checks
update:
  check: true             # poll for new versions on startup
  notifications: true     # notify in-game on join (requires scs.update.notifications)

# Command aliases — add extra command names that invoke the same handler
command-aliases:
  claim: []
  parea: []
  unclaim: []
  claims: []
  scs: []

Key reference

Database

SCS2 uses SQLite by default but supports MySQL / MariaDB for larger servers and multi-server setups:

database:
  enabled: false         # false = SQLite (local), true = use the MySQL block below
  hostname: localhost
  port: 3306
  name: database_name    # schema (must already exist on the server)
  username: root
  password: pass
  hikari:
    # Connection-leak threshold (ms). Hikari logs a stack trace identifying the borrower
    # if a connection is held longer than this without being returned. Useful to surface
    # accidental synchronous DB calls on hot paths. 0 disables the check.
    leak-detection-ms: 5000

Key reference

Database transfer

You can transfer data between local (SQLite) and distant (MySQL) databases at any time:

• /scs transferLocalToDistant — Copy all SQLite data to MySQL
• /scs transferDistantToLocal — Copy all MySQL data to SQLite

Redis (Optional Cache Layer)

Redis is an optional third caching layer between the in-memory cache (Caffeine) and the SQL database. It does not replace MySQL and is not a cross-server synchronization bus — it's purely a performance optimization.

How the cache stack works

Every claim / player read follows this order:

1. Caffeine (in-memory, per-server) — hit: returned instantly.
2. Redis (if enabled) — miss in Caffeine ⇒ check Redis. Hit: the value is deserialised and cached in Caffeine. Miss: fall through.
3. MySQL / SQLite — miss everywhere ⇒ query the database. The result is written to Redis (if enabled) and Caffeine for subsequent reads.

Writes go to the database first, then to Redis, then to Caffeine, and will invalidate both caches if any step fails to avoid stale reads.

redis:
  enabled: false
  hostname: localhost
  port: 6379
  password: ""                  # empty = no auth; set on any internet-facing Redis
  database: 0                   # Redis logical db (0-15 by default)
  command-timeout-seconds: 30   # bump on slow/remote Redis; 0 = no client-side timeout

Key reference

Storage schema

Since v2.2.4 the plugin stores claims under a two-key layout: one scs:claim:<id> key holds the JSON for the entire claim (chunks, members, bans, perms, flags), and every chunk gets a lightweight scs:chunk:<worldUuid>;<x>;<z> pointer containing just the claim id. This makes a radius claim O(chunks) on the wire instead of O(chunks²) and avoids the SETEX timeouts that earlier layouts could trigger.

When should I enable it?

Redis is worth enabling when:

• Caffeine evicts frequently (very large claim counts, a lot of Caffeine misses). Redis keeps deserialised claims close to the server.
• You want claim reloads after a /scs reload to be fast (Redis survives the restart; Caffeine does not).

For small/medium servers, Caffeine alone is enough. Redis adds operational overhead (another service to run) without meaningful gains.

Cache Thread Pool

Both the claim cache and the player cache share a tunable executor. It controls how many concurrent DB/Redis lookups the cache layer can fire when something misses Caffeine. Defaults are usually fine — only change this if you see "executor saturated" warnings or if your server is particularly large.

cache:
  thread-pool:
    # automatic = suitable for the machine (max(2, CPU cores / 2)).
    # manual    = use core-size below.
    mode: automatic
    core-size: 4
    queue-size: 5000

Key reference

Discord Webhook

SCS2 can post claim events (claims, unclaims, sales, purchases, ban/kick actions, /requnclaim submissions, etc.) to Discord. You can define multiple named webhooks and choose which event goes to which webhook.

discord-webhook:
  enabled: false
  url: ""                 # legacy single webhook — used as "default" if "webhooks" is empty

  webhooks:               # define one or more named webhooks
    default:
      url: "https://discord.com/api/webhooks/..."
      username: ""        # optional name override
      avatar-url: ""      # optional avatar override
  #  staff:
  #    url: "https://discord.com/api/webhooks/..."

  default-routes:         # events with no explicit route below go here
    - default

  routing:                # event -> webhook(s), overrides default-routes
  #  claim-deleted:
  #    - default
  #    - staff
  #  unclaim-request:
  #    - staff

Set enabled: true and configure at least one webhook URL. See Integrations → Discord Webhooks for the full list of routable event names. Leaving webhooks empty falls back to the single url (which then receives every event), so older configs keep working unchanged. Run /scs reload to apply changes.

Per-event toggles (Added in 2.6.6)

The optional events block turns individual events on or off at the source. An event set to false is never sent to any webhook — this is independent of routing, which only chooses which webhook receives an event that is being sent. Every event you omit defaults to true, so existing configs keep posting everything.

discord-webhook:
  events:
    chunk-added: false        # stop the per-chunk spam...
    chunk-removed: false      # ...while keeping everything else
    member-added: true
    member-role-changed: true
    # any event not listed here defaults to true

The example above silences the noisy chunk-added / chunk-removed events while still posting member and role changes. See Integrations → Discord Webhooks for the full list of event names.

Web Dashboard

The admin web dashboard provides remote management of claims and players through a browser interface:

web-dashboard:
  enabled: false
  port: 8095
  # Public URL appended with ?token=<...> in the in-game login link.
  # Change this when the dashboard is behind a reverse proxy or a custom domain.
  url: "http://localhost:8095"
  # Token lifetime in hours. 0 = tokens never expire.
  token-ttl-hours: 24
  # Allowed CORS origins. Fallback: localhost + 127.0.0.1 on the configured port.
  # "*" means "any origin": insecure, only for local trusted setups.
  cors-origins:
    - "http://localhost:8095"
    - "http://127.0.0.1:8095"

Key reference

Generate a login link

Run /scs dashboard in-game. The plugin sends a clickable [Click here] link in chat that opens the dashboard URL (from web-dashboard.url above) with the auth token already baked into the query string, so you land directly inside the dashboard. The token is also persisted in the browser's localStorage so a manual refresh keeps you signed in.

Tokens are stored hashed in web-tokens.json and persist across restarts.

Built-in abuse protection

• Rate limiting — the /auth endpoint accepts at most 5 attempts per IP per minute. Further requests return HTTP 429 with a Retry-After header, making brute-force token guessing impractical.
• Path traversal — static file requests are canonicalised; .. / ~ are rejected.
• Prepared statements — all dashboard DB access goes through the same DAO layer, no raw SQL concatenation.

Audit Logs

Track every action performed on claims for accountability and moderation:

audit-logs:
  enabled: false
  retention-days: 30
  # Buffer flush cadence (seconds). Lower = less data loss on a JVM crash, higher = fewer DB
  # roundtrips. The buffer is also flushed when batch-size entries accumulate, on /scs reload,
  # and on plugin disable.
  flush-interval-seconds: 5
  # Max entries kept in the in-memory buffer before forcing a flush.
  batch-size: 20

When enabled, all claim actions (permission changes, flag changes, member management, etc.) are logged with timestamps and player information. Logs older than retention-days are automatically purged.

Buffering

Writes do not hit the database one row at a time. Entries are buffered in memory and flushed in two cases: every flush-interval-seconds on a timer, or as soon as batch-size rows accumulate — whichever comes first. The buffer is also drained synchronously on /scs reload and on shutdown, so the only realistic data-loss window is a hard JVM crash within the last flush-interval-seconds seconds.

Exporting logs to CSV

/scs exportAuditLogs <claimId|*>

Dumps the audit log of a specific claim — or all claims with * — into a CSV file under plugins/SimpleClaimSystem/audit-exports/. Useful for external review, compliance, or just keeping a copy before retention-days drops old rows.

Plugin Hooks

Every optional integration can be disabled with a single flag in config.yml. Useful when another plugin is installed for its own reasons and you don't want SCS2 talking to it, or when troubleshooting ("does this still happen with the Dynmap hook off?").

hooks:
  vault: true              # economy (claim buy/sell, tax)
  worldguard: true         # registers the scs-claim custom flag
  placeholderapi: true     # %scs_*% placeholders
  geyser: true             # Bedrock client detection
  floodgate: true          # Bedrock UUID mapping
  dynmap: true
  bluemap: true
  pl3xmap: true
  squaremap: true
  quickshop-hikari: true
  griefprevention: true
  lands: true
  towny: true
  nexo: true               # <glyph:...> and <shift:N> tags
  oraxen: true
  itemsadder: true
  pvpmanager: true         # block combat-tagged players from no-PvP claims (needs PvPManager)

Set any hook to false and SCS2 skips the entire setup — no retry timer, no listener registration, no performance cost. PacketEvents is a hard dependency and cannot be disabled here.

Disabling the vault hook automatically forces claims.economy.enabled to false (can't have economy features without an economy provider). Disabling map hooks removes the overlay; it doesn't delete stored claim geometry.

Bedrock Players

When Geyser/Floodgate is installed, SCS2 detects Bedrock clients and routes them through native forms (SimpleForm / CustomForm) instead of the Java chest GUIs. Two knobs control this:

bedrock:
  # true  → Bedrock players see the Java chest GUIs (translated by Geyser).
  # false → Bedrock players see the native forms defined under bedrock-guis/*.yml.
  force-java-menus: false

When to enable force-java-menus

• Your resource pack uses Nexo/Oraxen glyphs that don't render on native Bedrock forms.
• You want visual parity between Java and Bedrock clients.
• You've customized Java GUIs heavily and don't want to maintain two separate UI trees.

Caveat

Chest GUIs translated by Geyser have quirks: shift-click doesn't always fire, some items render without custom model data, and closing via "E" vs the native close button behaves differently. For anything complex, the native Bedrock forms (below) give a better UX.

Default Player Settings

Values under players.default are copied to each player the first time they join. Existing players are migrated lazily — when their data is loaded, any missing key from this block is added automatically (no server-wide scan needed).

players:
  default:
    # Auto-actions — toggle via /claim auto-*
    auto-claim: false
    auto-unclaim: false
    auto-addchunk: false
    auto-delchunk: false
    auto-merge: false
    auto-fly: false
    auto-map: false

    # Hard ownership limits (0 = unlimited)
    max-claims: 0
    max-chunks: 1
    max-radius: 1

    # Default radius applied to /claim with no argument (and /claim create <name>).
    # 0 = single chunk. 1+ = behave like /claim radius N. Capped at max-radius.
    default-claim-radius: 0

    # Internal — id of the claim selected with /claim respawn. 0 = none. Do not edit by hand.
    respawn-claim-id: 0

    # Internal — sentinel for the last successful tax debit. The default is the literal
    # string "none" (player never taxed); the job replaces it with a yyyy-MM-dd HH:mm:ss timestamp
    # after the first debit. Do not edit by hand.
    last-tax-paid: "none"

    # Economy (only active when claims.economy.enabled = true)
    chunk-cost: 0.0
    cost-multiplier: 1.0
    max-claim-price: 0.0

    # Membership / role limits (per claim)
    max-members: 3
    max-roles: 3

    # Misc gameplay
    distance: 1     # min chunk distance between this player's claims and other players'
    delay: 5        # teleport delay in seconds (/claim tp, menu tp, etc.)
    fly: 0          # remaining claim-fly seconds; replenished via /scs player commands

    # /claim auto-X anti-abuse timers (seconds). 0 disables.
    auto-default-timer: 0   # default timer when no [seconds] passed
    auto-max-timer: 0       # hard cap on player-supplied [seconds]

    # When true, the auto-purge job skips this player even if inactive
    auto-purge-bypass: false

    # Claim-chat socialspy (needs scs.admin.socialspy). Toggled in-game with /scs socialspy.
    socialspy: false

Key reference

Any of these can be overridden per player via permissions or admin commands — see the Limits page.

Claims Settings

claims:
  # Auto-purge inactive claims
  auto-purge:
    enabled: true
    checker: 1h
    time-without-login: 90d
    # Days before purge to start warning the affected owner on join. 0 = no warning.
    warn-days-before: 7

  # Claim tax / rent (requires Vault) — see Features > Claim Tax / Rent
  tax:
    enabled: false
    taxation-period: 1d
    amount-per-chunk: 1.0
    grace-periods: 3

  # Allow /claim respawn (see Claiming > Respawn in Claim)
  respawn-in-claim:
    enabled: false

  # /claim back scope. false = any visited claim. true = only the player's own claims.
  claim-back:
    only-own-claims: false

  # Confirmation prompts — action must be run twice to execute
  confirmation:
    claim: false
    unclaim: false
    addchunk: false
    delchunk: false
    merge: false
    owner: true
  confirmation-delay: 30

  # Let claim MODERATORs (not just the owner) manage members / bans / chunks via the
  # normal commands, targeting the claim as "<owner>:<claim>" (tab-completed).
  # Moderators can never promote/demote, nor target the owner or another moderator.
  moderator-management:
    members: true
    banned: true
    chunks: true

  # Protection violation delivery: CHAT | ACTIONBAR | TITLE | NONE
  protection-message: CHAT

  # Particles
  show-particles: true
  show-particles-for-bedrock: false
  see-duration-seconds: 10            # /claim see border display duration (seconds) — 2.6.6

  # Names & descriptions
  template-name: "claim-%n"
  max-length-name: 32
  allowed-regex-name: "^[a-zA-Z0-9]+$"
  max-length-description: 64
  allowed-regex-description: "^[a-zA-Z0-9\\s]+$"
  blocked-words: ["fuck", "asshole"]

  invitation-delay: 120               # seconds before an invite expires
  only-adjacent-chunks: false
  addchunk-instead-if-possible: false

  # When a player's max claims/chunks is lowered below what they already own
  # (admin set-max-* / add-* commands), delete the surplus. Default: false.
  auto-delete-excess-on-limit-reduction: false

  # Default metadata applied to every new claim
  default:
    isBuyable: false
    price: 0.0
    icon: FARMLAND
    particles: false
    warp: false       # public warp closed by default (toggle via /claim settings)
    visitPrice: 0.0   # /claim visit fee charged to visitors (0 = free)

  # Plugin message channels — each has independent enter / leave toggles.
  messages:
    chat:
      enter: false
      leave: false
    actionbar:
      enter: true
      leave: true
    title:
      enter: false
      leave: false

  # Claim economy (requires Vault)
  economy:
    enabled: true
    max-price: 1_000_000_000
    formatted-number: true
    # /claim sell broadcast channels.
    announce:
      chat: true
      actionbar: false
      title: false
      bossbar:
        enabled: true
        color: YELLOW
        overlay: PROGRESS

Key reference

Auto-map & Enter Borders

Two optional visual helpers, both Folia-safe.

Auto-map (chat or scoreboard)

/claim map always prints the claims mini-map in chat. The auto-map (toggled per player) shows it automatically as you move — and you pick where it goes:

claims:
  auto-map:
    display: SCOREBOARD   # SCOREBOARD (live sidebar) or CHAT (printed on claim enter)

• SCOREBOARD (default): a packet-based sidebar (via FastBoard — works on Folia, where the Bukkit Scoreboard API throws). It shows the exact same map as /claim map and refreshes every time the player changes chunk (move or teleport). Only displayed while the player has auto-map enabled.
• CHAT: the classic behaviour — the map is printed in chat when the player enters a claim.

The sidebar title is the auto-map-scoreboard-title key in your language file; the map symbols/colours reuse the existing map-* language keys, so the chat and scoreboard maps stay identical.

Borders on enter

Briefly flash a claim's chunk borders when a player walks or teleports into it:

claims:
  show-borders-on-enter: false   # default off

The colour reflects the viewer's relation to the claim: green = your own, yellow = a claim you're a member of, pink = a protected area (server-owned), red = anyone else's. Skipped when the claim already shows a continuous border to its members (no double display).

Claim Holograms

SCS2 renders a floating Text Display hologram at each claim's spawn, shown to nearby players. It is fully packet-based and client-side (no real server entity), proximity-rendered, event-driven (no per-tick task) and kept in sync live whenever a claim changes. Bedrock players are skipped (Text Display does not render through Geyser). Enabled by default; turn it off with enabled: false.

Configuration

Under claims.hologram in config.yml (reload with /scs reload):

claims:
  hologram:
    enabled: true
    view-distance: 48          # blocks; the hologram appears within this range of its claim spawn
    height: 2.0                # vertical offset above the spawn block
    billboard: CENTER          # CENTER (faces the player), FIXED, VERTICAL, HORIZONTAL
    scale: 1.0                 # text size multiplier
    text-shadow: true          # drop shadow behind the text
    background: transparent    # 'transparent', 'default' (vanilla), or an ARGB hex e.g. '#40000000'
    brightness: 15             # 0-15 = constant light (15 = always readable), -1 = follow world light
    shadow-radius: 0.0         # block-shadow cast under the hologram (0 = none)
    shadow-strength: 1.0
    members-per-line: 3        # member names per line before wrapping
    # The hologram lines and the member / ban / flag / status text formats are defined
    # in your language file (keys: hologram-lines, hologram-member-online, …) — see below.

Appearance keys

The text bits live in your language file (not config): hologram-lines (the line list), hologram-member-online / hologram-member-offline (each name in %member-list%; %name% = the name; default green/red by online state), hologram-ban-format (%ban-list%), hologram-flag-true / hologram-flag-false (on/off marker for %flag-X% and %perm-X%, default ✔/✘), and hologram-status-yes / hologram-status-no (%warp% / %for-sale%).

Line placeholders

Each line in hologram-lines (in your language file) is a full MiniMessage string (colors, gradients, fonts…). Available placeholders:

Conditional & empty lines

Prefix a line to show it only in certain states:

• [buyable] / [notbuyable] — only when the claim is (not) for sale.
• [members] / [nomembers] — only when the claim has (no) members besides the owner.
• [warp] / [nowarp] — only when the claim has (no) open public warp.
• [bans] / [nobans] — only when the claim has (no) banned players.
• [owner] / [member] / [visitor] — by the viewing player's relation to the claim (owner / added member / neither).

Any line that renders empty after substitution (e.g. an empty description) is skipped automatically, so optional info never leaves a blank gap.

Line breaks & PlaceholderAPI

• Add a line break inside a single entry with <newline> (MiniMessage) or a literal \n.
• If PlaceholderAPI is installed, any %placeholder% it knows is resolved against the viewing player, so each player sees their own values. These refresh on the same triggers as the rest of the hologram (move, chunk cross, teleport, claim change), not continuously.

BossBar & Sounds

A BossBar is displayed when players are inside a claim (one color per role) and, optionally, when they are outside any claim (one color per world mode). Available colors: PINK, BLUE, RED, GREEN, YELLOW, PURPLE, WHITE. Available overlays: PROGRESS, NOTCHED_6, NOTCHED_10, NOTCHED_12, NOTCHED_20.

claims:
  bossbar:
    enabled: true
    # Outside any claim. Color/overlay/progress are configured per world mode.
    always-visible:
      survival-mode:
        enabled: true
        color: WHITE
        overlay: PROGRESS
        progress: 1.0
      survival_requiring_claims-mode:
        enabled: true
        color: WHITE
        overlay: PROGRESS
        progress: 1.0
      protected-mode:
        enabled: true
        color: GREEN
        overlay: PROGRESS
        progress: 1.0
      disabled-mode:
        enabled: true
        color: RED
        overlay: PROGRESS
        progress: 1.0
    # Inside a claim — one block per role.
    visitor:
      color: WHITE
      overlay: PROGRESS
      progress: 1.0
    member:
      color: GREEN
      overlay: PROGRESS
      progress: 1.0
    moderator:
      color: PURPLE
      overlay: PROGRESS
      progress: 1.0
    owner:
      color: BLUE
      overlay: PROGRESS
      progress: 1.0

Sounds

SCS2 ships 40 configurable sounds for every action: claiming, unclaiming, teleporting, entering/leaving claims, banning, kicking, merging, flying, inviting, and more. Each sound can be individually configured or disabled in claims.sounds.*.

Map Integration

SCS2 supports Dynmap, BlueMap, Pl3xMap, and squaremap with fully customizable visual styles:

dynmap:
  enabled: true
  show-labels: true
  boosted: false          # renderer-specific render boost (see below)
  styles:
    normal:
      line-weight: 2
      line-opacity: 0.8
      line-color: "00FF00"
      fill-opacity: 0.3
      fill-color: "00FF00"
      label-format: "%claim_name%"
      popup-format: |        # HTML shown when a claim is clicked on the map
        %claim_name%
Owner: %owner_name%
%description%
    for-sale:
      line-color: "FFCC00"
      fill-color: "FFCC00"
      popup-format: |
        %claim_name%
Price: %price%$

Normal claims and for-sale claims can have different visual styles on the map. show-labels toggles the always-on claim-name label; boosted applies a renderer-specific rendering boost (Dynmap's area boost flag, or disabling BlueMap's depth test so markers show through terrain); popup-format is the HTML shown when a claim is clicked, with placeholders %claim_name%, %owner_name%, %description% and (for-sale) %price%. The same structure applies for the bluemap, pl3xmap, and squaremap sections.