mtr::Api et interopérabilité Java

Quand utiliser Api

Objets et appels

Construisez Api avec l’entrée de la frame courante ; naviguez depuis les objets racine (context() / wrapper()), les classes statiques ou new :

struct State { mtr::Api::Object tracker; };

struct Example : mtr::PidsScript<State> {
    static constexpr auto ID = "example:arrivals";

    void create(mtr::PidsContext& ctx, State& state, const mtr::Pids&) override {
        mtr::Api api(ctx.input());
        state.tracker = api.create("StateTracker");            // new StateTracker()
        api.context().call("setZOrderStep", {0.0002});         // ctx.setZOrderStep(0.0002)
    }

    void render(mtr::PidsContext& ctx, State& state, const mtr::Pids&) override {
        mtr::Api api(ctx.input());
        auto arrivals = api.wrapper().call("arrivals");        // wrapper.arrivals()
        if (arrivals.call("size").as<int>() == 0) return;
        auto arrival = arrivals.call("get", {0});
        if (arrival.is_null()) return;

        auto text = api.call("Text", "create");                // new Text()
        text.call("text", {arrival.call("destination")});
        text.call("pos", {2.0, 3.0});
        text.call("draw", {api.context()});
    }
};
MTR_REGISTER_PIDS_SCRIPT(Example)

Tableau de correspondance JS ↔ C++

Les classes AWT s’utilisent avec leur nom complet : java.awt.Color, java.awt.Font, java.awt.BasicStroke, java.awt.geom.AffineTransform. Les champs publics graphics / bufferedImage de GraphicsTexture exposent les véritables objets Java2D. Résolution des chemins de ressources : Resources.idr se base sur le chemin déclaré du module courant (en cas de déclarations multi-bibliothèques, chacune utilise le sien) ; Resources.manager() vaut null, comme en JS sur MTR 4. Les nouveaux membres de l’amont v2.3.0-prerelease.2 — la forme de concaténation Resources.id(id, suffix), l’alias Resources.mgr() (compatibilité des packs de ressources ANTE), les variantes à argument chaîne comme VanillaText.withFont(String) — fonctionnent tels quels via le même canal JSON-RPC. Les capacités signalées comme non implémentées dans la documentation amont (drawConnModel / drawConnStretchTexture pour les attelages de véhicules) ne sont pas davantage inventées par ce mod.

Callbacks en arrière-plan

Api::Callback encapsule une fonction C++ en interface fonctionnelle Java (Runnable / Consumer / Function…). L’objet de callback doit rester en vie tant que Java peut encore l’appeler — placez-le dans State :

struct State {
    std::unique_ptr<mtr::Api::Callback> task;   // conservé jusqu'à la destruction
};

void create(mtr::PidsContext& ctx, State& s, const mtr::Pids&) {
    mtr::Api api(ctx.input());
    s.task = std::make_unique<mtr::Api::Callback>([api](mtr::Json) {
        auto response = api.call("Networking", "fetch",
                                 {"https://example.org/data"});
        // publier le résultat dans votre propre état synchronisé ; lu dans render
        return mtr::Json();
    });
    api.root("BackgroundWorker").call("submit", {*s.task});
}

• render et les callbacks peuvent être concurrents — verrouillez vous-même l’état C++ mutable partagé.
• Au rechargement, les callbacks sont d’abord arrêtés et les appels en cours attendus, avant la destruction des états et le déchargement du code.
• Les modèles GPU préparés en arrière-plan se téléversent via DynamicModelHolder.uploadLater ; ModelManager.upload en direct exige toujours le thread de rendu Java (appelez-le depuis create ou un callback du thread principal).

Couverture

Surface d’API usuelle : console, Resources, ModelManager / Model / RawModel / RawMeshBuilder / DynamicModelHolder, Vector3f, Matrices, GraphicsTexture et Java2D, RenderManager / QuadDrawCall, SoundManager / TickableSoundInstance, MinecraftClient, PlayerEntity / ItemStack / VanillaText / VoxelShape, Files, Networking, BackgroundWorker, TextUtil / Timing / StateTracker / CycleTracker / RateLimit, DataReader, MTRClientData, les classes de données TSC et DisplayHelper. La liste des membres appelables de PIDS / eyecandy / véhicule est consignée dans bench/api-coverage.json du dépôt ; pour l’ascenseur, l’enveloppe Java fait foi.

Après compilation, vous pouvez auditer votre surface d’appels face au véritable jar MTR :

python native/bench/api_coverage.py \
    --classes fabric/build/classes/java/main \
    --jar path/to/mtr.jar

Ensuite : ABI C et services de l’hôte — le contrat complet de la frontière du module.