canalhandia/specs/chunk-loader-module/plan.md

Plan: Módulo Nativo de Chunk Loader

Arquitetura

1. ChunkLoader.java (Record puro)

   • id, ownerUuid, ownerName, world, x, y, z, chunkX, chunkZ, createdAt.
   • Métodos utilitários: chunkCoords(), blockCoords(), etc.

2. ChunkLoaders.java (Gerenciador e Persistência)

   • Gerencia lista em memória sincronizada List<ChunkLoader>.
   • Persistência em plugins/Canalhandia/chunks.yml com salvamento assíncrono.
   • Métodos: add(), remove(), byChunk(), byOwner(), loadAll(), unloadAll(), playerLimit(Player).
   • Executa world.addPluginChunkTicket e world.removePluginChunkTicket.

3. Module.java & Settings.java

   • Adiciona CHUNKLOADER("chunkloader", "Âncoras de carregamento contínuo de chunks") no enum Module.
   • Adiciona configurações em Settings.java (limite padrão, material do bloco, raio de partículas).

4. ChunkLoaderListener.java (Eventos do Mundo)

   • BlockPlaceEvent: Detecta colocação da Âncora, verifica permissões/limites LuckPerms, registra loader e ticket.
   • BlockBreakEvent: Protege quebra por não-donos, remove ticket e devolve o item customizado.
   • BlockExplodeEvent / EntityExplodeEvent: Impede destruição por explosão.
   • BlockPistonExtendEvent / BlockPistonRetractEvent: Impede movimentação por pistão.

5. CanalhandiaCommand.java & ChunkLoaderCommand.java

   • Subcomandos de /chunkloader / /ancora e tab-completion completo.

6. BlueMapBridge.java

   • Cria conjunto de marcadores para chunk loaders no mapa web.

7. Testes Unitários (ChunkLoaderTest.java)

   • Validação de regras de permissão, cálculo de limite, serialização em YAML e exclusão de duplicatas na mesma chunk.

Riscos & Mitigações

• Risco: Descarregamento incorreto no shutdown do servidor gerando tickets órfãos.
  • Mitigação: unloadAll() limpo em onDisable(), e tickets do Paper (PluginChunkTicket) são re-validados no onEnable().
• Risco: Jogador contornar limite colocando em mundos não permitidos ou múltiplas na mesma chunk.
  • Mitigação: Validação estrita de unicidade de chunk (byChunk(world, cx, cz) != null) e verificação de limite antes de aceitar o evento.