Referência de configuração

O config.yml é a superfície de controle que pertence ao operador. O ReferralTrack nunca substitui um arquivo personalizado em silêncio. Quando a versão do esquema muda, o plugin preserva o original como config.yml.bak-v<old>, grava a nova referência completa em config.new-v<new>.yml, atualiza apenas o marcador de versão no arquivo ativo e informa os caminhos ausentes na inicialização. Os padrões incluídos do Bukkit mantêm as novas opções funcionando até que o operador as copie ou personalize.

O acesso administrativo usa nós de permissão granulares do Bukkit e funciona com o LuckPerms sem OP nem dependência obrigatória de uma API. Veja Comandos e permissões; referraltrack.admin continua sendo o pai com acesso total.

Sistemas principais #

• database: conexão SQLite ou MySQL/MariaDB e tempos limitados do pool. Mantenha as credenciais privadas.
• referral: política de resgate, origens conhecidas, códigos pessoais, validação, limites de recompensa, comandos, marcos e atribuição de retenção.
• campaigns: chave do mecanismo, fuso horário e datas de campanha independentes, filtros, códigos, multiplicadores, recompensas e marcos. Veja Campanhas.
• fraud: chave do mecanismo de risco, limite de revisão da equipe e sinais de conta/tempo de jogo. Veja Revisão de fraude.
• discord: rotas de webhook opcionais, relatórios, intervalo de atualização das estatísticas ao vivo, campos de embed com marca e URLs HTTPS seguras de mídia/botões. Um bot completo do Discord não faz parte desta versão.
• integrations.developer-api: registro no ServicesManager do Bukkit da API assíncrona somente leitura. events.pre-claim e events.claim-result controlam de forma independente os dois eventos públicos de resgate; desativar a API desativa ambos. Veja API para desenvolvedores.
• text-formatting: ativa de forma independente a formatação MiniMessage e os códigos antigos com e comercial. Gradientes, arco-íris, cor RGB e tags de estilo reconhecidos do MiniMessage podem coexistir com & e &#RRGGBB; placeholders comuns entre colchetes angulares permanecem literais.
• player-interface: seleciona AUTO, INVENTORY ou DIALOG. AUTO usa a API nativa de diálogos Java do Paper quando presente e, caso contrário, abre o inventário independente. As larguras do corpo e dos botões do diálogo, as colunas, o comportamento de pausa/escape e a política de alternativa são limitados e configuráveis. O texto do diálogo e os quatro rótulos de botão são localizados em dashboard.dialog-*. /referral inventory sempre abre o menu independente.
• player-feedback.claim: controles de título, subtítulo, action bar, som e partículas do resgate. Cada canal tem a própria chave; os tempos do título, o volume/tom do som e a contagem/deslocamento/velocidade das partículas são limitados. A animação de partículas oferece suporte às formas limitadas BURST, RING e HELIX com quadros, intervalo, raio e altura configuráveis. Valores inválidos de som, partícula ou animação falham de forma suave com um diagnóstico emitido uma única vez.
• onboarding: orientação na primeira inicialização, validação automática somente leitura e máximo de achados informados. /referraltrack validate verifica os limites do banco de dados e do pool, a identidade da indicação e as restrições de recompensa, os limites de validação e de fraude, os agendamentos de relatórios, os nós de rede passivos e o Discord ativado, porém não configurado. Informa caminhos e expectativas seguras, nunca valores secretos configurados.
• velogrowth: chave do ranking de qualidade, amostra mínima, tamanho do ranking, janela de avaliação e seis pesos relativos. O volume bruto só determina a elegibilidade. Validação, segurança contra rejeições, segurança de risco e retenção madura D1/D7/D30 contribuem para a pontuação de 0–100; coortes imaturas são omitidas e cada entrada é exibida por /referraltrack growth.
• campaign-guard: chave da verificação prévia de ativação, janela de "termina em breve", aviso de multiplicador de recompensa, número máximo de comandos, gravidade da economia ausente e limites de dinheiro configuráveis por resgate e para o total estimado. A estimativa do total usa exposure.expected-claims. Achados críticos bloqueiam a ativação da campanha e o ligar do mecanismo; os avisos continuam visíveis sem alterar a campanha em silêncio.
• reward-rescue: permissão da equipe, tamanho da lista, limites de idade para pendentes/travadas e máximo de tentativas manuais. /referraltrack rescue é somente leitura, a menos que retry ou cancel inclua confirm e um motivo imprimível. Linhas em processamento nunca são repetidas automaticamente, porque o Vault ou um comando de console pode já ter sido executado antes de uma falha. Veja Reward Rescue.
• settings: responsabilidade pelo rastreamento/entrega em redes, identidades ignoradas e limpeza de retenção.
• menu: todos os tamanhos de inventário fornecidos, slots, materiais, títulos, lore, capacidades de página, navegação, exibição do horário do histórico de recompensas e aparência da barra de progresso.

