Skip to content

Writing a plugin

Adrià edited this page Nov 18, 2026 · 1 revision

A plugin is a native library (.dll on Windows, .so on Linux) that a mod carries in its plugin/ folder. When the player turns the mod on, mkw-recomp loads it at start, before the game code, and hands it a table of functions: with them the plugin can replace functions of the game or of the Switch SDK, call the game's code, read and write its memory, and show things on screen. It is the way to add something that patches cannot, without changing mkw-recomp itself.

The whole API is one header, runtime/plugin/mkw_plugin.h: include it, and link against nothing of mkw-recomp. Its comments are the reference; this page is the overview.

Plugins come with the release after v0.1.13. On main today; Linux tested, Windows .dll not tested yet.

The smallest plugin

#include "mkw_plugin.h"

static const MkwPluginApi *api;

static void loaded(void *user) {
    api->notice("Hello from a plugin", 5);   // a line at the top of the picture for 5 seconds
}

MKW_PLUGIN_EXPORT int mkw_plugin_init(const MkwPluginApi *a, uint32_t version, const char **message) {
    if (version < 1 || a->size < sizeof(MkwPluginApi)) {
        *message = "needs a newer mkw-recomp";   // shown to the player; the game starts without the plugin
        return 1;
    }
    api = a;
    api->on_game_loaded(loaded, 0);
    return 0;   // 0 = stay loaded
}

A complete one that draws a box on screen: tools/plugin/example_plugin.c.

Building and packaging

# Linux
cc -std=c11 -O2 -shared -fPIC -fvisibility=hidden -I <path to mkw_plugin.h> myplugin.c -o myplugin.so
# Windows (MinGW or llvm-mingw)
clang -O2 -shared -I <path to mkw_plugin.h> myplugin.c -o myplugin.dll

The mod is a folder (or a .zip of it) with the libraries in plugin/. One archive can serve both systems: each loads only its own extension.

MyMod/
  plugin/
    myplugin.dll
    myplugin.so
  romfs/        (optional: game files, as any mod)

Players install it from the Mods page, by importing the archive or from GameBanana when it is uploaded there as a Mario Kart World mod. To try it yourself without the page: put the folder in mods/ of the game folder and run mkw --play --mod MyMod. Its lines go to logs/mkw.log, prefixed plugin:.

What the table gives

When Functions
Any time log, cfg_get (an MKW_* setting), guest_symbol, module_base, guest_modules; port_version, game_version (1.0.0, 1.8.0), game_id (the game code's build: pick your addresses by it), mod_dir, mod_name
Only in mkw_plugin_init override_symbol(name, fn): every call of the game to that function (an nn:: SDK function or any other import or export) runs yours, no limit on how many; stock(name): mkw-recomp's own replacement, to chain to it; on_game_loaded(cb); overlay_set(draw)
In mkw_plugin_init or on_game_loaded override_address(addr, fn): indirect calls to a game function (virtual functions, function pointers) run yours
Inside an override (on a game thread) call(cpu, fn, n, ...) a game function, call_original(cpu) the function you replaced, current_cpu(), core_away() / core_back() around a wait
Any thread notice(text, seconds), overlay_show(draw, on)

An override gets the game thread's CPU state, MkwCpu: arguments in x[0..7], the result goes in x[0], the caller's return address is x[30].

Rules worth knowing

  • Game memory is mapped 1:1: a game address is a pointer in the process (mkw_guest_ptr(addr)), from any thread.
  • Only game threads call game code. A thread of your own (a socket loop, say) hands its work to an override the game calls often, and that override does the call.
  • Waiting inside an override (a socket, a sleep): wrap it in core_away() / core_back(), so the game's other threads keep running meanwhile.
  • The overlay drawing runs on the present thread once per frame while it is shown: rectangles and text only, no game code, no waiting. It sits under mkw-recomp's own menu and windows.
  • Text entry is built in: when the game asks for a number or a code (nn::swkbd), mkw-recomp shows its own number pad, worked with a controller, the mouse or the keyboard. A plugin needs none of its own.
  • Versions: the table only grows. Check size before using a field added later, and your plugin keeps loading on newer releases without a rebuild. Game addresses change between game versions: choose them by game_version or game_id, and decline (return non-zero with a message) on a build you do not know.
  • Two plugins replacing one function: the one loaded later wins; it can chain with call_original.

What this project does not take

mkw-recomp hosts no plugins (see CONTRIBUTING). The API is generic on purpose: what a plugin does is its author's business and responsibility. Questions about the API go to Discussions.

Clone this wiki locally