GITHUB  •  DOCUMENTAZIONE  •  DISCORD

Panoramica - cosa fa BileTools

BileTools monitora la tua directory dei plugin e gestisce i cambiamenti del ciclo di vita in tempo reale, quindi una ricompilazione si trova nel server in esecuzione invece di un riavvio.

• Auto hot-reload. Ricompila su un jar di plugin esistente e BileTools rileva automaticamente il cambiamento di contenuto.

• Hot-drop. Inserisci un nuovo jar nella directory dei plugin e viene messo in coda per il caricamento in tempo reale senza un riavvio completo.

• Auto-unload. Elimina un jar tracciato e il suo plugin viene scaricato.

• Comandi del ciclo di vita. Carica, scarica, ricarica, installa e disinstalla manualmente dall'albero dei comandi \/bile.

• Consapevole delle dipendenze. I plugin dipendenti vengono scaricati e ricaricati attorno a una sostituzione invece di ricaricare un jar alla cieca.

• Libreria di plugin locale. Ogni jar che BileTools vede è archiviato per versione, e la stessa cartella è quella da cui \/bile install legge. Backup e rollback sono la stessa funzione.

• Distribuzione remota. Invia modifiche di jar selezionate ad altri server configurati tramite un trasferimento autenticato, limitato in dimensione, verificato con SHA-256.

Rilevamento, in breve: un cambiamento di dimensione o timestamp risveglia solo il watcher. Un SHA-256 del jar decide se qualcosa viene effettivamente ricaricato, quindi un jar che hai toccato ma non hai cambiato viene ignorato.

BileTools è uno strumento di sviluppo. Manipola deliberatamente lo stato del ciclo di vita del plugin in tempo reale. Questo è esattamente ciò che rende veloce il ciclo di sviluppo, e precisamente per questo appartiene ai server di sviluppo e test. Il hot reload non è un sostituto per un riavvio pulito su un server in produzione.

Compatibilità - runtime e Java

Un jar copre tutti e sei i runtime, Minecraft 1.20.1 fino all'attuale 26.x.

• Paper carica attraverso il PluginManager pubblico del server.

• Purpur stesso percorso di caricamento e scaricamento della famiglia Paper.

• Leaf fork della famiglia Paper, trattato come Paper.

• Folia pianificazione regionalizzata, BileTools dichiara supporto folia.

• Canvas fork di Folia, stesse regole regionalizzate.

• Spigot carica attraverso plugin.yml; i jar che vengono forniti solo con paper-plugin.yml vengono rifiutati.

Java: Java 17 per Minecraft 1.20.1+, Java 25 per 26.x+. Abbina qualsiasi cosa il tuo server richieda già.

Folia e Canvas: il hot reload su server regionalizzati è intrinsecamente più fragile. Un plugin di terze parti che non dichiara supporto folia potrebbe comunque fallire quando viene caricato a caldo.

Comandi e permessi

Il comando principale è \/biletools. Alias: \/bile, \/bi, \/b.

\/bile load <plugin>                    Carica un jar di plugin dalla directory dei plugin
\/bile unload <plugin>                  Scarica un plugin installato
\/bile reload <plugin>                  Ricarica un plugin installato
\/bile uninstall <plugin>               Elimina un jar di plugin dalla directory dei plugin
\/bile install <plugin> [version=..]    Installa un plugin dalla libreria di BileTools
\/bile library [plugin=..]              Elenca i plugin della libreria, o le versioni per un plugin

Un permesso copre l'intero albero:

bile.use     Consente l'accesso a BileTools     predefinito: op

I comandi manuali bypassano sempre i filtri del watcher. Il completamento automatico suggerisce plugin installati, plugin della libreria e versioni memorizzate. Eseguire \/bile da solo apre un menu di aiuto paginato hover-e-clicca.

Gli argomenti opzionali devono essere nominati. Passarli per posizione fallisce con "argomento imprevisto":

\/bile install MyPlugin                   funziona  (predefinito a version=latest)
\/bile install MyPlugin version=1.4.2     funziona
\/bile install MyPlugin version=latest    funziona
\/bile install MyPlugin 1.4.2             FALLISCE
\/bile library                            funziona  (elenca tutto)
\/bile library plugin=MyPlugin            funziona
\/bile library MyPlugin                   FALLISCE

Configurazione - configurazione predefinita completa config.yml

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

Cosa fa ciascuna opzione

• watcher.ignore Nomi dei plugin che il caricamento automatico, il ricaricamento e lo scaricamento salteranno. I predefiniti sono cose che di solito sono pericolose o inutili da ricaricare automaticamente su una macchina di sviluppo.

• watcher.only Quando questo elenco non è vuoto, solo questi plugin sono gestiti automaticamente. Utile quando stai sviluppando attivamente uno o due progetti su un server affollato.

• watcher.active-poll-ticks \/ idle-poll-ticks Quanto spesso il watcher scansiona mentre arrivano cambiamenti, rispetto a quando la directory si è stabilizzata.

