Spec: Módulo Nativo de Chunk Loader (Canalhandia)

1. Visão Geral

Adiciona ao plugin Canalhandia um módulo nativo, performático e equilibrado de Chunk Loading para o Paper 1.21.x. Permite que jogadores mantenham áreas/chunks específicas carregadas para farms, redstone e sistemas automatizados usando a API nativa de tickets do Paper (addPluginChunkTicket), com permissões granulares e limites por cargo configuráveis via LuckPerms.

2. Requisitos e Mecânicas

2.1. Bloco e Item Customizado: "Âncora de Chunk" (Chunk Anchor)

Item Base: RESPAWN_ANCHOR ou LODESTONE com nome formatado (§b§lÂncora de Chunk), lore explicativa e PersistentDataContainer identificando o item customizado.
Receita de Crafting:
- Configurada em config.yml (ex: 4 Obsidianas Choronas, 4 Diamantes, 1 Estrela do Nether ou Olho do Fim).
- Desbloqueia automaticamente no livro de receitas ao obter os ingredientes.

2.2. Colocação e Restrições

Ao colocar o bloco (BlockPlaceEvent):
- Verifica se o jogador possui permissão canalhandia.chunkloader.
- Verifica o limite de loaders do jogador no LuckPerms:
  - Lê permissões numéricas: canalhandia.chunkloader.limite.<N> (ex: limite.1, limite.2, limite.5, limite.10).
  - Pega o maior <N> encontrado nas permissões do jogador.
  - Se não houver permissão numérica explícita, usa chunkloader.limite-padrao do config.yml (padrão: 1).
  - Administradores com canalhandia.admin não têm limite.
- Verifica se já existe um loader ativo na mesma chunk (máximo 1 por chunk).
- Se aprovado:
  - Ativa o ticket na chunk: world.addPluginChunkTicket(chunkX, chunkZ, plugin).
  - Salva em chunks.yml.
  - Cria partícula/efeito sonoro de ativação.
  - Registra marcador no BlueMap (opcional/configurável).
  - Envia mensagem de confirmação informando quantas âncoras o jogador está usando (ex: 1/3 ativas).

2.3. Remoção e Proteção

Proteção: Apenas o dono da âncora ou administradores (canalhandia.admin) podem quebrar o bloco (BlockBreakEvent).
Explosões / Pistões: Protegido contra destruição acidental por TNT/Creeper (EntityExplodeEvent, BlockExplodeEvent) e empurrão por pistão (BlockPistonExtendEvent).
Ao quebrar:
- Remove o ticket de chunk do Paper: world.removePluginChunkTicket(chunkX, chunkZ, plugin).
- Remove de chunks.yml e do BlueMap.
- Devolve o item "Âncora de Chunk" ao jogador.

2.4. Persistência e Ciclo de Vida

Arquivo plugins/Canalhandia/chunks.yml:
- Armazena ID, UUID do dono, nome, mundo, coordenadas (x, y, z), chunk (cx, cz) e data de criação.
No onEnable() do plugin: Carrega chunks.yml e registra addPluginChunkTicket em todas as chunks salvas.
No onDisable() do plugin: Remove os tickets do plugin de forma limpa.

2.5. Comandos (`/chunkloader` ou `/ancora`)

/chunkloader ou /ancora:
- /chunkloader info — Mostra o status da chunk atual (se está carregada por um loader e por quem) e seus limites de uso.
- /chunkloader listar — Lista todas as âncoras ativas do jogador com coordenadas e link para deletar/desativar.
- /chunkloader remover <id> — Desativa remotamente uma âncora do próprio jogador.
- /chunkloader receita — Mostra a receita de crafting.
- /chunkloader admin listar [jogador] — (Admin) Lista todos os chunk loaders do servidor.
- /chunkloader admin remover <id> — (Admin) Força a remoção de qualquer loader.
- /chunkloader reload — (Admin) Recarrega configurações e sincroniza tickets.

3. Integração com LuckPerms

Nós de permissão:

canalhandia.chunkloader — Habilita o jogador a craftar, colocar e gerenciar âncoras.
canalhandia.chunkloader.limite.<N> — Define o limite máximo de âncoras ativas para o cargo (ex: canalhandia.chunkloader.limite.3 para VIP).
canalhandia.chunkloader.admin — Acesso total aos comandos administrativos de chunk loading.

4. Critérios de Aceite

Módulo pode ser ativado/desativado via config.yml e /canalhandia modulo chunkloader.
Bloco colocado registra ticket via world.addPluginChunkTicket que sobrevive a reboots via chunks.yml.
Limites de permissão do LuckPerms são respeitados estritamente.
Blocos não podem ser roubados ou quebrados por terceiros.
Suíte de testes unitários (ChunkLoaderTest.java) com 100% de aprovação.

4.4 KiB Raw Blame History