feat(chunkloader): add native chunk loader module with LuckPerms limits and BlueMap support

specs/chunk-loader-module/spec.md

@@ -0,0 +1,72 @@
+# 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
+1. Módulo pode ser ativado/desativado via `config.yml` e `/canalhandia modulo chunkloader`.
+2. Bloco colocado registra ticket via `world.addPluginChunkTicket` que sobrevive a reboots via `chunks.yml`.
+3. Limites de permissão do LuckPerms são respeitados estritamente.
+4. Blocos não podem ser roubados ou quebrados por terceiros.
+5. Suíte de testes unitários (`ChunkLoaderTest.java`) com 100% de aprovação.