Concepts : comment fonctionne un mod

Chaque affirmation renvoie au code (crates/modding/src/…) ou à Mods TypeScript. Ce qui n'a pas pu être vérifié est marqué [À VÉRIFIER].

Trois genres de scripts, une seule API

Un mod ne peut pas appeler playfield.* ni lanes.set (réservés aux skins et scripts de map) ; un script de map ne peut pas utiliser hud.* ni storage.* (api.rs : playfield_call, for_mods_and_skins). Tableau complet : Disponibilité par genre de script.

Natif ou mod : qui décide quoi

Règle de classement (décision du joueur, 2026-10-11) : si ça touche au temps réel, c'est natif et expliqué comme une capacité de l'hôte ; si c'est de la présentation, de la règle ou une transformation de données, c'est un mod.

1. Natif : les entrées (Raw Input, horodatage QPC), le jugement, l'horloge de la chanson, l'audio, le rendu. Un script tourne sur un fil à part avec un budget (30 ms, 16 Mio) : le mettre dans ces chemins casserait les 2 500 FPS et la précision des entrées. Auto et Ghost sont donc natifs : ce sont des capacités de l'hôte (jouer à la place du joueur, rejouer un replay à côté), que le jeu présente sur la page Mods comme des mods pour l'interface, sans que leur script contienne de logique.
2. Mod : l'affichage (HUD, calques de skin), les règles de présentation (jeux de jugement, vitesses de défilement, notes de difficulté), et les transformations de données (les notes d'un chart), avec les API typées nécessaires.
3. Ne jamais appeler « mod » un simple interrupteur natif sans le dire : la documentation et l'interface disent quand un « mod » n'est qu'une déclaration dont l'hôte fait tout le travail.

Audit des mods livrés (content/mods/, 24 dossiers avec main.ts)

Les mods servaient donc surtout à l'affichage, aux règles de jugement et au défilement, presque pas à ce que fait le joueur. Les meilleurs exemples pour une communauté sont les fonctions du jeu elles-mêmes, écrites en mods lisibles.

Cycle de vie

