Server documentation

BetterClaim

Active

Hytale • Version 1.5.1

Complete setup guide for server owners: commands, hierarchical permissions, configuration reference, and admin workflows.

Mod overview CurseForge

Every BetterClaim command, permission node, config option, and common setup pattern for Hytale server owners.

Inspired by SimpleClaims.

Overview

BetterClaim lets players own individual chunks, manage parties with a full GUI, mark admin deny zones, set homes inside claims, and sync claim colors on /bc and the world map (M). Data persists in SQLite per world save.

Installation

Download BetterClaim-1.5.1.jar from the CurseForge Files tab
Place the JAR in your server’s mods/ folder (or Hytale user mods folder for singleplayer)
Start the server, config is generated at plugins/BetterClaim/config.json
Grant permissions to your player groups (see Permissions below)
Use /bc in-game to open the BetterClaim hub (or the claim map directly if useBcHubUi is false)

Optional: install LuckPerms so dynamic nodes (betterclaim.limit.N, betterclaim.playtime.N, betterclaim.admin.max-add-limit.N) resolve with inherited group permissions. Without LuckPerms, BetterClaim uses the native Hytale permission providers (same as 1.2.x).

Singleplayer: use /perm group add OP betterclaim.gui (and other nodes as needed) to grant yourself access.

Admin Commands

Main command: /bc (alias: /betterclaim)

Player commands are listed on the mod overview page.

Command	Description
`/bc admin`	Opens the admin player list GUI
`/bc admin players`	Select a target player for admin actions
`/bc admin chunk`	Opens the claim map in admin mode for the selected target
`/bc admin party`	Edit any party as admin
`/bc admin claim`	Claims the current chunk for the selected target player
`/bc admin unclaim`	Unclaims the current chunk for the selected target player
`/bc admin override`	Toggles bypassing claim limits and full claim protection while using admin tools
`/bc admin denyzone`	Opens the deny zones admin GUI (recommended)
`/bc admin denyzone start`	Starts deny zone selection (map or chat)
`/bc admin denyzone cancel`	Cancels an in-progress selection
`/bc admin denyzone confirm <name>`	Saves the region after both corners are set
`/bc admin denyzone pos1`	Saves corner 1 (current chunk or via map)
`/bc admin denyzone pos2`	Saves corner 2 of a no-claim rectangle
`/bc admin denyzone create <name>`	Creates a persisted zone from pos1 + pos2 (legacy flow)
`/bc admin denyzone list`	Lists all claim-denied regions
`/bc admin denyzone remove <name>`	Removes a claim-denied region
`/bc admin set-limit <player> <limit>`	Sets a persistent claim limit override
`/bc admin add-limit <player> <amount>`	Adds bonus claim chunks to a player
`/bc admin create-party <player> [name]`	Creates a party for a player

Admin chunk mode: run /bc admin players first to select a target, then use /bc admin chunk or the admin claim/unclaim commands.

Deny zones (claim-denied regions)

Rectangular areas where players cannot create new claims. Admins with betterclaim.admin or betterclaim.admin.chunk can create and remove zones.

Recommended flow (GUI)

/bc admin → open Deny zones
Click Start — opens the selection map centered on your position
Click two chunks (corner 1 and corner 2). Works on wilderness and already-claimed chunks
Use Back to return to the admin panel (selection stays active)
Enter a name and click Save

While selecting, an orange preview appears on the /bc map and on the in-game world map (M key). Saved zones do not keep permanent preview particles.

Alternative flow (chat)

/bc admin denyzone start
/bc admin denyzone pos1    # or click on the map
/bc admin denyzone pos2
/bc admin denyzone confirm MyZone

To cancel: /bc admin denyzone cancel or the GUI equivalent.

Maintenance commands

/bc admin denyzone list — list saved zones
/bc admin denyzone remove <name> — remove a zone

Permissions

BetterClaim uses hierarchical permissions. Granting a parent node also grants all its children.

Command Permissions

Permission	Grants access to
`betterclaim.gui`	`/bc`: territory map GUI
`betterclaim.claim`	`/bc claim` and claim clicks in GUI
`betterclaim.unclaim`	`/bc unclaim` and unclaim clicks in GUI
`betterclaim.home`	`/bc sethome`, `/bc home`, `/bc delhome`, `/bc homes`
`betterclaim.party`	All party subcommands (parent node)
`betterclaim.party.edit`	`/bc party`: party GUI
`betterclaim.party.create`	`/bc party create`
`betterclaim.party.invite`	`/bc party invite`
`betterclaim.party.accept`	`/bc party accept`
`betterclaim.party.decline`	`/bc party decline`
`betterclaim.party.leave`	`/bc party leave`
`betterclaim.party.kick`	`/bc party kick`
`betterclaim.party.transfer`	`/bc party transfer`
`betterclaim.party.disband`	`/bc party disband`
`betterclaim.admin`	All admin subcommands (parent node)
`betterclaim.admin.players`	`/bc admin`, `/bc admin players`
`betterclaim.admin.chunk`	`/bc admin chunk`
`betterclaim.admin.party`	`/bc admin party`
`betterclaim.admin.claim`	`/bc admin claim`
`betterclaim.admin.unclaim`	`/bc admin unclaim`
`betterclaim.admin.override`	`/bc admin override`
`betterclaim.admin.set-limit`	`/bc admin set-limit`
`betterclaim.admin.add-limit`	`/bc admin add-limit`
`betterclaim.admin.create-party`	`/bc admin create-party`

