mtr::Api and Java interop

When to use Api

Objects and calls

Construct an Api from the current frame's input; navigate from the root objects (context() / wrapper()), static classes, or 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)

JS ↔ C++ cheat sheet

AWT classes use fully qualified names: java.awt.Color, java.awt.Font, java.awt.BasicStroke, java.awt.geom.AffineTransform. The public GraphicsTexture fields graphics / bufferedImage expose the real Java2D objects. Resource path resolution: Resources.idr resolves against this module's declaration path (with multiple library declarations, each uses its own); Resources.manager() is null on MTR 4, same as JS. Members new in upstream v2.3.0-prerelease.2 — the Resources.id(id, suffix) concatenation form, the Resources.mgr() alias (ANTE resource-pack compatibility), string-argument variants such as VanillaText.withFont(String) — work out of the box over the same JSON-RPC channel. Capabilities the upstream documentation marks as unimplemented (the vehicle coupler's drawConnModel / drawConnStretchTexture) are equally not invented here.

Background callbacks

Api::Callback wraps a C++ function into a Java functional interface (Runnable / Consumer / Function, …). Callback objects must stay alive until Java can no longer possibly call them — put them in State:

struct State {
    std::unique_ptr<mtr::Api::Callback> task;   // keep it until 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"});
        // publish the result into your own synchronized state; read it in render
        return mtr::Json();
    });
    api.root("BackgroundWorker").call("submit", {*s.task});
}

• render and callbacks can run concurrently — lock shared mutable C++ state yourself.
• A reload first stops callbacks and waits for in-flight calls to return, then destroys the state and unloads the code.
• GPU models prepared in the background upload via DynamicModelHolder.uploadLater; a direct ModelManager.upload still requires the Java render thread (call it from create or a main-thread callback).

Coverage

The commonly used API surface: console, Resources, ModelManager / Model / RawModel / RawMeshBuilder / DynamicModelHolder, Vector3f, Matrices, GraphicsTexture plus Java2D, RenderManager / QuadDrawCall, SoundManager / TickableSoundInstance, MinecraftClient, PlayerEntity / ItemStack / VanillaText / VoxelShape, Files, Networking, BackgroundWorker, TextUtil / Timing / StateTracker / CycleTracker / RateLimit, DataReader, MTRClientData, the TSC data classes, and DisplayHelper. The callable member lists for PIDS / eyecandy / vehicle are recorded in the repository's bench/api-coverage.json; for lifts, the Java wrapper is authoritative.

After building, you can audit your call surface against the real MTR jar:

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

Up next: C ABI and host services — the complete contract at the module boundary.