Configuração do Nightbreak e gestão de conteúdo

Esta página é o guia de configuração partilhado para os plugins geridos pelo Nightbreak.

Aplica-se diretamente a:

• EliteMobs
• BetterStructures
• FreeMinecraftModels
• EternalTD
• ResurrectionChest
• WorldCannon

Estes plugins agora partilham o mesmo ciclo de vida geral:

1. Instale o plugin e quaisquer dependências obrigatórias.
2. Inicie o servidor uma vez para que os ficheiros e menus sejam gerados.
3. Execute o comando de configuração inicial do plugin, se existir.
4. Vincule o servidor à sua conta Nightbreak com /nightbreaklogin e depois aprove-o na ligação que o comando imprime.
5. Use o menu de configuração do plugin para navegar, instalar, ativar, desativar e atualizar conteúdo.
6. Use os comandos de download/atualização em massa do plugin quando quiser um arranque inicial mais rápido.

O que o MagmaCore realmente partilha

O MagmaCore é a camada partilhada por trás do fluxo gerido pelo Nightbreak. Fornece:

• o comando partilhado /nightbreaklogin, que vincula o servidor a partir de um navegador ou guarda um token que cole (permissão nightbreak.login, por padrão OP)
• o comando partilhado /nightbreaklogout para desligar o servidor da sua conta Nightbreak (permissão nightbreak.login, por padrão OP)
• o comando partilhado /logify para enviar o log atual do servidor para mclo.gs (permissão logify.*, por padrão OP). Envia logs/latest.log, ou o ficheiro .log mais recente se esse não existir, mascara primeiro os dígitos dos endereços IPv4 e das portas e responde com uma ligação clicável
• o comando partilhado /nightbreak plugins para navegar no catálogo de plugins do Nightbreak (permissão nightbreak.plugins, por padrão OP)
• o armazenamento partilhado do token em plugins/MagmaCore/nightbreak.yml
• primitivas partilhadas do menu de configuração usadas pelos menus de configuração dos plugins
• verificações partilhadas de acesso, versão e download do Nightbreak
• lógica partilhada de download em massa que descarrega ficheiros para a pasta imports do plugin proprietário
• a caixa de entrada de changelogs partilhada que avisa os administradores no jogo quando um plugin ou um pacote de conteúdo instalado tem notas de lançamento por ler (ver Notificações de changelog do Nightbreak)
• atualizações de plugins sem reinício através de applypluginupdate e da definição nightbreak.applyPluginUpdatesWithoutRestart (ver abaixo)
• o conjunto padrão de subcomandos que cada plugin gerido pelo Nightbreak regista sob o seu próprio comando raiz (ver abaixo)

/nightbreaklogin, /nightbreaklogout, /logify e /nightbreak são registados uma vez por servidor pelo primeiro plugin gerido pelo Nightbreak que carregue o MagmaCore, pelo que ficam disponíveis independentemente de qual plugin "detém" os comandos em tempo de execução.

Subcomandos padrão partilhados

Os subcomandos abaixo não são escritos por cada plugin. O MagmaCore regista as mesmas implementações sob o comando raiz que o plugin declarar (/em, /bs, /fmm, /etd, …), razão pela qual se comportam de forma idêntica em todo o lado.

Subcomando	O que faz	Permissão
setup	Abre o menu de configuração do plugin. Apenas para jogadores.	permissão de setup do plugin
initialize	Abre o menu de configuração inicial para jogadores quando o plugin regista esse fluxo. Não exige modos predefinidos; FreeMinecraftModels também o regista. Consulte a página de comandos de cada plugin.	permissão de initialize do plugin
recommendedplugins	Mostra os plugins complementares recomendados (menu no jogo, lista em chat a partir da consola).	permissão de setup do plugin
downloadpluginupdate	Descarrega apenas um jar de atualização do plugin. Sem conteúdo.	permissão de admin do plugin
applypluginupdate	Aplica uma atualização do plugin já descarregada sem reiniciar o servidor. Consulte Aplicar atualizações sem reiniciar.	permissão de admin do plugin
downloadall	Descarrega a atualização do plugin e depois todo o conteúdo disponível.	permissão de admin do plugin
downloadallcontent	Descarrega todo o conteúdo disponível, sem atualização do plugin. Só é registado por plugins que incluem pacotes de conteúdo.	permissão de setup do plugin
updatecontent (alias updateallcontent)	Descarrega atualizações apenas para o conteúdo já desatualizado. Só é registado por plugins que incluem pacotes de conteúdo.	permissão de setup do plugin
forcereinstallcontent <package|all>	Volta a descarregar conteúdo através do caminho normal de importação autenticada e recarga, mesmo quando a versão instalada já está atualizada. all abrange todos os pacotes que estejam descarregados, instalados ou desatualizados; indique diretamente o slug de um pacote se os seus ficheiros estiverem completamente em falta. Só é registado por plugins que incluem pacotes de conteúdo.	permissão de admin do plugin

