Configuração do MegaBlock Survivors

O fluxo de configuração do MegaBlock Survivors é baseado em pacotes de conteúdo gerenciados pelo Nightbreak, com suporte opcional a modelos através do FreeMinecraftModels.

Requisitos

• Java 21
• Um servidor compatível com Paper/Spigot na linha da API 1.21.4

Integrações opcionais:

• FreeMinecraftModels -- modelos personalizados de mobs e armas (dependência opcional)
• LibsDisguises -- dependência opcional para suporte visual adicional

O que o MegaBlock Survivors Cria

Ao iniciar, o MegaBlock Survivors inicializa ou utiliza estes caminhos sob plugins/MegaBlockSurvivors/:

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

Ele também carrega automaticamente um mundo de lobby criado pelo operador chamado mbs_spawn caso a pasta exista em disco. O plugin não cria nem modifica esse mundo -- ele apenas o carrega. Vários recursos do plugin silenciosamente recorrem ao comportamento padrão caso o mbs_spawn esteja ausente:

• O holograma do placar (ancorado em (4.5, 67, -14.5) em mbs_spawn) deixa de surgir e registra um aviso.
• O teleporte ao entrar (SpawnLobbyListener) envia os jogadores que entram para (0.5, 65, 0.5) em mbs_spawn com yaw 180 -- ignorado quando o jogador tem uma partida ativa.
• O encerramento pós-partida retorna o jogador para mbs_spawn, se ele existir.

Configuração

O config.yml contém:

Chave	Tipo	Padrão	Descrição
setupDone	boolean	false	Controla se a orientação de configuração inicial já foi concluída

Traduções

Todos os textos exibidos ao usuário (linhas de chat, títulos de diálogos, barras de chefe, textos de holograma, descrições de comandos) são carregados do translations.yml. Os operadores do servidor podem localizar ou re-tematizar cada linha sem mexer no jar. Os recursos suportados incluem:

• Códigos de cor simples com prefixo & e escapes hexadecimais &#RRGGBB.
• Tags de gradiente do MagmaCore como <gradient:#FF0000:#00FF00>text</gradient>.
• Tokens {placeholder} que são substituídos pelo plugin em tempo de execução.
• Chaves ausentes são renderizadas como um marcador visível [translations: key.name], facilitando identificar entradas não definidas no jogo.

O arquivo é regenerado com entradas padrão na primeira execução e ao recarregar o plugin, então strings recém-adicionadas aparecem automaticamente.

Dados Persistentes do Jogador

Arquivo	Finalidade
leaderboard.yml	Entradas de placar por categoria (6 seções: 2 modos de jogo x 3 dificuldades), limitadas a 100 entradas por categoria.
meta_progression.yml	Saldo de Ecos de Alma e níveis das trilhas de melhoria por jogador. Indexado pelo UUID do jogador.
stats-dump.log	Log apenas-adição em formato JSON-lines de cada partida concluída, gravado no encerramento da partida.

Aviso de Configuração Inicial

Quando setupDone é false, o plugin exibe um aviso de configuração inicial aos jogadores com a permissão megablocksurvivors.* ao entrarem. O aviso é configurado (via NightbreakFirstTimeSetupSpec) apenas com um comando de setup, então ele aponta os jogadores para /mbs setup (o navegador de conteúdo) e não para uma etapa de inicialização/download. O /mbs initialize não é registrado nesta build; o /mbs downloadall é registrado, mas baixa apenas o jar do plugin, já que os pacotes de conteúdo estão desativados (veja a página Comandos) -- use /mbs setup em vez disso.

Fluxo Recomendado de Configuração Inicial

1. Instale o MegaBlock Survivors e inicie o servidor uma vez. As traduções e arquivos de configuração são gravados na primeira execução.
2. Vincule sua conta Nightbreak com /nightbreaklogin <token>.
3. Execute /mbs setup para abrir o navegador de conteúdo Nightbreak e instalar / habilitar os pacotes que desejar.
4. Execute /mbs reload se você colocar conteúdo em imports/ manualmente, ou após ativar/desativar pacotes em content_packages/.

O /nightbreaklogin <token> é fornecido pelo fluxo de conta compartilhado Nightbreak/MagmaCore, e não pelo plugin.yml do MegaBlock Survivors.

Pacotes de Conteúdo

Os pacotes de conteúdo são configurados via arquivos YAML na pasta content_packages/. Cada pacote pode definir:

Campo	Tipo	Descrição
isEnabled	boolean	Se o pacote está ativo
name	string	Nome de exibição do pacote
description	lista de strings	Linhas de descrição
downloadLink	string	URL de download manual
version	integer	Número da versão do pacote
nightbreakSlug	string	Slug do conteúdo Nightbreak para downloads automáticos
schematicFiles	lista de strings	Arquivos de schematic incluídos no pacote
worldFolders	lista de strings	Pastas de mundo incluídas
worldContainerFolders	lista de strings	Pastas de contêineres de mundo incluídas
modelFolders	lista de strings	Pastas de modelos para o FreeMinecraftModels
markerFileName	string	Arquivo marcador para detectar se o pacote está instalado
category	enum	FREE, PREMIUM ou RESOURCES
toggleable	boolean	Se o pacote pode ser ativado/desativado

Configuração de NPCs

Os NPCs (fornecedores de missões no lobby, lojistas) são configurados via arquivos YAML em npcs/. Os NPCs são respawnados ao carregar o chunk, sobrevivendo a ciclos de descarregamento/recarregamento dos chunks do lobby. Clicar com o botão direito em um NPC executa seu interactionCommand configurado.

Dois NPCs vêm com o plugin e surgem automaticamente em mbs_spawn quando esse mundo é carregado:

NPC	Localização padrão	Disfarce	Comando de interação
Iniciador de Partida	mbs_spawn, 0, 67, -15	VILLAGER	mbs start
Meta-Progressão	mbs_spawn, -9, 66, -13	PIGLIN	mbs meta

Qualquer um deles pode ser desativado, movido ou reconfigurado editando o YAML correspondente em npcs/. Os disfarces requerem o LibsDisguises para serem renderizados; sem ele, o NPC ainda surge como uma entidade base na localização configurada.

Campos do YAML de NPC

Campo	Tipo	Descrição
isEnabled	boolean	Se o NPC surge
name	string	Nome interno
location	string	Formato world,x,y,z,pitch,yaw
disguise	string	Tipo de entidade do LibsDisguises (opcional)
interactionCommand	string	Comando a executar quando um jogador clica com o botão direito no NPC
nameTag	string	Holograma flutuante acima do NPC (códigos de cor permitidos)

Notificações de Atualização de Versão

Quando o plugin detecta uma mudança de versão (comparando com version.txt), ele notifica o console e todos os OPs online.