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.

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.

Tableau récap

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

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.

Procédure recommandée pour retirer un script

6 — Recharger le KubeJS : les commandes

Reloader sans casser, et savoir quand c'est impossible sans restart.

Commandes principales

Cheatsheet : quoi reload selon la modif

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

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"
    ]
}

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.