Repository navigation
Writing a plugin
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
maintoday; Linux tested, Windows.dllnot tested yet.
#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.
# 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.dllThe 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:.
| 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].
-
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
sizebefore using a field added later, and your plugin keeps loading on newer releases without a rebuild. Game addresses change between game versions: choose them bygame_versionorgame_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.
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.
Something wrong or missing here? Say so in Discussions. mkw-recomp is not affiliated with Nintendo.