Toda frase visível para jogadores/equipe está em lang/<language>.yml; cinco idiomas completos são fornecidos. Chaves de tradução personalizada ausentes recorrem ao inglês incluído sem sobrescrever o arquivo de idioma personalizado.

O texto de retorno do resgate é localizado por feedback.claim-title, feedback.claim-subtitle e feedback.claim-action-bar. Os placeholders aceitos são {player}, {source} e {status}. A mecânica visual e sonora permanece em player-feedback.claim para que os operadores possam mudar a apresentação sem editar as traduções.

Regras de segurança dos menus #

Os tamanhos de inventário devem ser múltiplos de 9 entre 9 e 54. Os slots começam em zero e devem caber no inventário configurado. Os campos de material aceitam materiais do Bukkit e as referências HEADDB:<id>, HDB:<id> e hdb-<id> no estilo DeluxeMenus quando o HeadDatabase está instalado e carregado. Plugins ausentes, IDs desconhecidos e materiais inválidos recorrem a um material interno seguro com um aviso no console. Valores numéricos fora do intervalo são limitados e diagnosticados. As listas de slots descartam entradas inválidas e duplicadas; se nenhuma restar, o layout interno seguro é usado.

menu.player-dashboard.progress controla o slot de progresso, o material, o comprimento (1–40), os glifos e as cores. reward-history-button controla o botão de entrada dele.

menu.reward-history controla o tamanho do inventário, os slots de conteúdo ordenados, o máximo de linhas (1–45), os materiais de na fila/processando/entregue/cancelada, os controles de vazio/voltar/fechar, o padrão de data do Java e o fuso horário. Use SYSTEM para o fuso horário do host ou um ID IANA como Europe/Istanbul.

menu.admin-dashboard e menu.admin-review controlam tamanhos, slots de página ordenados, materiais de estado/risco e cada slot de navegação/controle. A capacidade efetiva de página é a contagem de slots de conteúdo válidos, então a paginação permanece consistente com layouts personalizados.

Evite atribuir duas ações ao mesmo slot: o item gravado por último ficará visível e isso pode deixar outra ação inacessível. Depois de qualquer edição de layout, execute /referraltrack reload, inspecione os diagnósticos do console e abra manualmente os menus de jogador e de equipe antes de usar em produção.

Presets e segredos #

Veja Presets e temas antes de aplicar /referraltrack install <preset> confirm. Os presets nunca modificam credenciais do banco de dados, tokens nem URLs de webhook. /referraltrack doctor, as exportações e as interfaces não expõem esses valores. Guarde os backups fora de raízes web que possam ser baixadas publicamente e restrinja o acesso ao sistema de arquivos à conta de serviço do Minecraft.

Temas #

Veja Presets e temas antes de aplicar /referraltrack theme <theme> confirm. A pré-visualização do tema é somente leitura; a instalação confirmada cria um backup exato e altera apenas os caminhos de apresentação documentados de menus/progresso/retorno do resgate. Nunca altera dados de recompensas, campanhas, permissões, banco de dados nem segredos.