1 — KubeJS : C'est quoi, comment ça marche
Avant de toucher quoi que ce soit, comprendre l'outil.
Qu'est-ce que KubeJS ?
KubeJS est un mod qui permet de modifier le jeu sans créer un mod complet. Il expose une API JavaScript pour : ajouter/retirer des recettes, créer des items custom, modifier les drops des mobs, intercepter des events (kill, craft, login), gérer les tags, etc. C'est l'outil principal qui définit l'identité du modpack Arcadia V2.
Où vit le KubeJS ?
Tout est dans le dossier kubejs/ à la racine du serveur (ou de l'instance client pour les client_scripts/). C'est ce dossier qui est versionné et partagé entre l'équipe staff.
- Faites TOUJOURS un backup du dossier kubejs/ avant modification massive.
- Travaillez sur un serveur de test, jamais en prod.
- Les erreurs de syntaxe peuvent empêcher le serveur de démarrer.
- Consultez logs/kubejs/server.log et startup.log à chaque reload.
2 — Les 3 types de scripts (CRITIQUE)
Comprendre ces 3 types, c'est 80% du job.
KubeJS sépare les scripts en 3 catégories. Chacune a son moment d'exécution, ses possibilités et son comportement au reload. Mettre un script dans le mauvais dossier ne marchera tout simplement pas.
S'exécutent au démarrage serveur ET à chaque /reload. C'est là que tout se passe au quotidien : recettes, drops, stats de mobs, events, tags.
S'exécutent UNE SEULE FOIS au lancement. Pas rechargeable. Sert à enregistrer des items, blocs, sons, armures. Toute modif → restart serveur obligatoire.
S'exécutent côté client uniquement. Tooltips, JEI, visuels. Reload via F3+T. Doit être présent sur chaque client.
Tableau récap
| Type | Quand ça run | Rechargeable | Usage typique |
|---|---|---|---|
| Startup | Lancement du jeu | NON (restart) | Items, blocs, sons, tiers d'armure, creative tabs |
| Server | Démarrage + /reload | OUI | Recettes, tags, events, loot tables, stats mobs |
| Client | Join client + F3+T | OUI (client) | Tooltips, JEI, visuels |
- Tu enregistres un nouvel item, bloc, son, armure ? → startup_scripts
- Tu ajoutes/retires une recette, modifies un drop, crée un event ? → server_scripts
- Tu personnalises un tooltip, masques un truc de JEI ? → client_scripts
3 — Structure du KubeJS Arcadia V2
La carte du territoire — savoir où chaque chose vit.
Convention de nommage Arcadia
- Fichiers en snake_case.js — le nom décrit la fonction, pas le mod.
- Namespace custom : arcadia: partout (ex: arcadia:vote_key).
- Chaque recette custom a un .id('arcadia:nom') explicite.
- Header // Priority: N en haut de fichier (plus haut = chargé en premier).
- Pas d'accents dans les noms de fichiers — ASCII only.
4 — Lire un script : la méthode
Comment décortiquer un fichier sans paniquer.
L'anatomie d'un server_script
// Priority: 100 ← Ordre de chargement (optionnel) ServerEvents.recipes(event => { // ← Hook : event "recipes" // 1) On retire d'abord event.remove({ output: 'minecraft:diamond_sword' }); // 2) On rajoute ensuite (avec un id explicite) event.shaped('minecraft:diamond_sword', [ ' D ', ' D ', ' S ' ], { D: 'minecraft:diamond', S: 'minecraft:stick' }).id('arcadia:custom_diamond_sword'); });
Les events les plus courants chez Arcadia
| Event | À quoi ça sert |
|---|---|
| ServerEvents.recipes | Ajouter, retirer, modifier des recettes. |
| ServerEvents.tags | Manipuler les tags d'items, blocs, entités. |
| LootJS.modifiers | Modifier les loot tables (mobs, structures, fishing). |
| EntityJSEvents | Modifier les stats des mobs (HP, dégâts, armure). |
| PlayerEvents.inventoryChanged | Détecter changements d'inventaire (scan ban). |
| BlockEvents | Réagir aux placements/destructions de blocs. |
| StartupEvents.registry | Enregistrer items, blocs, sons (startup only). |
| ItemEvents.tooltip | Modifier les tooltips (client_scripts only). |
Trouver le bon fichier pour une modif
grep -r "arcadia:vote_key" kubejs/
// ou sous Windows avec ripgrep :
rg "arcadia:vote_key" kubejs/
5 — Désactiver / Supprimer un script proprement
Trois méthodes, de la plus douce à la plus radicale.
Méthode 1 — Commenter une section (recommandée pour test)
Encadre la section que tu veux désactiver entre /* */ :
ServerEvents.recipes(event => {
event.remove({ output: 'minecraft:diamond_sword' });
/* DÉSACTIVÉ TEMPORAIREMENT — 11/05/2026 — test PvP
event.shaped('minecraft:netherite_sword', [...], {...})
.id('arcadia:custom_netherite_sword');
*/
});
Méthode 2 — Renommer le fichier avec .disabled
KubeJS ne charge que les fichiers .js. Renommer un fichier en .js.disabled le désactive sans le supprimer :
mob_damage_nerfs.js ← chargé mob_damage_nerfs.js.disabled ← ignoré (mais conservé)
Méthode 3 — Supprimer le fichier
Définitif. À ne faire qu'après backup et confirmation que personne d'autre n'en dépend.
- Si tu supprimes item_registry.js du startup, tous les items custom disparaissent du monde. Inventaires affectés.
- Si tu supprimes un script de recettes custom, les items deviennent injoignables sauf via /give.
- Si tu supprimes recipe_remover.js, les 152 items bannis redeviennent craftables.
- Si tu supprimes inventory_scanner.js, les bans existants restent dans l'inventaire des joueurs.
Procédure recommandée pour retirer un script
- server_scripts → /reload
- startup_scripts → restart serveur complet
- client_scripts → F3+T (chaque client)
6 — Recharger le KubeJS : les commandes
Reloader sans casser, et savoir quand c'est impossible sans restart.
Commandes principales
| Commande | Effet |
|---|---|
| /reload | Recharge server_scripts, datapacks, recettes, tags, loot tables. La commande la plus utilisée. |
| /kubejs reload server_scripts | Recharge UNIQUEMENT les server_scripts (plus rapide que /reload complet). |
| /kubejs reload client_scripts | Recharge les client_scripts (à exécuter côté client). |
| /kubejs reload startup_scripts | N'a PAS d'effet réel — affiché mais startup nécessite restart. |
| /kubejs hand | Affiche les infos complètes de l'item en main (id, NBT, tags). Indispensable pour écrire des recettes. |
| /kubejs errors | Liste les erreurs KubeJS du dernier reload. |
| /kubejs warnings | Liste les warnings (recettes en conflit, doublons d'id). |
| /kubejs export | Exporte les data dumps (recettes, tags) dans local/kubejs/export/. |
| /kubejs reload tags | Recharge uniquement les tags. |
| F3+T | (Client) Reload assets + client_scripts + textures + lang. |
Cheatsheet : quoi reload selon la modif
| Modif faite | Action |
|---|---|
| server_scripts/*.js | /reload OU /kubejs reload server_scripts |
| data/*.json (tags, recettes, loot) | /reload |
| client_scripts/*.js | F3+T sur le client |
| assets/* (textures, lang, sons) | F3+T sur le client |
| startup_scripts/*.js | Restart serveur |
| config/*.cfg ou *.toml | Restart serveur |
| Ajout/retrait d'un mod | Restart serveur + client |
7 — Le dossier data/ : datapack overrides
Du JSON pur, pas du JavaScript. Mais aussi puissant.
Le dossier kubejs/data/ contient des fichiers JSON qui surchargent les fichiers vanilla ou des mods au même chemin. C'est techniquement un datapack intégré, qui se recharge avec /reload.
Ce qui vit dans data/ chez Arcadia
| Chemin | Effet |
|---|---|
| data/apotheosis/rarities/ | Tables de poids des raretés par world tier (haven → pinnacle). |
| data/apotheosis/affixes/armor/attribute/winged.json | Affixe Winged (vol créatif) nerf : poids 25 → 3, mythic-only. |
| data/apotheosis/recipe/potion_charm.json | Recette endgame : HDPE Sheet + Rune Matrix. |
| data/apothic_attributes/brewing_mixes/ | Gates de vol (Dragon's Breath, Nether Star). |
| data/apothic_spawners/tags/entity_type/blacklisted_from_spawners.json | 37 mobs interdits dans les spawners Apothic. |
| data/arcadia/jukebox_song/ | Définitions des 20 musiques custom. |
| data/minecraft/tags/item/enchantable/durability.json | Retire 53 items custom du tag enchantable. |
| data/parcool/advancement/ | Désactive le spam du guide Parcool. |
Anatomie d'un override
Si Apotheosis a un fichier apotheosis:winged.json, créer kubejs/data/apotheosis/affixes/armor/attribute/winged.json remplace le fichier d'origine.
{
"replace": false,
"values": [],
"remove": [
"arcadia:adept_helmet",
"arcadia:heretic_chestplate"
]
}
C'est exactement comme ça que data/minecraft/tags/item/enchantable/durability.json retire 53 items custom du tag vanilla.8 — Modifications courantes : recettes pratiques
Les manips qu'on fait 9 fois sur 10.
🚫 Bannir un nouvel item
🔧 Modifier les stats d'un mob
Ouvre mob_stat_overrides.js. Les overrides sont commentés par catégorie (Twilight, Mowzie's, vanilla, etc.). Exemple :
// Pour augmenter le HP du Wither de 500 à 800 :
'minecraft:wither': { health: 800, damage: 12, armor: 15 },
Puis /reload. Les mobs déjà spawnés gardent leur ancien HP — les nouveaux auront les nouvelles valeurs.
💎 Modifier un drop rate
Ouvre items/loot/loot_table_nerfs.js. Diamond actuel = 0.5%, Netherite = 0.01%. Modifie la valeur, /reload, test sur un nouveau bloc miné.
➕ Ajouter une recette custom simple
ServerEvents.recipes(event => {
event.shaped('5x minecraft:bread', [
'WWW',
' S ',
' '
], {
W: 'minecraft:wheat',
S: 'minecraft:stick'
}).id('arcadia:bread_bonus');
});
Place ce fichier dans server_scripts/recipes/custom/. Toujours mettre un .id() explicite pour éviter les conflits.
🎨 Ajouter un nouvel item custom
StartupEvents.registry('item', event => {
event.create('arcadia:mon_item')
.displayName('Mon Item')
.rarity('rare')
.maxStackSize(16);
});
"item.arcadia.mon_item": "Mon Item"
9 — Erreurs courantes & debug
Les bugs typiques et comment les chasser.
Lire les logs (obligatoire)
3 fichiers à connaître :
- logs/kubejs/startup.log — erreurs de chargement startup (items, blocs custom).
- logs/kubejs/server.log — erreurs server_scripts (recettes, events).
- logs/kubejs/client.log — erreurs client (côté client uniquement).
- logs/latest.log — log global du serveur (les autres mods).
FAQ — les erreurs typiques
Q: "Item or tag does not exist: xxx:yyy"
R: L'item n'existe pas ou le mod est désactivé. Utilise /kubejs hand pour récupérer l'ID exact. Vérifie aussi que tu utilises le bon namespace (minecraft: vs arcadia:).
Q: "Recipe already exists" ou doublon d'id
R: Tu as deux recettes avec le même .id(). Renomme l'une des deux. Vérifie avec /kubejs warnings.
Q: Mon item custom n'a pas de texture (carré violet/noir)
R: Vérifie le chemin assets/arcadia/textures/item/<nom>.png. Le nom du fichier doit exactement matcher l'id de l'item. F3+T pour reload côté client.
Q: Mon item custom apparaît avec le nom "item.arcadia.xxx"
R: Traduction manquante dans assets/arcadia/lang/en_us.json (ou fr_fr.json selon la locale du joueur). F3+T après ajout.
Q: Le serveur ne démarre plus après modif startup
R: Ouvre logs/kubejs/startup.log. Cherche la ligne avec "Error" ou "Exception". Le numéro de ligne du .js est indiqué. Pour rétablir vite : renomme ton fichier en .disabled.
Q: La modif ne s'applique pas après /reload
R: 3 causes courantes :
- C'est un startup_script (restart obligatoire).
- C'est dans config/ et pas dans kubejs/ (config = restart).
- Erreur de syntaxe dans le script — vérifie /kubejs errors.
Q: Comment je teste une recette sans /reload ?
R: Tu ne peux pas. Mais /kubejs reload server_scripts est plus rapide que /reload complet.
Outils de debug
- /kubejs hand — donne l'ID complet + NBT de l'item en main.
- /kubejs errors — liste les erreurs du dernier reload.
- /kubejs warnings — liste les warnings (conflits, doublons).
- /kubejs export — exporte recettes/tags vers local/kubejs/export/ (utile pour vérifier qu'une recette est bien chargée).
- console.log() dans tes scripts — apparaît dans logs/kubejs/server.log.
10 — Bonnes pratiques staff Arcadia
Les règles à suivre pour garder un KubeJS sain.
✅ À faire
- Backup avant toute modif : cp -r kubejs kubejs.bak.YYYY-MM-DD.
- Commit Git après chaque modif testée. Le KubeJS doit être versionné.
- Tester sur serveur dev avant prod. Toujours.
- Toujours mettre un .id() sur les recettes custom.
- Toujours ajouter EN + FR pour les traductions d'items custom.
- Documenter dans modified_recipes.txt chaque ban/modif majeure.
- Lire les logs après /reload, même si "ça a l'air OK".
- Préférer .disabled à rm pour retirer un script (réversible).
❌ À ne pas faire
- Modifier un startup_script en prod sans annoncer un restart.
- Supprimer recipe_remover.js sans avoir d'abord vidé la liste — sinon les 152 bans sautent.
- Ajouter des accents dans les noms de fichiers.
- Mettre une recette sans id explicite — KubeJS génère un id auto qui peut bouger d'un reload à l'autre.
- Modifier directement les configs des mods alors qu'on peut le faire via KubeJS (plus propre, versionné).
- Ignorer les warnings — un warning ignoré pendant 3 mois devient un crash le jour où un mod update.
- kubejs.com/wiki/ — documentation officielle complète.
- Le fichier modified_recipes.txt à la racine du kubejs/ — référence staff de TOUTES les modifs Arcadia.
- Discord KubeJS pour les questions pointues (channel #help).
- Pull les dernières modifs Git : git pull.
- Backup local : cp -r kubejs kubejs.bak.
- Édite ton fichier (VS Code recommandé, syntax highlighting).
- Reload approprié (/reload ou restart).
- Check logs : /kubejs errors + /kubejs warnings.
- Test in-game 15 min minimum.
- Documente dans modified_recipes.txt si modif majeure.
- Commit + push : git add . && git commit -m "feat: ...".