Server documentation

BetterClaim

Active

Hytale • Version 1.5.1

Guia completo de configuração para donos de servidor: comandos, permissões hierárquicas, referência de configuração e fluxos de admin.

Mod overview CurseForge

Comandos, permissões, configuração e fluxos comuns de admin do BetterClaim para donos de servidores Hytale.

Aviso: Mod inspirado em SimpleClaims.

Instalação

Baixe BetterClaim-x.x.x.jar na aba Files do CurseForge
Coloque o JAR na pasta mods/ do servidor (ou na pasta de mods do usuário Hytale para singleplayer)
Inicie o servidor; a config é gerada em plugins/BetterClaim/config.json
Conceda permissões aos grupos de jogadores (veja Permissões abaixo)
Use /bc no jogo para abrir o hub BetterClaim (ou o mapa de claims diretamente se useBcHubUi for false)

Opcional: instale LuckPerms para que nós dinâmicos (betterclaim.limit.N, betterclaim.playtime.N, betterclaim.admin.max-add-limit.N) resolvam com permissões de grupo herdadas. Sem LuckPerms, o BetterClaim usa os provedores nativos de permissão do Hytale (igual ao 1.2.x).

Singleplayer: use /perm group add OP betterclaim.gui (e outros nós conforme necessário) para conceder acesso a si mesmo.

Comandos de admin

Comando principal: /bc (alias: /betterclaim)

Comandos de jogador estão listados na página de visão geral do mod.

Comando	Descrição
`/bc admin`	Abre a GUI de lista de jogadores para admin
`/bc admin players`	Seleciona um jogador alvo para ações de admin
`/bc admin chunk`	Abre o mapa de reivindicação em modo admin para o alvo selecionado
`/bc admin party`	Edita qualquer grupo como admin
`/bc admin claim`	Reivindica o chunk atual para o jogador alvo selecionado
`/bc admin unclaim`	Remove a reivindicação do chunk atual para o jogador alvo selecionado
`/bc admin override`	Alterna ignorar limites de reivindicação e proteção total enquanto usa ferramentas de admin
`/bc admin denyzone`	Abre a GUI de zonas negadas (recomendado)
`/bc admin denyzone start`	Inicia seleção de zona negada (mapa ou chat)
`/bc admin denyzone cancel`	Cancela a seleção em andamento
`/bc admin denyzone confirm <name>`	Salva a região após definir os dois cantos
`/bc admin denyzone pos1`	Salva o canto 1 (chunk atual ou via mapa)
`/bc admin denyzone pos2`	Salva o canto 2 de um retângulo sem reivindicação
`/bc admin denyzone create <name>`	Cria zona persistida a partir de pos1 + pos2 (fluxo legado)
`/bc admin denyzone list`	Lista todas as regiões com reivindicação negada
`/bc admin denyzone remove <name>`	Remove uma região com reivindicação negada
`/bc admin set-limit <player> <limit>`	Define um override persistente de limite de reivindicação
`/bc admin add-limit <player> <amount>`	Adiciona chunks bônus de reivindicação a um jogador
`/bc admin create-party <player> [name]`	Cria um grupo para um jogador

Modo admin de chunk: execute /bc admin players primeiro para selecionar um alvo, depois use /bc admin chunk ou os comandos admin de claim/unclaim.

Zonas negadas (deny zones)

Regiões retangulares onde jogadores não podem reivindicar chunks novos. Admins com betterclaim.admin ou betterclaim.admin.chunk podem criar e remover zonas.

Fluxo recomendado (GUI)

/bc admin → abra Zonas negadas
Clique Iniciar — abre o mapa de seleção centrado na sua posição
Clique em dois chunks (canto 1 e canto 2). Funciona em wilderness e em chunks já claimados
Use Voltar para retornar ao painel admin (a seleção permanece ativa)
Digite um nome e clique Salvar

Durante a seleção, uma prévia laranja aparece no mapa /bc e no mapa do mundo (tecla M). Não há partículas permanentes após salvar a zona.

Fluxo alternativo (chat)

/bc admin denyzone start
/bc admin denyzone pos1    # ou clique no mapa
/bc admin denyzone pos2
/bc admin denyzone confirm MinhaZona

Para cancelar: /bc admin denyzone cancel ou o botão equivalente na GUI.

Comandos de manutenção

/bc admin denyzone list — lista zonas salvas
/bc admin denyzone remove <nome> — remove uma zona

Permissões

O BetterClaim usa permissões hierárquicas. Conceder um nó pai também concede todos os filhos.

Permissões de comando

Permissão	Concede acesso a
`betterclaim.gui`	`/bc`: GUI do mapa de território
`betterclaim.claim`	`/bc claim` e cliques de reivindicação na GUI
`betterclaim.unclaim`	`/bc unclaim` e cliques de desfazer na GUI
`betterclaim.home`	`/bc sethome`, `/bc home`, `/bc delhome`, `/bc homes`
`betterclaim.party`	Todos os subcomandos de grupo (nó pai)
`betterclaim.party.edit`	`/bc party`: GUI de grupo
`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`	Todos os subcomandos de admin (nó pai)
`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`

