QuestLines Claims

How It Works

QuestLines Claims protects land by intercepting block, interaction, and combat events and checking whether the acting player is allowed to perform that action at the target position. Permission is resolved by walking a four-step chain and stopping at the first match:

1. Admin regions that contain the position, highest priority first.
2. Rent/Buy regions that contain the position.
3. Player claim at the position’s chunk, if any.
4. Wilderness defaults (global flag set with optional per-player overrides).

At every layer, members with an explicit entry check their per-member flag allow-list first; otherwise the layer’s default flag set applies. Players with questlinesclaims.admin bypass all protection checks.

Region Types

Four kinds of protected area can exist on the server. Player claims are chunk-based; admin, rent, and buy regions are arbitrary rectangles in blocks (optionally extended vertically to the full world height).

Permission Flags

Every region and claim has a default flag set (what non-members can do) plus a per-member flag set (what each listed member can do). A flag being in the set means the action is allowed.

Flag Exclusions

Admin regions can whitelist specific block or item IDs for a denied flag. Patterns are case-insensitive and support * wildcards (e.g. *stone, Iron_*, *_door*). This is useful for spawn regions that should deny BREAK broadly but still allow chopping trees.

Wilderness Flags

Unclaimed land uses the wilderness_flags config entry (all flags enabled by default). Admins can override the wilderness flag set for specific players via /claim manage run outside any claim or region.

Priority Resolution

When multiple regions cover the same block, admin regions are sorted by their priority field (descending) and only the top region is consulted. The resolution order for a given (world, x, y, z) is:

1. Highest-priority admin region at that position (if any).
2. First rent or buy region at that position.
3. Player claim that owns the position’s chunk.
4. Wilderness defaults.

Admin regions cover any player claim they overlap — players cannot claim chunks that intersect an admin, rent, or buy region.

Player Claims

Players use /claim map to open a grid of chunk cells centred on their current position. Green cells are unclaimed and can be clicked to claim; cells in the player’s own claims are shown in that claim’s colour and can be managed; cells owned by others or under admin regions are read-only.

Contiguity

Claims must be a single contiguous chunk group (4-way adjacency). Adding a chunk requires it to be adjacent to an existing chunk in that claim. Removing a chunk that would split the claim into disconnected pieces is refused (a breadth-first search verifies remaining chunks stay connected).

Chunk Limits

Every player has a total-chunk budget across all their claims. The budget is:

• default_max_chunks (default 25) — base from config.
• + N for every questlinesclaims.claim.chunks.N permission the player holds. Multiple matching permissions stack (N = 1–500).
• + bonus — admin-granted chunks via /claim addchunks.

Claim Separation

The distance_between_claims config value (default 1 chunk) sets a minimum buffer between claims of different players. Set to 0 to allow claims to touch.

Claim Colours

Each claim is assigned a random vivid HSV colour on creation. Owners can pick a specific colour or re-roll at random through the claim map UI. The colour appears as an overlay on the world map so players can see claim boundaries at a glance.

Members and Flags

Claim owners open /claim members (inside their claim) or use the Members button in the claim map to add trusted players. Each member has their own allowed-flag set; unlisted players fall back to the member default flags set for the claim.

Admin Regions

Admins define rectangular protected regions with a wand workflow:

1. Run /claim wand to receive the Claim Staff.
2. Left-click a block to set Pos1, right-click a block to set Pos2.
3. A selection box outline renders between the two corners.
4. Run /claim admin to open the admin region list, then Create from Wand Selection.

The creation form asks for name, priority, type (Admin / Rent / Buy), and — for rent/buy — price and duration. Checking Expand Y extends the region vertically to cover the full world height regardless of the clicked Y coordinates.

Rent and Buy Regions

Rent and buy regions require VaultUnlocked. Players browse them via /claim rentbuy, which opens a filtered list of available, owned, and locked plots.

Buying

Buy regions are a one-time purchase. On confirmation the price is withdrawn from the player and they become the region owner for as long as the region exists. Buy regions have no expiry and no grace period.

Renting

Rent regions have a price and a durationSeconds. The rent cycle begins when the tenant rents the plot; the lease renewal timer fires at leaseStart + durationSeconds.

The RentExpireTask runs on a scheduled executor (rent_check_interval seconds, default 300). On each tick it:

1. Sends warning notifications at each configured expiry_warn_times threshold that hasn’t fired yet.
2. When the lease expires, attempts to withdraw another full cycle of rent from the tenant. If that succeeds, leaseEnd advances by durationSeconds and the lease continues.
3. If the renewal fails (insufficient funds), the region enters a locked state: all members and the tenant lose access, and a countdown to reset begins.
4. After rent_grace_days days in the locked state, the region’s tenancy is cleared and, if a schematic was saved, the saved prefab is pasted back to restore the region to its original state.

When refund_on_reset=true, the pro-rated remaining lease value is refunded to the tenant on reset. Default is false.

Notifications

Expiry warnings, lock notices, and reset notices are sent both as a NotificationUtil toast (if the tenant is online) and as a chat message. If the tenant is offline, the message is stored as a PendingNotification and flushed to chat on their next connect.

Schematics

Rent/Buy regions can have an associated prefab captured from the region volume. Saving is triggered from the admin region edit UI and runs on the world executor via the Hytale PrefabSaver. Prefabs are stored under prefabs/questlinesclaims/<regionId>.prefab and are pasted back on rent reset (and can be manually restored from the admin UI).

Commands

Root command: /claim.

Player Commands

Admin Commands

All commands below require questlinesclaims.admin.

Configuration

All plugin-level settings live in mods/QuestLinesClaims/questlinesclaims.conf. Missing keys are written back with defaults on first load.

Database

Region and claim data is stored in a SQL database. SQLite is the default and keeps a local file at mods/QuestLinesClaims/claims.db. Switch to MySQL or MariaDB by setting database_type and filling in the connection parameters. Database changes require a server restart.

Permissions

Integrations

VaultUnlocked

Rent and buy features require VaultUnlocked. At startup Claims probes for net.cfh.vault.VaultUnlockedServicesManager; if absent, economy is disabled, and rent/buy transactions return ECONOMY_UNAVAILABLE. Withdrawals and refunds go through the standard Vault economy object so any Vault-backed currency plugin works transparently.

World Map

Claims installs its own IWorldMapProvider that draws the usual terrain plus an overlay of claim colours and admin region boundaries. Invalidation is automatic: claiming, unclaiming, renaming, or recolouring a claim triggers a redraw of the affected chunks plus their neighbours.

Entry & Title Systems

Two ECS ticking systems run per-player while they are in-world:

• ClaimTitleSystem — shows a short title announcement when a player crosses into a new claim or region. Admin regions show in cyan, player claims show in the owner’s claim colour, wilderness shows in green as “Wilderness”.
• EntryEnforcementSystem — remembers the player’s last allowed position and teleports them back when they enter a position where the ENTRY flag is denied. Admins bypass this check.

File Layout