1. Chargement : le premier niveau du fichier s'exécute. Seuls defineMod (ou defineSkin/defineChart), log.* et ctx.on fonctionnent ; tout autre appel hôte lève … is not available while the mod loads: call it from `setup` or an event handler. Le chargement sert aussi à l'installateur pour lire la déclaration sans exécuter setup.
2. Déclaration : defineMod doit être appelé exactement une fois, au premier niveau. Un second appel, une déclaration invalide ou un id déjà pris font échouer le mod, même si l'exception est rattrapée.
3. setup(mod) : appelée une fois, après le setup des paquets listés dans uses. Seul endroit où les *.register sont permis : ils se ferment après le chargement de tous les mods (… is only available in a mod's setup).
4. Événements : le mod reçoit game.*, library.*, controls.action, elements.configure, etc., et peut appeler game.*, hud.*, storage.*…

Ordre des mods : les fournisseurs avant leurs dépendants (uses), sinon loadOrder (0 à 10000, défaut 1000) puis id. Cet ordre décide aussi de l'empilement des calques HUD et de la livraison des événements.

Les mods se chargent en arrière-plan : le jeu n'attend pas. Un mod désactivé par le joueur est déclaré (ses métadonnées sont lues) mais son setup ne tourne pas. Un skin et un script de map sont rechargés à neuf à chaque lancement de map : rien ne persiste d'une partie à l'autre, sauf storage pour les mods.

Threads et budgets

• Tout le code des mods, du skin et des scripts de map tourne sur un seul thread mods, jamais sur les threads d'entrées, de rendu, audio ou de fenêtre. Les threads de jeu envoient des événements par une file bornée (1024) sans jamais attendre les mods ; si elle est pleine, l'événement est perdu. Conséquence : un événement peut manquer. Ne bâtissez pas un état critique sur la réception de chaque game.judgement ; relisez game.player() ou les totaux (counts, combo, accuracy portés par chaque événement).
• Les mods livrés partagent un moteur Manivelle (QuickJS, réserve de 16 Mio × leur nombre) et chaque mod du joueur a le sien (voir Budgets) : 16 Mio de mémoire, 1 Mio de pile, 30 ms d'exécution par chargement, setup, événement ou tick (Budgets).
• Un mod est désactivé après 3 échecs consécutifs (exception non rattrapée ou dépassement) ou 3 dépassements de budget au total, jusqu'au prochain démarrage de l'hôte.
• Les valeurs qui changent à chaque image ne doivent pas passer par le script : utilisez les liaisons (bind, fill, showWhen, animate) que la surcouche résout toute seule, et les animations/déclencheurs de stage.* que le rendu évalue. Un script efficace ne s'exécute que quelques fois par seconde.

Événements

Payloads : Événements.

Dépendances et éléments configurables

Un mod (ou un skin) déclare uses: { "autre.mod": "^1" } ; une dépendance est facultative par défaut (absente, ctx.has("autre.mod") vaut false et une note apparaît sur la page Mods). required: true la rend obligatoire. 16 dépendances au plus, pas de cycle (dependency cycle: a → b → a).

Un mod expose des widgets avec provides.elements (options typées : number, integer, boolean, string, color, enum, colors). Les autres paquets les placent avec ctx.element("<paquet>/<élément>").configure({…}) ; le fournisseur reçoit elements.configure. Ordre unique de priorité : défauts déclarés < configure() du skin < configuration du joueur dans l'éditeur de skin. Les scripts ne s'appellent jamais entre eux.

Permissions

Trois permissions existent (type Permission = "stage" | "skinImport" | "network"), à déclarer dans permissions: [...] :

network ne donne aucun accès réseau au script : il autorise seulement à déclarer des hôtes ; l'hôte (crates/downloader) fait toutes les requêtes, en HTTPS, sur ces hôtes seulement, et garde le jeton du joueur. Il n'y a pas de permission fichier ou DOM : ces accès n'existent pas du tout.

Erreurs que vous verrez

Un mod en échec n'est pas chargé et l'erreur apparaît sur la page Mods ; les autres mods se chargent normalement. Le chargement transpile sans vérifier les types : une erreur de type n'apparaît qu'avec tsc (voir README).

Déterminisme et rejeu

• Les jugements sont natifs : un script ne peut ni injecter d'entrées, ni modifier un jugement, ni un score (gameplay.register ne fait que déclarer un genre connu de l'hôte).
• Une transformation des notes (chartTransform) : le script lit chart.getNotes() et rend chart.setNotes(tampon) ; Rust valide le tampon (crates/core/src/scripted_notes.rs) et refuse l'invalide en retirant seulement cette modification. La partie enregistre les notes résultantes (chartMods.scripted) : elle se rejoue sans le mod, et ce tampon, pas le code, fait foi.
• Les paliers d'un jeu de jugement sont résolus une fois par combinaison de paramètres puis enregistrés tels quels dans les replays, qui se rejugent sans le mod. tiers(params) doit donc être pure et synchrone. De même les conversions toMs des vitesses de défilement : le rendu ne reçoit que le temps résolu.
• Un script de map est visuel : le replay n'enregistre que son empreinte BLAKE3.
• Les Hit de game.hits sont l'historique natif réel (accords et relâchements séparés compris), pas une reconstruction par événements.
• Fonctions non déterministes (Math.random, Date) : leur disponibilité dans le moteur n'est pas documentée dans le code lu [À VÉRIFIER] ; ne les utilisez pas pour un contenu qui doit rester identique d'une partie à l'autre. Il n'y a ni timers (setTimeout…), ni réseau (la permission network ne fait que déclarer des sources), ni accès fichier (Sécurité).

Ce qu'un mod ne peut JAMAIS faire

• Accéder au DOM, au JavaScript de l'interface, aux commandes IPC, au réseau (le script ne fait jamais de requête, même avec network), aux fichiers hors de son dossier, aux timers.
• Injecter des touches, modifier le jugement, le score ou un replay (ce qui est temps réel reste natif, voir la règle).
• Dessiner du HTML ou du CSS brut, charger un shader personnalisé.
• Lire le stockage d'un autre mod, ou appeler un autre mod directement.
• Charger une bibliothèque native (DLL) : hors périmètre (AGENTS.md).
• Lire un autre fichier que ses polices (.ttf/.otf) et images (.png) déclarés.
• import() dynamique (refusé) ; les imports relatifs et node_modules du dossier du mod sont résolus, jamais hors du dossier.
• Ajouter un modificateur qui touche aux entrées ou au jugement : les genres auto et ghost sont natifs et fermés. Une transformation des notes passe par chart.getNotes / chart.setNotes (kind: "chartTransform"), jamais par un genre natif ; fullLn reste natif (paramètres typés et aperçu fournis par l'hôte). hidden, sudden et lift sont natifs parce que leur dessin passe par playfield, que seuls les skins et les maps peuvent appeler ; ils ne touchent ni aux notes ni au jugement.

Mods, skins, thèmes : ne pas confondre

• Un thème (content/themes/<id>/) est de la donnée (manifeste + tokens.css), jamais du code : voir Thèmes d'interface.
• Un skin est du code (skin.ts) qui configure le playfield et les éléments.
• Un mod fournit les widgets, les jeux de jugement, etc.