O nó de permissão exato por trás de cada coluna é escolhido pelo plugin, por isso consulte a página do próprio plugin para saber os nomes dos nós. initialize é um fluxo de orientação inicial — não substitui o menu de configuração nem os comandos de gestão de conteúdo.

Como o downloadall começa pela atualização do plugin, ele para antes do passo de conteúdo quando a conta não tem token ou quando a autenticação do token falha. Corrija primeiro o token e depois volte a executá-lo.

O MagmaCore também possui um sistema de inicialização separado no arranque do plugin, mas não é a mesma coisa que os comandos initialize orientados ao jogador documentados aqui.

Atualizações automáticas

Cada plugin gerido pelo Nightbreak escreve duas chaves partilhadas no seu próprio config.yml:

nightbreak:
  autoDownloadPluginUpdates: false
  applyPluginUpdatesWithoutRestart: never

Quando autoDownloadPluginUpdates é true, esse plugin descarrega automaticamente, alguns minutos após o arranque:

• um jar de atualização do plugin disponível, e
• ficheiros de atualização para quaisquer pacotes de conteúdo desatualizados que ele gira.

As atualizações de conteúdo descarregadas automaticamente são usadas depois de o servidor reiniciar. Uma atualização do plugin descarregada também aguarda um reinício, a menos que applyPluginUpdatesWithoutRestart a aplique antes (consulte Aplicar atualizações sem reiniciar). Ambas as definições começam desativadas, pelo que, de origem, continua a usar o botão de atualização no jogo. O botão Atualizações automáticas na barra de ferramentas do menu de configuração ativa e desativa autoDownloadPluginUpdates. Esse botão e a entrada Atualização do plugin indicam quando uma atualização do plugin descarregada é aplicada, com o valor atual de applyPluginUpdatesWithoutRestart. Os do ResourcePackManager indicam que é preciso reiniciar.

O ResourcePackManager só escreve autoDownloadPluginUpdates, porque as suas atualizações do plugin exigem sempre um reinício.

As descargas de jars de plugins no jogo, automáticas ou iniciadas a partir de um comando ou menu, exigem um token válido e uma subscrição ativa de apoiante no Patreon associada à conta Nightbreak. Sem eles, a descarga é recusada e o plugin explica o motivo, com uma ligação para a página pública de transferência. Antes de um jar descarregado receber o nome definitivo, na pasta update do servidor ou, numa nova instalação, na pasta plugins, o MagmaCore valida-o face ao nome e à versão esperados do plugin. A soma SHA-256 também é verificada quando o Nightbreak a fornece. Se uma verificação falhar, a descarga temporária é eliminada em vez de ser instalada.

Independentemente da definição de download automático, cada plugin volta a verificar discretamente se existe uma versão mais recente cerca de uma vez por hora, para que o menu de configuração possa mostrar um estado de atualização correto. Essa verificação nunca descarrega nada por si só. Alguns plugins também registam na consola a versão pública mais recente quando esse resultado muda e avisam os operadores que entram de que a sua versão está desatualizada, com uma ligação de transferência.

Aplicar atualizações sem reiniciar

Uma atualização do plugin descarregada aguarda na pasta update do servidor. Execute /<root> applypluginupdate, por exemplo /em applypluginupdate, para a instalar no servidor em execução. O comando usa a permissão de admin do plugin e também funciona a partir da consola.

