GITHUB • DOCUMENTATION • DISCORD

Visão geral - o que o BileTools faz

O BileTools monitora seu diretório de plugins e conduz mudanças no ciclo de vida em tempo de execução, para que uma recompilação ocorra no servidor em execução em vez de uma reinicialização.

• Auto hot-reload. Recompile sobre um jar de plugin existente e o BileTools detecta a mudança de conteúdo automaticamente.

• Hot-drop. Coloque um novo jar no diretório de plugins e ele será colocado na fila para carregamento em tempo de execução sem uma reinicialização completa.

• Auto-unload. Exclua um jar rastreado e seu plugin será descarregado.

• Comandos de ciclo de vida. Carregue, descarregue, recarregue, instale e desinstale manualmente a partir da árvore de comandos /bile.

• Ciente de dependências. Plugins dependentes são descarregados e recarregados ao redor de uma substituição em vez de recarregar um jar cegamente.

• Biblioteca de plugins local. Cada jar que o BileTools vê é arquivado por versão, e a mesma pasta é o que /bile install lê. Backup e rollback são a mesma funcionalidade.

• Implantação remota. Envie alterações de jar selecionadas para outros servidores configurados por meio de uma transferência autenticada, limitada em tamanho e verificada por SHA-256.

Detecção, em resumo: uma mudança de tamanho ou timestamp apenas ativa o observador. Um SHA-256 do jar decide se algo realmente recarrega, então um jar que você tocou, mas não mudou, é ignorado.

BileTools é uma ferramenta de desenvolvimento. Ela manipula deliberadamente o estado do ciclo de vida do plugin em tempo de execução. Isso é exatamente o que torna o ciclo de desenvolvimento rápido, e exatamente por isso pertence a servidores de desenvolvimento e teste. O hot reload não é um substituto para uma reinicialização limpa em um servidor ao vivo.

Compatibilidade - tempos de execução e Java

Um jar cobre todos os seis tempos de execução, Minecraft 1.20.1 até a atual 26.x.

• Paper carrega através do PluginManager público do servidor

• Purpur mesmos caminhos de carga e descarga da família Paper

• Leaf fork da família Paper, tratado como Paper

• Folia agendamento regionalizado, o BileTools declara suporte a folia

• Canvas fork do Folia, mesmas regras regionalizadas

• Spigot carrega através do plugin.yml; jars que enviam apenas paper-plugin.yml são recusados

Java: Java 17 para Minecraft 1.20.1+, Java 25 para 26.x+. Combine com o que seu servidor já requer.

Folia e Canvas: o hot reload em servidores regionalizados é inerentemente mais frágil. Um plugin de terceiros que não declara suporte a folia pode falhar ao ser carregado.

Comandos e permissões

O comando raiz é /biletools. Aliases: /bile, /bi, /b.

/bile load <plugin>                  Carrega um jar de plugin do diretório de plugins
/bile unload <plugin>                  Descarrega um plugin instalado
/bile reload <plugin>                  Recarrega um plugin instalado
/bile uninstall <plugin>                Exclui um jar de plugin do diretório de plugins
/bile install <plugin> [version=..]    Instala um plugin da biblioteca BileTools
/bile library [plugin=..]              Lista plugins da biblioteca, ou versões de um plugin

Uma permissão cobre toda a árvore:

Os comandos manuais sempre ignoram os filtros do observador. A conclusão automática sugere plugins instalados, plugins da biblioteca e versões armazenadas. Executar /bile sozinho abre um menu de ajuda paginado com hover e clique.

Argumentos opcionais devem ser nomeados. Passá-los de forma posicional falha com "argumento inesperado":

/bile install MyPlugin                   funciona  (padrão para version=latest)
/bile install MyPlugin version=1.4.2      funciona
/bile install MyPlugin version=latest      funciona
/bile install MyPlugin 1.4.2                FALHA
/bile library                               funciona  (lista tudo)
/bile library plugin=MyPlugin               funciona
/bile library MyPlugin                       FALHA

Configuração - configuração.yml padrão completa

remote-deploy:
  slave:
    slave-enabled: false
    slave-port: 9876
    slave-payload: pickapassword
  master:
    master-enabled: false
    master-deploy-to:
    - yourserver.com:9876:password
    master-deploy-signatures:
    - MyPlugin
    - AnotherPlugin
  socket-timeout-ms: 15000
  max-transfer-bytes: 268435456
archive-plugins: true
watcher:
  idle-poll-ticks: 20
  active-poll-ticks: 5
  fingerprint-debounce-ticks: 8
  ignore:
  - LuckPerms
  - Vault
  - ProtocolLib
  - packetevents
  - WorldGuard
  - CoreProtect
  - spark
  - only: []
  coalesce-window-ticks: 10
observability:
  log-timings: true
lifecycle:
  health-check: true

• watcher.ignore Nomes de plugins que o hot-drop, reload e unload automáticos irão ignorar. Os padrões são coisas que geralmente são perigosas ou inúteis para auto-recarregar em uma caixa de desenvolvimento.

• watcher.only Quando esta lista não está vazia, apenas esses plugins são gerenciados automaticamente. Útil quando você está desenvolvendo ativamente um ou dois projetos em um servidor ocupado.

