Server & storage

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: []
  cc: []
  requnclaim: []
  viewrequnclaim: []

# Base commands to unregister entirely (see the key reference below)
disabled-commands: []

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
  ssl-mode: PREFERRED    # MySQL TLS: DISABLED, PREFERRED, REQUIRED, VERIFY_CA, VERIFY_IDENTITY
  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: 30000

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, but since 2.8 it also doubles as a real-time cross-server sync bus (see Multi-server setup below): several servers sharing one Redis + one MySQL now see each other's claim changes instantly.

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
  username: ""                  # Redis 6+ ACL user; empty = default user
  password: ""                  # empty = no auth; set on any internet-facing Redis
  ssl: false                    # enable TLS to the Redis server
  cross-server-sync: true       # publish cache invalidations so other servers see changes live
  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.

Multi-server setup (2.8)

Point several servers at the same MySQL database and the same Redis, with redis.enabled: true and redis.cross-server-sync: true (the default). From then on the servers stay coherent in real time:

• Every claim mutation (create, unclaim, add/remove chunk, rename, description, spawn, icon, members, roles, bans, permissions, flags, sale, ownership transfer) writes to MySQL + Redis, then publishes an invalidation on the scs:invalidate Redis channel.
• Each other server is subscribed to that channel and, on receipt, drops the affected chunks from its local Caffeine cache, reads the fresh claim back from Redis and applies it: holograms, map markers, bossbars, the public-warp and spawn indexes and the per-player claim lists are all refreshed on the spot, so the change shows up within milliseconds, without a reload or a reconnect.
• Per-player data travels on the same channel: every write to a player's data (limits, settings, purge grace, tax meter, favourites) publishes an invalidation, and a player's data is always re-read at login, so a change made on one server is visible on the others right away — including for a player currently connected elsewhere.
• Unclaim requests, template names and claim-name lists are kept in step the same way, and a bulk rewrite (config migration, custom flag backfill, admin reset) sends a single flush that makes every server reload its cached claims.
• The recurring jobs that must run once per network (tax collector, auto-purge, temporary-member sweep, unclaim-request sweep) take a short Redis lock before each run, so only one server executes them per interval and nobody is billed or purged twice.
• A server ignores its own messages (each instance has a random id), so there is no echo loop, and cache warm-up loads (login, /scs reload) do not broadcast, so the channel stays quiet.

# Same config on every server:
database:
  enabled: true            # one shared MySQL
  # ...same host/name/credentials everywhere...
redis:
  enabled: true            # one shared Redis
  cross-server-sync: true
  # ...same host everywhere...

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