A substituição desativa o plugin e todos os plugins ativos do MagmaGuy que dependem dele, diretamente ou por soft-depend, substitui o jar e depois volta a carregá-los e ativá-los. O chat lista os plugins recarregados em conjunto. Se o novo jar não ativar, o jar anterior é carregado novamente e a atualização fica na pasta update para o próximo reinício. As atualizações que aí aguardam para os outros plugins recarregados também ficam para o próximo reinício; só o plugin indicado muda de versão.

O comando é recusado, com uma mensagem, quando:

• não há nenhuma atualização descarregada à espera, ou o jar à espera é inválido ou não é mais recente do que a versão em execução
• um plugin de outro autor depende dele, diretamente ou por soft-depend. Nesse caso, reinicie o servidor
• já está em curso outra substituição de plugin
• o plugin exige sempre um reinício. O ResourcePackManager recusa porque a sua extensão do Geyser só carrega quando o Geyser arranca

Use este comando em vez de um recarregador de plugins de terceiros. Até à substituição ou a um reinício, o servidor continua a executar o jar antigo.

nightbreak.applyPluginUpdatesWithoutRestart decide o que acontece logo após a descarga de uma atualização do plugin, quer a descarga tenha vindo de downloadpluginupdate, de downloadall, do menu de configuração ou de uma descarga automática:

Valor	Comportamento
never	Predefinição. A atualização aguarda o próximo reinício. Os jogadores online com a permissão de admin ou a permissão global do plugin recebem um título e um aviso no chat de que é necessário reiniciar. O aviso indica /<root> applypluginupdate apenas quando o plugin regista esse comando e permite atualizações sem reinício.
when-empty	Aplica a atualização de imediato se não houver jogadores online. Caso contrário, o plugin verifica a cada 30 segundos e aplica-a quando o servidor estiver vazio.
immediately	Aplica a atualização assim que a descarga termina.

Qualquer outro valor comporta-se como never. Quando when-empty ou immediately encontram uma das recusas acima, a atualização aguarda o próximo reinício. Uma substituição recarrega o plugin, pelo que os bosses, arenas e instâncias de masmorras em curso terminam.

Fluxo recomendado para proprietários de servidores

1. Instale primeiro o plugin

Coloque o ficheiro jar do plugin e quaisquer dependências obrigatórias em plugins/, depois inicie o servidor uma vez.

2. Execute o fluxo de configuração inicial

Se o plugin expõe um comando initialize, use-o primeiro. Os menus atuais são concebidos para:

• marcar a configuração inicial como concluída
• direcioná-lo para a vinculação de conta Nightbreak ou iniciar a vinculação por si
• direcioná-lo para o menu de configuração atual
• esclarecer quando as importações manuais ainda são válidas

Este processo não exige modos predefinidos; o FreeMinecraftModels também o disponibiliza. Consulte a página de comandos de cada plugin para confirmar a disponibilidade.

3. Vincule a sua conta Nightbreak

Execute:

/nightbreaklogin

Abra a ligação que o comando imprime, inicie sessão e aprove o servidor. O servidor guarda sozinho o token da sua conta. Continua a poder colar um token da página de conta Nightbreak com /nightbreaklogin <token>. Consulte Ligação de conta Nightbreak.

O token é partilhado através do MagmaCore, pelo que um token vinculado pode ser reutilizado por todos os plugins MagmaGuy compatíveis nesse servidor.

4. Use o menu de configuração para a gestão diária de conteúdo

Os menus de configuração são a fonte de verdade atual para:

• estados dos pacotes
• estados de acesso
• conteúdo instalado vs descarregado
• conteúdo parcialmente instalado que precisa de reparação
• conteúdo desatualizado
• filtros de conteúdo por categoria

Se tiver um token vinculado, os menus de configuração são o local recomendado para instalar e atualizar conteúdo.

5. Use a instalação/atualização em massa quando quiser velocidade

Use o comando downloadall quando quiser configurar um servidor rapidamente e o comando updatecontent quando quiser atualizar tudo o que estiver desatualizado.

O descarregador em massa partilhado só tenta pacotes geridos pelo Nightbreak que tenham um slug Nightbreak. Entre esses:

• downloadall e downloadallcontent escolhem os pacotes que ainda não foram descarregados ou estão desatualizados. É a verificação autenticada de descarga do Nightbreak que decide o acesso, pelo que um pacote a que a sua conta não tem acesso aparece como falhado no fim.
• updatecontent começa por atualizar as versões dos pacotes e depois escolhe apenas os pacotes desatualizados, ignorando os que a verificação de acesso já marcou como bloqueados.

