Dungeon

A extensão Dungeon fornece um framework completo para criar e gerenciar masmorras instanciadas, com detecção de salas baseada em polígonos, menus globais/de grupo, baús de saque e sincronização de grupo.

Recursos

• Mundos instanciados — Mundos dedicados criados a cada partida de masmorra, com geração baseada em modelo.
  • Salas e gatilhos — Salas baseadas em polígonos com gatilhos onEnter/onLeave, prioridade e critérios.
  • Sistema de menus — Navegador global de masmorras + saguão de grupo com personalização completa do layout da interface.
  • Baús de saque — Baús aleatórios com âncoras de NPC, gatilhos manuais e blocos virtuais do lado do cliente.
  • Sistema de grupo — Saguão integrado com estados pronto/não pronto. Adaptadores opcionais para MMOCore, Parties.
  • Editor de salas — Editor de salas visual no jogo com bordas de partículas, manipulação de nós e barra de ferramentas.

Permissões

Permission	Descrição
typewriter.dungeon.admin	Administrar masmorras e o editor de salas.

Dependências

Extension	Obrigatório	Uso
GUI Extension	Obrigatório	Todos os menus usam o sistema de layout da GUI (layoutPool, mainLayoutId). Sem ela, nenhum menu abrirá.
QuestExtension	Obrigatório	Dependência de tempo de execução para a integração de missões (Ref<QuestEntry>).
PartyExtension	Opcional	Plugin de grupo externo (Parties, MMOCore). O Dungeon tem um saguão integrado que funciona de forma autônoma.
PlaceholderAPI	Opcional	Para a resolução de placeholders @Placeholder nas mensagens.

Arquitetura

Entradas

• Definições — Dungeon Instance: regras, custos e configuração de grupo. Category: agrupa as masmorras nos menus. Room: contorno poligonal com gatilhos de entrada/saída. Room Config: conjunto de salas + ponto de spawn. Loot Chest: contêineres de recompensa aleatórios.
  • Ações — Global Menu: navegar por todas as masmorras. Party Menu: coordenação do saguão. Enter: lógica de entrada do jogador. Leave: lógica de saída do jogador. Close: encerrar a instância. Loot Chest Trigger: ativação manual de um baú.
  • Fatos — InDungeon Fact: verificar se o jogador está dentro de uma masmorra. InDungeonInstance Fact: verificar uma masmorra específica.

Guia de início rápido

Passo 1 — Definir uma sala

Use /dungeon room my_room edit para entrar no editor de salas visual. Coloque nós para formar um limite poligonal. Salve com corante verde-limão.

dungeon_room:
  id: "boss_room"
  name: "Boss Arena"
  nodes:
    - {x: 10, y: 64, z: 10}
    - {x: 20, y: 64, z: 10}
    - {x: 20, y: 64, z: 20}
    - {x: 10, y: 64, z: 20}
  priority: 1
  onEnter:
    - "boss_spawn_trigger"

Passo 2 — Agrupar salas em uma configuração

dungeon_room_config:
  id: "dungeon_layout"
  name: "Default Layout"
  rooms:
    - "boss_room"
    - "entrance_room"
  spawnPoint:
    x: 15
    y: 65
    z: 15
    world: "dungeon_template"

Passo 3 — Definir a instância da masmorra

dungeon_instance:
  id: "ancient_temple"
  name: "Ancient Temple"
  templateWorld: "dungeon_template"
  roomConfigurations:
    - "dungeon_layout"
  minPartySize: 1
  maxPartySize: 4
  cooldownSeconds: 300

Passo 4 — Criar uma categoria e um menu

dungeon_category:
  id: "main_dungeons"
  name: "Main Dungeons"
  instances:
    - dungeonInstance: "ancient_temple"
      unlockedItem: STONE_BRICKS
      unlockedName: "<gold>Ancient Temple</gold>"
      unlockedLore:
        - "<gray>Players: {players}/{max}"

dungeon_global_menu:
  id: "dungeon_hub"
  category: "main_dungeons"
  inventoryTitle: "<bold><gold>⚔ Dungeons</gold></bold>"
  layoutPool:
    - id: "main"
      type: simple
      items: []

Passo 5 — Acionar o menu

A partir de qualquer ação, comando, diálogo de NPC ou gatilho de entrada:

action:
  type: dungeon_global_menu
  id: "open_dungeons"
  globalMenu: "dungeon_hub"

Ou pelo comando: /dungeon global-menu main_dungeons

Comandos

Comando	Descrição
/dungeon global-menu <category>	Abrir o navegador global de masmorras
/dungeon party-menu <instance>	Abrir o saguão de grupo de uma instância específica
/dungeon room <room> edit	Entrar no editor de salas visual
/dungeon room <room> addvertex	Adicionar um nó no bloco visado
/dungeon room <room> removevertexat <index>	Remover um nó por índice
/dungeon room <room> save	Salvar a sala e sair do editor
/dungeon room <room> cancel	Cancelar a edição

Placeholders

Todos os placeholders usam o prefixo %typewriter_dungeon_%.

Placeholder	Descrição
%typewriter_dungeon_players%	Número de jogadores na masmorra atual.
%typewriter_dungeon_attempts%	Total de tentativas nesta masmorra (artefato por jogador).
%typewriter_dungeon_completions%	Número de conclusões (artefato por jogador).
%typewriter_dungeon_best_time%	Melhor tempo de conclusão formatado (artefato por jogador).