• watcher.fingerprint-debounce-ticks Quanto a lungo un'impronta del jar deve rimanere stabile prima che inizi il lavoro del ciclo di vita. Questo è ciò che impedisce il caricamento di jar parzialmente scritti.

• watcher.coalesce-window-ticks Raggruppa le scritture di jar vicine in un flush di ricarica ordinato per dipendenze, quindi una build multi-modulo non attiva cinque ricariche separate.

• archive-plugins Archivia ogni jar di plugin nella cartella della libreria prima che venga sostituito.

• lifecycle.health-check Dopo un caricamento o un ricaricamento, verifica che il plugin sia effettivamente registrato e abilitato. Un'operazione fallita segna il plugin come sporco e interrompe i ricaricamenti automatici per esso.

• observability.log-timings Registra i tempi per fase (scaricamento, dipendenti, caricamento, salute) per ogni operazione.

Libreria di plugin e rollback

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

Con archive-plugins attivo, ogni jar di plugin che BileTools vede viene copiato qui prima di essere sostituito. Ciò significa che la libreria funge anche da cronologia di rollback, \/bile library elenca ciò che hai, e \/bile install <plugin> version=<version> ripristina qualsiasi cosa nel server in esecuzione.

Distribuzione remota

Opzionale. Consente a un server master di inviare modifiche di jar selezionate a uno o più server slave.

• Su ciascun server ricevente: imposta remote-deploy.slave.slave-enabled: true, scegli una porta e imposta slave-payload su una password condivisa.

• Sul server di invio: imposta remote-deploy.master.master-enabled: true, elenca ogni obiettivo in master-deploy-to nella forma sottostante, e elenca quali plugin inoltrare in master-deploy-signatures.

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

I trasferimenti atterrano in un file temporaneo .part e vengono promossi solo dopo che la password, il nome del file, la dimensione del trasferimento e SHA-256 sono tutti verificati. I nomi dei file vengono sanificati e qualsiasi percorso che potrebbe uscire dalla cartella dei plugin viene rifiutato. I predefiniti sono un limite di 256 MB e un timeout di socket di 15 secondi.

Lingue - tutti i 17 codici locali

L'inglese è selezionato per impostazione predefinita. Per cambiare, imposta locale in plugins\/BileTools\/language.yml:

locale: en_US

de_DE    Tedesco (Germania)
es_ES    Spagnolo (Spagna)
fi_FI    Finlandese (Finlandia)
fr_FR    Francese (Francia)
he_IL    Ebraico (Israele)
it_IT    Italiano (Italia)
ja-JP    Giapponese (Giappone)
ko_KR    Coreano (Corea del Sud)
lt_LT    Lituano (Lituania)
nl_NL    Olandese (Paesi Bassi)
pl_PL    Polacco (Polonia)
pt_PT    Portoghese (Portogallo)
ru_RU    Russo (Russia)
tr_TR    Turco (Turchia)
vi_VI    Vietnamita (Vietnam)
zh_CN    Cinese (semplificato)
zh_TW    Cinese (tradizionale)

Puoi anche sovrascrivere singole righe senza toccare i pacchetti. Qualsiasi cosa tu aggiunga sotto una sezione messages: in language.yml prevale; tutto ciò che lasci fuori torna alla lingua selezionata, poi all'inglese. Il file viene caricato a caldo al salvataggio.

Come viene eseguito effettivamente un ricaricamento

hot-drop, ricarica, installa, disinstalla, distribuzione remota: passa attraverso una coda serializzata con chiavi deduplica, su un thread dedicato alle operazioni dei plugin. Le mutazioni del ciclo di vita stesse vengono sempre eseguite sul thread globale o principale.

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

I plugin che implementano il contratto ReloadAware di VolmLib ottengono un callback HOT_RELOAD o HOT_UNLOAD prima che i loro compiti vengano annullati e gli ascoltatori smantellati, così possono drenare il lavoro in corso mentre il loro scheduler è ancora attivo.

Lo scaricamento pulisce il plugin dalla grafica dei comandi attivi, servizi, canali di messaggistica e tabelle di ricerca prima di chiudere il suo classloader, motivo per cui i comandi e il completamento automatico tornano corretti invece di mezzi cablati.

Le attese del ciclo di vita portano un timeout esplicito. Un'operazione bloccata si presenta come un fallimento e segna il plugin come sporco piuttosto che bloccare la coda. Attiva observability.log-timings per vedere i tempi per fase per ogni operazione.

Limiti noti del hot reload

Non ogni plugin può essere ricaricato a caldo in modo pulito, e BileTools non finge il contrario. Le cose che generalmente non sopravvivono a un ricaricamento di classe:

• Stato statico campi mantenuti attraverso un ricaricamento di classe.

• Thread in background lavoro avviato al di fuori dello scheduler del plugin.

• Risorse native qualsiasi cosa legata al di fuori della JVM.

• Connessioni esterne socket e pool con il proprio ciclo di vita.

• Interni specifici del plugin cache e registri di cui altri plugin sono proprietari.

Tieni i plugin critici o oscuri nella lista di ignorati, attiva i log dei tempi mentre iteri, e quando lo stato non può essere ricostruito in modo sicuro, riavvia il server.