Permissões dinâmicas

Quando um jogador tem vários nós correspondentes, o maior valor vence.

Permissão	Descrição
`betterclaim.limit.N`	Limite base de reivindicação por jogador (ex.: `betterclaim.limit.10` = 10 chunks). O maior valor correspondente vence.
`betterclaim.playtime.N`	Minutos de tempo de jogo por chunk bônus (ex.: `betterclaim.playtime.120`). O maior valor correspondente vence; substitui a config quando maior que 0.
`betterclaim.admin.max-add-limit.N`	Limite total máximo de reivindicações alcançável via `/bc admin add-limit` para esse admin.

Ordem de cálculo de limite

Override /bc admin set-limit de admin (banco de dados): maior prioridade
Permissão betterclaim.limit.<N> (maior valor)
Config defaultClaimLimit
Chunks bônus por tempo de jogo (se ativado)
Chunks bônus de /bc admin add-limit
Limitado pela config maxClaimLimit (a menos que o modo override de admin esteja ativo)

Setup rápido com Hytale /perm

Jogadores padrão (exemplo grupo Adventure):

/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 (exemplo grupo OP):

/perm group add OP betterclaim.admin

LuckPerms

O BetterClaim declara LuckPerms como dependência opcional. Verificações de comando ainda passam pelo PermissionsModule do Hytale (LuckPerms se registra como provedor). Nós numéricos dinâmicos (betterclaim.limit.N, betterclaim.playtime.N, betterclaim.admin.max-add-limit.N) usam permissões herdadas do LuckPerms quando o LuckPerms está ativo, então grupos VIP e herança funcionam como esperado.

Exemplo de 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

Após alterar dados do LuckPerms, execute /lp sync (ou seu reload usual) e verifique os limites novamente em /bc.

Configuração

Arquivo de config: plugins/BetterClaim/config.json (gerado automaticamente na primeira execução)

Limites de reivindicação

Opção	Padrão	Descrição
`defaultClaimLimit`	`5`	Limite inicial de reivindicação por jogador
`maxClaimLimit`	`50`	Limite máximo total de reivindicações (a menos que override de admin)
`enablePlaytimeClaimGain`	`true`	Ativar chunks bônus por tempo de jogo
`claimGainMinutes`	`600`	Minutos de tempo de jogo por chunk bônus
`enableAdjacentClaims`	`false`	Exigir que novas reivindicações toquem uma existente (primeira reivindicação é livre)
`creativeBypassProtection`	`true`	Jogadores em modo Creative ignoram proteção de reivindicação
`worldNameBlacklistForClaiming`	`[]`	Nomes de mundos onde jogadores não podem reivindicar (correspondência exata)
`scaleClaimLimitByPartyMembers`	`false`	(não usado) Flag legada de config
`showPartyTotalClaims`	`false`	Mostrar total do grupo em vez da contagem pessoal na GUI

Grupo

Opção	Padrão	Descrição
`maxPartyMembers`	`10`	Máximo de membros por grupo
`maxPartyAllies`	`-1`	Máximo de aliados (-1 = ilimitado)
`enableAllySystem`	`true`	Ativar aliados (jogador/grupo)
`enablePartyInactivityDisband`	`false`	Dissolver grupos quando o dono exceder o limite de inatividade
`partyInactivityDisbandDays`	`30`	Dias de inatividade do dono antes da dissolução automática
`partyInactivityCheckIntervalMinutes`	`60`	Com que frequência o servidor executa a verificação de inatividade (mínimo 5)

Títulos de zona e sons

Opção	Padrão	Descrição
`wildernessName`	`Wilderness`	Nome exibido para áreas não reivindicadas
`titleTopText`	(vazio)	Texto opcional exibido acima dos títulos de zona
`personalClaimSubtitle`	`Personal Claim`	Subtítulo para reivindicações pessoais
`enableZoneTitles`	`true`	Mostrar título de zona ao entrar
`showWildernessZoneTitle`	`true`	Mostrar título ao entrar na wilderness
`enableClaimEntrySound`	`true`	Tocar som ao entrar em reivindicação
`claimEntrySoundOncePerZone`	`true`	Apenas uma vez por visita à zona
`claimEntrySoundId`	`SFX_Discovery_Z1_Short`	ID do som

Mapa e visuais

Opção	Padrão	Descrição
`enableCustomMap`	`true`	Mapa de terreno na GUI /bc
`mapOverlayAlpha`	`0.5`	Opacidade da sobreposição de reivindicações no mapa do mundo
`guiMapResolutionScale`	`0.75`	Resolução do mapa na GUI (0.1–1.0)
`guiMapCacheTtlSeconds`	`120`	TTL do cache de imagem do mapa em segundos
`enableParticleBorders`	`true`	Bordas com partículas nas arestas dos chunks
`useBcHubUi`	`true`	`/bc` abre o hub (mapa / party / criar) em vez de só o mapa de claims