• watcher.active-poll-ticks / idle-poll-ticks Com que frequência o observador escaneia enquanto as mudanças estão chegando, em comparação com uma vez que o diretório se estabilizou.

• watcher.fingerprint-debounce-ticks Quanto tempo a impressão digital de um jar deve permanecer estável antes que o trabalho do ciclo de vida comece. Isso é o que impede que jars meio escritos sejam carregados.

• watcher.coalesce-window-ticks Agrupa gravações de jars próximas em um flush de recarga ordenado por dependência, para que uma construção de múltiplos módulos não acione cinco recargas separadas.

• archive-plugins Arquiva cada jar de plugin na pasta da biblioteca antes de ser substituído.

• lifecycle.health-check Após um carregamento ou recarregamento, verifique se o plugin está realmente registrado e habilitado. Uma operação falhada marca o plugin como sujo e pausa os recarregamentos automáticos para ele.

• observability.log-timings Registra os tempos por fase (descarregar, dependentes, carregar, saúde) para cada operação.

Biblioteca de plugins e rollback

plugins/BileTools/library/<PluginName>/<version>.jar

Com archive-plugins ativado, cada jar de plugin que o BileTools vê é copiado aqui antes de ser substituído. Isso significa que a biblioteca também serve como um histórico de rollback, /bile library lista o que você tem, e /bile install <plugin> version=<version> coloca qualquer um deles de volta no servidor em execução.

Implantação remota

Opcional. Permite que um servidor mestre envie alterações de jar selecionadas para um ou mais servidores escravos.

• Em cada servidor receptor: defina remote-deploy.slave.slave-enabled: true, escolha uma porta e defina slave-payload para uma senha compartilhada.

• No servidor de envio: defina remote-deploy.master.master-enabled: true, liste cada destino em master-deploy-to na forma abaixo, e liste quais plugins encaminhar em master-deploy-signatures.

master-deploy-to:
- host:port:password

As transferências aterrissam em um arquivo temporário .part e só são promovidas após a senha, nome do arquivo, tamanho da transferência e SHA-256 serem verificados. Os nomes dos arquivos são sanitizados e qualquer caminho que escape da pasta de plugins é rejeitado. Os padrões são um limite de 256 MB e um tempo limite de soquete de 15 segundos.

Idiomas - todos os 17 códigos de localidade

O inglês é selecionado por padrão. Para mudar, defina locale em plugins/BileTools/language.yml:

locale: en_US

de_DE    Alemão (Alemanha)
es_ES    Espanhol (Espanha)
fi_FI    Finlandês (Finlândia)
fr_FR    Francês (França)
he_IL    Hebraico (Israel)
it_IT    Italiano (Itália)
ja-JP    Japonês (Japão)
ko_KR    Coreano (Coreia do Sul)
lt_LT    Lituano (Lituânia)
nl_NL    Holandês (Países Baixos)
pl_PL    Polonês (Polônia)
pt_PT    Português (Portugal)
ru_RU    Russo (Rússia)
tr_TR    Turco (Turquia)
vi_VI    Vietnamita (Vietnã)
zh_CN    Chinês (Simplificado)
zh_TW    Chinês (Tradicional)

Você também pode substituir linhas individuais sem tocar nos pacotes. Qualquer coisa que você adicionar sob uma seção messages: na language.yml vence; tudo que você deixar de fora volta para o idioma selecionado, depois para o inglês. O arquivo é carregado automaticamente ao ser salvo.

Como um reload realmente é executado

Cada operação hot-drop, reload, install, uninstall, remote deploy: passa por uma fila serializada com chaves de deduplicação, em uma thread dedicada a operações de plugin. As mutações do ciclo de vida sempre são executadas na thread global ou principal.

detect -> stabilize -> fingerprint -> queue -> unload -> load -> dependents -> health check

Plugins que implementam o contrato ReloadAware do VolmLib recebem um callback HOT_RELOAD ou HOT_UNLOAD antes que suas tarefas sejam canceladas e ouvintes sejam desmontados, para que possam drenar trabalhos em andamento enquanto seu agendador ainda está vivo.

Descarregar remove o plugin do gráfico de comandos ao vivo, serviços, canais de mensagens e tabelas de consulta antes de fechar seu classloader, que é o motivo pelo qual os comandos e a conclusão automática voltam corretos em vez de meio conectados.

As esperas do ciclo de vida têm um tempo limite explícito. Uma operação presa aparece como uma falha e marca o plugin como sujo em vez de bloquear a fila. Ative observability.log-timings para ver os tempos por fase para cada operação.

Limites conhecidos do hot reload

Nem todo plugin pode ser recarregado limpo, e o BileTools não finge o contrário. Coisas que geralmente não sobrevivem a um recarregamento de classe:

• Estado estático campos mantidos durante um recarregamento de classe

• Threads em segundo plano trabalho iniciado fora do agendador de plugins

• Recursos nativos qualquer coisa vinculada fora da JVM

• Conexões externas soquetes e pools com seu próprio tempo de vida

• Internos específicos do plugin caches e registros que outros plugins possuem

Mantenha plugins críticos ou obscuros na lista de ignorados, ative os logs de tempo enquanto você itera, e quando o estado não puder ser reconstruído com segurança, reinicie o servidor.