Modèle de script et cycle de vie

Les quatre catégories de scripts

Incluez <mtr/script.hpp>, héritez de la classe de base correspondante et exportez-la avec la macro d’enregistrement. Le paramètre modèle de la classe de base est le type d’état par instance :

Le squelette d’un script de véhicule (pour les trois autres catégories, seuls la classe de base et les types de paramètres changent) :

#include <mtr/script.hpp>

struct MyVehicleState {
    mtr::CycleTracker dest{"KOWLOON|TSUEN WAN"};   // n'importe quel type C++ à vous
    mtr::Api::Object tracker;                        // handle d'objet Java
    std::unique_ptr<mtr::GraphicsTexture> lcd;    // ressource détenue
};

struct MyVehicleScript : mtr::VehicleScript<MyVehicleState> {
    static constexpr auto ID = "demo:vehicle";

    void create(mtr::VehicleContext& ctx, MyVehicleState& state,
                const mtr::Vehicle& vehicle) override {
        // appelé une fois avant la première frame : créer les ressources, enregistrer les callbacks
    }

    void render(mtr::VehicleContext& ctx, MyVehicleState& state,
                const mtr::Vehicle& vehicle) override {
        // appelé à chaque frame : lire l'instantané, écrire les enregistrements de dessin
    }

    void dispose(mtr::VehicleContext& ctx, MyVehicleState& state,
                 const mtr::Vehicle& vehicle) override {
        // appelé avant la destruction de l'instance : libérer les ressources
    }
};

MTR_REGISTER_VEHICLE_SCRIPT(MyVehicleScript)

• ID est l’identifiant nommé du script (par ex. demo:vehicle) ; il doit être identique au champ id de l’entrée déclarée dans le mtr_custom_resources.json du pack de ressources.
• Les trois fonctions du cycle de vie peuvent toutes être surchargées au besoin (la classe de base fournit des implémentations vides) ; leurs signatures sont fixes.
• Une unité de traduction enregistre un seul script ; pour plusieurs scripts, répartissez-les dans plusieurs bibliothèques modules.

State : l’état par instance

Chaque instance de script (chaque véhicule, chaque bloc-entité PIDS…) possède son propre bloc State indépendant, alloué et construit par l’hôte :

• L’hôte alloue le bloc d’état selon mtrStateSize() (généré par la macro d’enregistrement à partir de sizeof(State)) et le construit via mtrInit() par placement-new avant la première utilisation — ne supposez pas qu’une mémoire remplie de zéros est utilisable (les types non triviaux comme std::string ont un comportement indéfini sur de la mémoire nulle).
• Le contenu du bloc d’état persiste d’une frame à l’autre : placez-y les textures, les handles de modèles, les callbacks et les caches.
• Les membres de la classe de script (les champs que vous écrivez dans MyVehicleScript) sont en revanche partagés par toutes les instances du module — n’y placez que des constantes en lecture seule et de la configuration globale.
• Le bloc d’état est détruit dès que dispose retourne ; une instance est retirée environ 5 secondes après sa disparition du côté client, et toutes sont détruites au rechargement du pack de ressources (F3+T).

Ordonnancement du cycle de vie

Modèle de threading

• L’hôte appelle en série toutes les fonctions du cycle de vie d’un module donné sur un unique thread d’arrière-plan par module (miroir de l’exécuteur mono-thread par script que JCM applique aux scripts JS) — les create / render / dispose d’une même instance ne sont jamais concurrents.
• En revanche, render et les callbacks asynchrones peuvent être concurrents (une tâche soumise au BackgroundWorker peut s’exécuter à cet instant sur un autre thread) : la synchronisation de l’état mutable partagé incombe au script.
• Au rechargement du pack de ressources, les callbacks sont d’abord arrêtés et les appels en cours attendus, puis les états sont détruits et le code déchargé.

Isolation des plantages

Les macros d’enregistrement enveloppent chaque fonction exportée dans un garde-fou anti-plantage (crash_guard.hpp) :

• Défauts matériels du type segmentation fault → seul le module est désactivé, le processus du jeu continue de tourner ; latest.log conserve une ligne native script faulted … module disabled.
• Les exceptions C++ non interceptées sont elles aussi bloquées par le garde-fou — mais faites vos propres try/catch pour garder une sémantique claire.
• Les signaux POSIX ne sont pas « récupérés » à la longjmp : sauter par-dessus le gestionnaire de signal est plus dangereux que le plantage lui-même ; la mise hors ligne immédiate du module est un choix délibéré.

Codes de retour

Ces codes de retour sont générés par le SDK ; un code de script ordinaire n’a pas à s’en soucier. Si vous écrivez un hôte personnalisé ou un pilote de test, interprétez-les selon le tableau ci-dessus (détails dans ABI C et services de l’hôte).

Ensuite : Instantanés de données — ce que render peut lire ; Dessin et canevas — comment le dessiner.