Homes

Opção	Padrão	Descrição
`maxHomes`	`5`	Máximo de homes por jogador
`homeCooldownSeconds`	`5`	Cooldown de teleporte

Proteção global

Opção	Padrão	Descrição
`protectBuckets`	`true`	Bloquear colocação de fluido e reabastecimento de container por estranhos em reivindicações protegidas
`protectBenches`	`true`	Proteger bancadas de crafting
`isolateCraftBenchMaterials`	`true`	Crafts na bancada usam só inventário do jogador e baús próximos permitidos
`protectTamedEntities`	`true`	Bloquear dano de estranhos a papéis de NPC domesticados dentro de reivindicações (flag de grupo se aplica)
`tamedEntityRoleIdentifiers`	`Tamed_`	Prefixos de nome de papel de NPC tratados como companheiros domesticados
`blocksThatIgnoreInteractRestrictions`	`gravestone, tombstone, corpse, loot_chest`	Blocos sempre interagíveis

Proteção padrão de grupo (novos grupos)

Opção	Padrão	Descrição
`defaultPartyBlockPlaceEnabled`	`false`	Permitir que não-membros coloquem blocos
`defaultPartyBlockBreakEnabled`	`false`	Permitir que não-membros quebrem blocos
`defaultPartyBlockInteractEnabled`	`false`	Permitir que não-membros interajam com blocos
`defaultPartyPVPEnabled`	`false`	Permitir PVP em reivindicações de grupo
`defaultPartyFriendlyFireEnabled`	`false`	Permitir friendly fire entre membros
`defaultPartyInteractChest`	`false`	Permitir que não-membros abram baús
`defaultPartyInteractDoor`	`false`	Permitir que não-membros usem portas
`defaultPartyInteractBench`	`false`	Permitir que não-membros usem bancadas
`defaultPartyInteractChair`	`false`	Permitir que não-membros usem cadeiras
`defaultPartyInteractPortal`	`false`	Permitir que não-membros usem portais
`defaultPartyTamedDamageEnabled`	`false`	Permitir que não-membros causem dano a entidades domesticadas

Alternâncias do dono do grupo

Opção	Padrão	Descrição
`allowPartyPlaceBlockSetting`	`true`	Dono pode alternar colocação de blocos para não-membros
`allowPartyBreakBlockSetting`	`true`	Dono pode alternar quebra de blocos para não-membros
`allowPartyInteractBlockSetting`	`true`	Dono pode alternar interação com blocos para não-membros
`allowPartyPVPSetting`	`true`	Dono pode alternar PVP
`allowPartyFriendlyFireSetting`	`true`	Dono pode alternar friendly fire
`allowPartyInteractChestSetting`	`true`	Dono pode alternar acesso a baús
`allowPartyInteractDoorSetting`	`true`	Dono pode alternar acesso a portas
`allowPartyInteractBenchSetting`	`true`	Dono pode alternar acesso a bancadas
`allowPartyInteractChairSetting`	`true`	Dono pode alternar acesso a cadeiras
`allowPartyInteractPortalSetting`	`true`	Dono pode alternar acesso a portais
`allowPartyTamedDamageSetting`	`true`	Dono pode alternar dano a entidades domesticadas

Exemplo 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
}

Veja a config padrão completa dentro de plugins/BetterClaim/config.json após a primeira inicialização.

Observações

Reivindicar/desfazer na GUI requer betterclaim.claim / betterclaim.unclaim. Membros de grupo sempre reivindicam chunks pessoais: não há permissão separada de reivindicação de grupo.
Modo admin de chunk requer selecionar um alvo primeiro com /bc admin players.
Override de admin requer betterclaim.admin.override e ignora limites e proteção.
Regiões com reivindicação negada são armazenadas no SQLite e bloqueiam reivindicações de jogadores no retângulo marcado.
Zonas negadas não bloqueiam entrada de jogadores; apenas impedem novos claims na área.
Defina useBcHubUi como false se preferir que /bc abra o mapa de claims diretamente (comportamento legado).
Zonas negadas salvas aparecem só no mapa de claims, não no mapa normal (M) após Salvar.
Mundos listados em worldNameBlacklistForClaiming rejeitam novas reivindicações com uma mensagem no jogo.
Com LuckPerms instalado, verifique o log do servidor por LuckPerms detected na inicialização quando limites dinâmicos devem usar herança de grupo.
Dissolver um grupo mantém as reivindicações. Elas continuam pertencendo aos jogadores individuais (incluindo dissolução automática por inatividade do dono).
Dissolução por inatividade do grupo está desativada por padrão; ative enablePartyInactivityDisband e defina partyInactivityDisbandDays para ativá-la.
Localização do banco de dados: universe/BetterClaim/BetterClaim.db (dentro do save do mundo)