Dynamic Permissions

When a player has multiple matching nodes, the highest value wins.

Permission	Description
`betterclaim.limit.N`	Base claim limit per player (e.g. `betterclaim.limit.10` = 10 chunks). Highest matching value wins.
`betterclaim.playtime.N`	Minutes of playtime per bonus chunk (e.g. `betterclaim.playtime.120`). Highest matching value wins; overrides config when greater than 0.
`betterclaim.admin.max-add-limit.N`	Maximum total claim limit reachable via `/bc admin add-limit` for that admin.

Limit Calculation Order

Admin /bc admin set-limit override (database): highest priority
Permission betterclaim.limit.<N> (highest value)
Config defaultClaimLimit
Playtime bonus chunks (if enabled)
Admin /bc admin add-limit bonus chunks
Capped by config maxClaimLimit (unless admin override mode is active)

Quick Setup with Hytale /perm

Default players (Adventure group example):

/perm group add Adventure betterclaim.gui
/perm group add Adventure betterclaim.claim
/perm group add Adventure betterclaim.unclaim
/perm group add Adventure betterclaim.home
/perm group add Adventure betterclaim.party
/perm group add Adventure betterclaim.limit.10

Staff / admins (OP group example):

/perm group add OP betterclaim.admin

LuckPerms

BetterClaim declares LuckPerms as an optional dependency. Command checks still go through Hytale’s PermissionsModule (LuckPerms registers as a provider). Dynamic numeric nodes (betterclaim.limit.N, betterclaim.playtime.N, betterclaim.admin.max-add-limit.N) use LuckPerms inherited permissions when LuckPerms is active, so VIP groups and inheritance work as expected.

Example setup:

/lp group default permission set betterclaim.gui true
/lp group default permission set betterclaim.party true
/lp group default permission set betterclaim.limit.10 true
/lp group vip permission set betterclaim.limit.20 true
/lp group admin permission set betterclaim.admin true
/lp user <player> permission set betterclaim.playtime.120 true

After changing LuckPerms data, run /lp sync (or your usual reload) and re-check limits in /bc.

Configuration

Config file: plugins/BetterClaim/config.json (auto-generated on first run)

Claim Limits

Option	Default	Description
`defaultClaimLimit`	`5`	Starting claim limit per player
`maxClaimLimit`	`50`	Hard cap on total claims (unless admin override)
`enablePlaytimeClaimGain`	`true`	Enable bonus chunks from playtime
`claimGainMinutes`	`600`	Minutes of playtime per bonus chunk
`enableAdjacentClaims`	`false`	Require new claims to touch an existing claim (first claim is free)
`creativeBypassProtection`	`true`	Creative mode players ignore claim protection
`worldNameBlacklistForClaiming`	`[]`	World names where players cannot claim (exact match)
`scaleClaimLimitByPartyMembers`	`false`	(unused) Legacy config flag
`showPartyTotalClaims`	`false`	Show party total instead of personal count in GUI

Party

Option	Default	Description
`maxPartyMembers`	`10`	Maximum members per party
`maxPartyAllies`	`-1`	Maximum allies (-1 = unlimited)
`enableAllySystem`	`true`	Enable player/party allies
`enablePartyInactivityDisband`	`false`	Disband parties when the owner exceeds the inactivity threshold
`partyInactivityDisbandDays`	`30`	Days of owner inactivity before auto-disband
`partyInactivityCheckIntervalMinutes`	`60`	How often the server runs the inactivity check (minimum 5)

Zone Titles & Sounds

Option	Default	Description
`wildernessName`	`Wilderness`	Name shown for unclaimed areas
`titleTopText`	(empty)	Optional text shown above zone titles
`personalClaimSubtitle`	`Personal Claim`	Subtitle for personal claims
`enableZoneTitles`	`true`	Show zone title on entry
`showWildernessZoneTitle`	`true`	Show title when entering wilderness
`enableClaimEntrySound`	`true`	Play sound on claim entry
`claimEntrySoundOncePerZone`	`true`	Only once per zone visit
`claimEntrySoundId`	`SFX_Discovery_Z1_Short`	Sound ID

Map & Visuals