Os comandos interativos em massa pedem ao plugin proprietário que recarregue depois de pelo menos um download bem-sucedido. Os downloads automáticos de conteúdo no arranque deliberadamente não recarregam o plugin; só produzem efeito depois de o servidor reiniciar.

Conceitos partilhados

Descarregado vs instalado

Um pacote pode existir localmente sem estar ativado. O significado exato varia ligeiramente consoante o plugin, mas o estado do menu de configuração importa mais do que a existência de um zip em imports.

Os downloads em massa também vão para a mesma pasta imports do plugin usada pelas importações manuais, antes de o passo de importação/recarga específico do plugin terminar.

Conteúdo com reconhecimento de acesso

Os menus de configuração agora podem distinguir entre conteúdo que:

• está disponível para o seu token
• precisa de ser comprado ou desbloqueado
• está instalado
• está apenas parcialmente instalado
• está descarregado mas desativado
• está desatualizado

Um plugin pode listar um pacote antes de o Nightbreak o lançar. Quando o plugin já carregou a lista de pacotes publicados do Nightbreak e esse pacote não consta dela, clicar no pacote indica que ainda não foi lançado no Nightbreak. As verificações de acesso e os comandos em massa, incluindo forcereinstallcontent, ignoram-no. Se o Nightbreak ainda responder a um pedido desse pacote com «not found», a consola regista uma única vez que o pacote não foi lançado, em vez de registar um erro da API.

As atualizações de conteúdo arquivam os ficheiros que deixam de incluir

Quando um pacote atualizado deixa de incluir um ficheiro que a versão anterior instalou, a importação move esse ficheiro para plugins/MagmaCore/outdated files/ em vez de o deixar carregado. Consulte Ficheiros que uma atualização de pacote deixa de incluir.

As importações manuais continuam válidas

Os plugins geridos pelo Nightbreak ainda suportam fluxos de importação manual. A importação manual é agora o caminho alternativo, não o caminho predefinido. Consulte Importações manuais vs gestão no jogo.

Catálogo de plugins e recomendações

/nightbreak plugins lista os plugins do MagmaGuy, como menu no jogo e como lista no chat a partir da consola. No menu, clicar num plugin instalado abre o seu menu de configuração. Clicar num plugin em falta descarrega o seu jar diretamente para a pasta plugins, com o nome do ficheiro do catálogo, o que exige um token vinculado e acesso de apoiante; a mensagem no chat pede-lhe então que reinicie o servidor para que o novo plugin seja carregado. Se a pasta plugins já tiver um jar desse plugin que o servidor não carregou, a descarga vai antes para a pasta update, com o nome desse jar. Sem token ou sem acesso, a mensagem apresenta antes uma ligação para a página pública de transferência.

/<root> recommendedplugins lista os plugins complementares de um plugin, cada um com a etiqueta Required (obrigatório), Recommended (recomendado) ou Encouraged (aconselhado). Os plugins do MagmaGuy comportam-se como em /nightbreak plugins. Os plugins externos, como WorldEdit, WorldGuard, LibsDisguises e PacketEvents, apresentam uma ligação para as respetivas páginas oficiais. O botão Plugins recomendados do menu de configuração abre a mesma lista e fica verde quando todos os plugins listados estão instalados.

Plugins que não usam este fluxo

Nem todos os plugins nesta wiki usam conteúdo descarregável gerido pelo Nightbreak.

• BetterFood não usa gestão de pacotes Nightbreak
• ResourcePackManager gere pacotes de recursos, não pacotes DLC Nightbreak

Ambos esses plugins continuam a registar a estrutura de configuração partilhada e os comandos partilhados de atualização de plugin e de changelog; o que lhes falta são pacotes de conteúdo Nightbreak.

O ResurrectionChest e o WorldCannon não são exceções — ambos declaram pacotes de conteúdo, ambos registam os subcomandos de conteúdo partilhados e ambos usam o importador partilhado, pelo que também aceitam zips de pacotes colocados manualmente. Consulte Importações manuais vs gestão no jogo.