Quick start

Prerequisites

Get the SDK

The SDK ships with every release as jcm-native-sdk-<version>.zip (see the GitHub Releases assets); its contents are the source of the repository's native/ directory:

jcm-native-sdk-2.3.0-1.0.2/
├── include/mtr/          # All SDK headers (script.hpp is the single entry point)
│   ├── mtr_native.h      # C ABI: exported functions, snapshots, draw records, host services
│   ├── script.hpp        # Script base classes + registration macros (one #include is all you need)
│   ├── vehicle.hpp  pids.hpp  lift.hpp  eyecandy.hpp
│   ├── gfx.hpp  gfx2d.hpp  font5x7.hpp  text.hpp  matrices.hpp
│   ├── api.hpp           # mtr::Api (full Java API access)
│   └── crash_guard.hpp ...
├── examples/             # Three minimal example modules
├── bench/                # Tests and tooling
└── CMakeLists.txt

Set up a module project

The easiest path: unzip the SDK into your resource pack project and append your own targets to the end of its CMakeLists.txt — the SDK already wraps every platform's linking details (prefix-less .dll on Windows, .dylib plus -undefined dynamic_lookup on macOS, 16 KB page alignment on Android) in the mtr_add_script() function:

# Append to the end of the SDK's native/CMakeLists.txt
mtr_add_script(my_pids src/my_pids.cpp)

If you prefer a standalone project, here is a complete template equivalent to that function:

cmake_minimum_required(VERSION 3.16)
project(my_native_scripts LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# SDK header path (point this at the extracted SDK include directory)
add_library(mtr_script_sdk INTERFACE)
target_include_directories(mtr_script_sdk INTERFACE path/to/sdk/include)

function(mtr_add_script name)          # Module target function, same as the SDK's
  add_library(${name} MODULE ${ARGN})
  target_link_libraries(${name} PRIVATE mtr_script_sdk)
  set_target_properties(${name} PROPERTIES CXX_VISIBILITY_PRESET hidden)
  if(WIN32)
    set_target_properties(${name} PROPERTIES PREFIX "" SUFFIX ".dll")
  elseif(APPLE)
    set_target_properties(${name} PROPERTIES PREFIX "lib" SUFFIX ".dylib")
    target_link_options(${name} PRIVATE "-Wl,-undefined,dynamic_lookup")
  elseif(ANDROID)
    target_link_options(${name} PRIVATE "-Wl,-z,max-page-size=16384")
  endif()
endfunction()

mtr_add_script(my_pids src/my_pids.cpp)

Your first module

A minimal PIDS arrival display module — complete, compilable, and ready to drop straight into the game:

#include <mtr/script.hpp>

struct ArrivalState {};                    // Per-instance persistent state (empty in this example)

struct ArrivalDisplay : mtr::PidsScript<ArrivalState> {
    static constexpr auto ID = "example:arrivals";   // Must match the resource pack declaration

    void render(mtr::PidsContext& ctx, ArrivalState&,
                const mtr::Pids& pids) override {
        for (int row = 0; row < pids.rows(); row++) {
            if (pids.is_row_hidden(row)) continue;

            std::string text = pids.get_custom_message(row).str();
            if (text.empty() && row < pids.arrivals().size())
                text = pids.arrivals().at(row).destination().str();

            if (!text.empty())
                mtr::Text::create()
                    .text(text.c_str())
                    .pos(2, row * 10.0 + 2)
                    .size(pids.width() - 4, 9)
                    .draw(ctx);
        }
    }
};

MTR_REGISTER_PIDS_SCRIPT(ArrivalDisplay)

Key points:

• The base class determines the script type — PidsScript / VehicleScript / LiftScript / EyecandyScript; the template argument is the per-instance state type.
• The lifecycle is the same as JS: override the three virtual functions create / render / dispose as needed (all optional).
• The registration macro expands to all ABI exports; one translation unit registers exactly one script.

More examples live in the SDK's examples/: minimal samples for each of the vehicle / lift / eyecandy kinds.

Build

cmake -S native -B native/build -DCMAKE_BUILD_TYPE=Release
cmake --build native/build --config Release --parallel 4
ctest --test-dir native/build -C Release --output-on-failure   # Optional: run the SDK's bundled tests

Package into a resource pack

Directory layout

Drop each platform's build output into the resource pack's natives/<platform>/ directory:

my_pack/
├── natives/
│   ├── windows-x64/my_pids.dll
│   ├── windows-arm64/my_pids.dll
│   ├── linux-x64/libmy_pids.so
│   ├── linux-arm64/libmy_pids.so
│   ├── macos-x64/libmy_pids.dylib
│   ├── macos-arm64/libmy_pids.dylib
│   ├── android-arm64/libmy_pids.so
│   └── ios-arm64/libmy_pids.dylib
└── ... (the rest of the pack: textures, models, and so on)

Declare it in joban_custom_resources.json (PIDS preset)

No language field is needed — the mod detects the language automatically from the characteristics of each scriptLocations entry, and any number of JS and C++ files can be mixed within one entry:

{
    "pids_images": [{
        "id": "example:arrivals",
        "scriptLocations": [
            "mtr:my_pack/natives/my_pids"
        ]
    }]
}

Entry resolution rules:

• Same rules for all four script kinds: vehicleScripts / objectScripts / liftScripts in mtr_custom_resources.json and pids_images presets (via scriptLocations) in joban_custom_resources.json all support the mixed declarations above.
• Legacy format still works: old declarations using "language": "cpp" plus nativeLibrary / nativeLibraries keep working and can be mixed with .js; "language": "javascript" forces the whole entry to be parsed as JS.
• JS fields behave as usual: fields such as prependExpressions / input / dataFetchMode keep their meaning, and the C++ side reads input through api.input().
• Keep rendering off-screen: the PIDS preset field outOfBound: true (upstream v2.3.0-prerelease.3) keeps the preset rendering when the screen is out of the camera's bounds — needed for projector presets that must run constantly.

Verify in game

1. Install JCM Yanyang and MTR, drop the resource pack into resourcepacks/ and enable it (or ship it as built-in assets with a world).
2. Place the corresponding block (e.g. a PIDS) and select your script in its configuration / make the declaration entry take effect.
3. Open logs/latest.log and search for native script — at load time the mod prints a module census summary (module count, script types, transport channel, and so on). Seeing your example:arrivals means it loaded successfully.
4. After changing library files, press F3+T to reload resource packs — that also reloads C++ scripts (or use the mod's "Reload all MTR scripts" keybind); no game restart needed.

Next up: Script model and lifecycle — the full semantics of the four script kinds; or jump straight to Data snapshots for a look at the readable data.