Instalação do MegaBlock Survivors

A instalação do MegaBlock Survivors usa pacotes de conteúdo geridos pelo Nightbreak. O FreeMinecraftModels é necessário para as criaturas e armas das partidas, apesar de estar declarado como dependência opcional no descritor do plugin.

Requisitos

• Java 21.
• Um servidor compatível com a sua compilação do MegaBlock Survivors. O descritor declara a API 1.21.4, mas o código atual é compilado contra o Spigot 26.2; o descritor, por si só, não é uma lista de versões suportadas.
• FreeMinecraftModels e os pacotes de modelos e conteúdo necessários para jogar.
• WorldEdit, para as schematics de torres, muralhas e árvores que a geração de mundos cola. O plugin chama diretamente a API do WorldEdit, mas o descritor não o declara como dependência.
• Suporte nativo funcional de minecraft:dialog para os ecrãs de seleção e recompensas.

Integrações opcionais:

• LibsDisguises, para suporte visual adicional.

O que o MegaBlock Survivors cria

Ao arrancar, o MegaBlock Survivors inicializa ou usa estes caminhos em plugins/MegaBlockSurvivors/:

plugins/MegaBlockSurvivors/config.yml
plugins/MegaBlockSurvivors/translations.yml
plugins/MegaBlockSurvivors/content_packages/
plugins/MegaBlockSurvivors/content_markers/
plugins/MegaBlockSurvivors/imports/
plugins/MegaBlockSurvivors/schematics/
plugins/MegaBlockSurvivors/worlds/
plugins/MegaBlockSurvivors/npcs/
plugins/MegaBlockSurvivors/leaderboard.yml
plugins/MegaBlockSurvivors/meta_progression.yml
plugins/MegaBlockSurvivors/stats-dump.log
plugins/MegaBlockSurvivors/version.txt
plugins/MegaBlockSurvivors/nightbreak-changelogs.yml

nightbreak-changelogs.yml guarda o estado de leitura partilhado das notas de lançamento usado por /mbschangelog (consulte Comandos).

Também carrega um mundo de entrada criado pelo administrador, chamado mbs_spawn, se a pasta existir em disco e o mundo ainda não estiver carregado. Instale esse mundo antes de iniciar o plugin. Quando não está disponível:

• O holograma da classificação, situado em (4.5, 67, -14.5) de mbs_spawn, não aparece e gera uma mensagem informativa.
• O teletransporte ao entrar não faz nada. Quando o mundo de entrada está carregado, tenta enviar o jogador para (0.5, 65, 0.5), com orientação horizontal 180, se não tiver um registo de partida ou se o nome do mundo atual começar por megablocksurvivors_. Ter uma partida ativa não basta para evitar esta condição.
• O encerramento da partida usa a localização anterior do jogador em vez do mundo de entrada.

Configuração

config.yml contém:

Chave	Tipo	Predefinição	Descrição
setupDone	booleano	false	Regista se a orientação de instalação inicial foi concluída.
preGenerateWorldCache	booleano	false	Gera previamente os mundos de jogo durante o arranque. Deixe false para manter o arranque leve; os mundos continuam a ser gerados quando uma partida precisar deles.
nightbreak.autoDownloadPluginUpdates	booleano	false	Acrescentada pela biblioteca MagmaCore incorporada depois do arranque. Com true, uma atualização disponível do plugin é transferida automaticamente alguns minutos após o arranque. As transferências automáticas do plugin exigem um token válido da conta Nightbreak e uma subscrição de apoiante ativa.
nightbreak.applyPluginUpdatesWithoutRestart	texto	never	Acrescentada pelo MagmaCore. never aguarda o próximo reinício, when-empty aplica uma atualização transferida na próxima vez que não houver jogadores online e immediately aplica-a de imediato. Aplicar uma atualização recarrega o MegaBlock Survivors e termina as partidas ativas. /mbs applypluginupdate aplica manualmente uma atualização em espera.