Option	Default	Description
`enableCustomMap`	`true`	Terrain map in /bc GUI
`mapOverlayAlpha`	`0.5`	World map claim overlay opacity
`guiMapResolutionScale`	`0.75`	GUI map resolution (0.1–1.0)
`guiMapCacheTtlSeconds`	`120`	Map image cache TTL in seconds
`enableParticleBorders`	`true`	Particle borders at chunk edges
`useBcHubUi`	`true`	`/bc` opens the hub (map / party / create) instead of the claim map only

Homes

Option	Default	Description
`maxHomes`	`5`	Maximum homes per player
`homeCooldownSeconds`	`5`	Teleport cooldown

Global Protection

Option	Default	Description
`protectBuckets`	`true`	Block outsider fluid placement and container refill in protected claims
`protectBenches`	`true`	Protect crafting benches
`isolateCraftBenchMaterials`	`true`	Bench crafts only use the player’s inventory plus nearby chests they may access
`protectTamedEntities`	`true`	Block outsider damage to tamed NPC roles inside claims (party flag applies)
`tamedEntityRoleIdentifiers`	`Tamed_`	NPC role name prefixes treated as tamed companions
`blocksThatIgnoreInteractRestrictions`	`gravestone, tombstone, corpse, loot_chest`	Blocks always interactable

Default Party Protection (new parties)

Option	Default	Description
`defaultPartyBlockPlaceEnabled`	`false`	Allow non-members to place blocks
`defaultPartyBlockBreakEnabled`	`false`	Allow non-members to break blocks
`defaultPartyBlockInteractEnabled`	`false`	Allow non-members to interact with blocks
`defaultPartyPVPEnabled`	`false`	Allow PVP in party claims
`defaultPartyFriendlyFireEnabled`	`false`	Allow friendly fire between members
`defaultPartyInteractChest`	`false`	Allow non-members to open chests
`defaultPartyInteractDoor`	`false`	Allow non-members to use doors
`defaultPartyInteractBench`	`false`	Allow non-members to use benches
`defaultPartyInteractChair`	`false`	Allow non-members to use chairs
`defaultPartyInteractPortal`	`false`	Allow non-members to use portals
`defaultPartyTamedDamageEnabled`	`false`	Allow non-members to damage tamed entities

Party Owner Toggles

Option	Default	Description
`allowPartyPlaceBlockSetting`	`true`	Owner can toggle block placing for non-members
`allowPartyBreakBlockSetting`	`true`	Owner can toggle block breaking for non-members
`allowPartyInteractBlockSetting`	`true`	Owner can toggle block interaction for non-members
`allowPartyPVPSetting`	`true`	Owner can toggle PVP
`allowPartyFriendlyFireSetting`	`true`	Owner can toggle friendly fire
`allowPartyInteractChestSetting`	`true`	Owner can toggle chest access
`allowPartyInteractDoorSetting`	`true`	Owner can toggle door access
`allowPartyInteractBenchSetting`	`true`	Owner can toggle bench access
`allowPartyInteractChairSetting`	`true`	Owner can toggle chair access
`allowPartyInteractPortalSetting`	`true`	Owner can toggle portal access
`allowPartyTamedDamageSetting`	`true`	Owner can toggle tamed entity damage

Example config.json

{
  "configVersion": 28,
  "useBcHubUi": true,
  "worldNameBlacklistForClaiming": [],
  "tamedEntityRoleIdentifiers": ["Tamed_"],
  "defaultClaimLimit": 5,
  "maxClaimLimit": 50,
  "enablePlaytimeClaimGain": true,
  "claimGainMinutes": 600,
  "enableAdjacentClaims": false,
  "creativeBypassProtection": true,
  "enablePartyInactivityDisband": false,
  "partyInactivityDisbandDays": 30,
  "partyInactivityCheckIntervalMinutes": 60,
  "maxPartyMembers": 10,
  "maxPartyAllies": -1,
  "enableAllySystem": true,
  "enableCustomMap": true,
  "enableParticleBorders": true,
  "maxHomes": 5,
  "homeCooldownSeconds": 5
}

See the full default config inside plugins/BetterClaim/config.json after first launch.

Notes

GUI claim/unclaim requires betterclaim.claim / betterclaim.unclaim. Party members always claim personal chunks: no separate party claim permission.
Admin chunk mode requires selecting a target first with /bc admin players.
Admin override requires betterclaim.admin.override and bypasses limits and protection.
Claim-denied regions are stored in SQLite and block player claims in the marked rectangle.
Deny zones do not block players from walking through; they only prevent new claims in the area.
Set useBcHubUi to false if you prefer /bc to open the claim map directly (legacy behavior).
Worlds listed in worldNameBlacklistForClaiming reject new claims with an in-game message.
With LuckPerms installed, check the server log for LuckPerms detected on startup when dynamic limits should use group inheritance.
Disbanding a party keeps claims. They remain owned by individual players (including auto-disband from owner inactivity).
Party inactivity disband is disabled by default; enable enablePartyInactivityDisband and set partyInactivityDisbandDays to activate it.
Database location: universe/BetterClaim/BetterClaim.db (inside your world save)