Consulte Atualizações automáticas para saber como as definições de atualização partilhadas funcionam nos plugins Nightbreak.

Traduções

Muitas mensagens, caixas de diálogo, barras de boss e textos de hologramas usam translations.yml. Algumas mensagens dos pacotes, descrições de comandos partilhados e textos da classificação continuam definidos diretamente em inglês. As traduções suportam:

• Códigos de cor com prefixo & e sequências hexadecimais &#RRGGBB.
• Etiquetas de gradiente do MagmaCore, como <gradient:#FF0000:#00FF00>text</gradient>.
• Marcadores {placeholder}, substituídos pelo plugin durante a execução.
• Chaves ausentes apresentadas como [translations: key.name], para facilitar a sua identificação no jogo.

O ficheiro é regenerado com entradas predefinidas na primeira execução e ao recarregar o plugin. Assim, os novos textos aparecem automaticamente.

Dados persistentes dos jogadores

Ficheiro	Finalidade
leaderboard.yml	Entradas de classificação por categoria: seis secções, correspondentes a dois modos de jogo e três dificuldades, com um máximo de 100 entradas por categoria.
meta_progression.yml	Saldo de Ecos de Alma e níveis das melhorias permanentes de cada jogador, identificados pelo UUID.
stats-dump.log	Registo de resumos em linhas JSON, acrescentadas ao encerrar cada partida. /mbs dump limpa o ficheiro partilhado antes de procurar a partida atual ou mais recente de quem executou o comando. Mesmo sem resumo disponível, o registo anterior é apagado.

Pastas de conteúdo

Pasta	Finalidade
imports/	Recebe os arquivos de conteúdo transferidos ou colocados manualmente. O importador do MagmaCore processa-os no arranque e em /mbs reload.
schematics/	Schematics de estruturas usados na geração de mundos. Os nomes seguem Level<1-3>_<Name>.schem: Tower, Wall / Wall1 / Wall2 e Tree1..Tree5. Os mundos 1 e 3 incluem quatro variantes de árvore; o mundo 2 inclui cinco. A arena do boss final não usa schematics.
worlds/	Pastas de mundos instaladas pelos pacotes.
content_packages/	Definições YAML de cada pacote, descritas abaixo.
content_markers/	Ficheiros marcadores usados para detetar se um pacote já está instalado.

Aviso de instalação inicial

Quando setupDone é false, o plugin apresenta um aviso aos jogadores com megablocksurvivors.* ao entrarem. O aviso, configurado através de NightbreakFirstTimeSetupSpec, define apenas um comando de instalação e encaminha para /mbs setup, o navegador de conteúdo. /mbs initialize não está registado nesta versão. /mbs downloadall existe, mas transfere apenas o JAR do plugin, porque os pacotes de conteúdo estão desativados nesse fluxo, conforme a página de comandos. Use /mbs setup.

Abrir o navegador de conteúdo não define setupDone. O menu que altera esse valor só é acessível através do controlador initialize, que não está registado. Depois de concluir e verificar a instalação, defina setupDone: true em config.yml e recarregue o plugin para parar o lembrete.

Instalação inicial recomendada

Guarde os objetos normais antes de iniciar uma partida e use um inventário dedicado ao minijogo. A implementação atual substitui a armadura do peito e limpa todo o inventário no encerramento da partida, sem restaurar os objetos anteriores. Também repõe atributos, vida, alimentação e saturação e remove os efeitos de poção.

1. Instale o MegaBlock Survivors e inicie o servidor. Os ficheiros de configuração e tradução são escritos na primeira execução.
2. Associe a sua conta Nightbreak com /nightbreaklogin <token>.
3. Execute /mbs setup para abrir o navegador de conteúdo Nightbreak e instalar os pacotes necessários. Confirme que o FreeMinecraftModels carrega os modelos; o estado de instalação do pacote apenas verifica os caminhos registados.
4. Execute /mbs reload após importações manuais ou alterações à configuração dos pacotes. Isto reinicia o MegaBlock Survivors e termina as partidas ativas. Se forem importados modelos durante este recarregamento e o FreeMinecraftModels estiver ativo, o conteúdo do FMM também é recarregado. Para ficheiros editados ou copiados diretamente nas pastas do FMM, use o comando de recarregamento do próprio FMM.

/nightbreaklogin <token> pertence ao fluxo de conta partilhado do Nightbreak/MagmaCore, não ao plugin.yml do MegaBlock Survivors.

Pacotes de conteúdo

Os pacotes são configurados através de ficheiros YAML em content_packages/. Cada pacote pode definir:

Campo	Tipo	Descrição
isEnabled	booleano	Metadado guardado; a deteção atual de instalação usa a presença dos recursos e não aplica este campo como interruptor da jogabilidade.
name	texto	Nome apresentado do pacote.
description	lista de textos	Linhas da descrição.
downloadLink	texto	Endereço para transferência manual.
version	inteiro	Número da versão do pacote.
nightbreakSlug	texto	Identificador do conteúdo Nightbreak para transferências automáticas.
schematicFiles	lista de textos	Schematics incluídos no pacote.
worldFolders	lista de textos	Pastas de mundos incluídas.
worldContainerFolders	lista de textos	Pastas que contêm mundos incluídos.
modelFolders	lista de textos	Pastas de modelos para o FreeMinecraftModels.
markerFileName	texto	Ficheiro marcador para detetar a instalação.
category	enumeração	FREE, PREMIUM ou RESOURCES.
toggleable	booleano	Predefinido como false. O processo atual de desinstalação apresenta sempre instruções de remoção manual; este campo não fornece uma opção funcional para desligar o pacote.

Um pacote é considerado instalado se registar pelo menos um recurso e todos estiverem presentes. A verificação examina caminhos, não o conteúdo dos ficheiros nem se os modelos estão prontos; uma pasta no diretório de modelos desativados do FreeMinecraftModels também conta. Recursos em falta originam um estado de instalação parcial. Clicar num pacote instalado e atualizado apresenta instruções de remoção manual. Alterar apenas isEnabled não desativa os recursos de jogo importados.

Configuração de NPCs

Os NPCs são configurados em ficheiros YAML em npcs/. Os NPCs registados reaparecem quando o respetivo chunk é recarregado. Se o mundo não estava disponível durante a inicialização, carregue-o e recarregue o MegaBlock Survivors para registar os NPCs. Clicar com o botão direito executa o interactionCommand como o jogador e com as suas permissões.

O plugin inclui dois NPCs que aparecem automaticamente quando mbs_spawn é carregado:

NPC	Localização predefinida	Disfarce	Comando de interação
Iniciar partida	mbs_spawn, 0, 67, -15	VILLAGER	mbs start
Progressão permanente	mbs_spawn, -9, 66, -13	PIGLIN	mbs meta

Pode desativar, mover ou alterar a ação de qualquer um editando o respetivo YAML em npcs/ e recarregando o plugin. Com LibsDisguises, o NPC usa um aldeão como entidade base e o disfarce configurado. Sem ele, o plugin tenta usar o tipo de entidade Bukkit configurado e recorre a um aldeão se esse tipo não for uma entidade viva que possa ser criada.

Campos YAML dos NPCs

Campo	Tipo	Descrição
isEnabled	booleano	Define se o NPC aparece.
name	texto	Nome interno.
location	texto	Formato world,x,y,z ou world,x,y,z,yaw,pitch.
disguise	texto	Tipo de entidade LibsDisguises, opcional.
interactionCommand	texto	Comando executado quando um jogador clica com o botão direito no NPC.
nameTag	texto	Nome personalizado visível da entidade NPC; aceita códigos de cor.

Notificações de atualização de versão

Quando a versão atual é mais recente do que a guardada em version.txt, o plugin notifica a consola e os operadores ligados. A primeira execução sem versão guardada, uma versão inalterada ou o regresso a uma versão anterior não desencadeiam este aviso de atualização.