Skip to content

Plugin structure

A Zig plugin is a struct with start and maybe stop.

const std = @import("std");
const sdk = @import("wraith_sdk");
pub const std_options: std.Options = .{ .logFn = sdk.logFn };
pub const panic = sdk.panic;
const log = sdk.log.scoped(.my_plugin);
pub const Plugin = struct {
ctx: *sdk.Context = undefined,
pub fn start(self: *Plugin, ctx: *sdk.Context) !void {
self.ctx = ctx;
log.info("Hello!", .{});
}
pub fn stop(self: *Plugin) void {
_ = self;
}
};
comptime {
sdk.exportPlugin(Plugin);
}

std_options and panic send logs and crashes to Wraith’s log. exportPlugin checks your struct and turns it into what Wraith loads. It tells you at compile time if start or stop look wrong.

ctx is yours for the plugin’s lifetime.

  • ctx.allocator is a heap that reports leaks when the plugin unloads.
  • ctx.io is for anything that waits.
  • ctx.config(T) loads settings. Every field in T needs a default.
  • ctx.gameConfig(T) does the same, but separately for each game.
  • ctx.addWindow and ctx.keybind add UI and keys. See UI and Keybinds and input.

Plugins spend most of their time waiting, for a key or the next frame. Tasks let you write that as a plain loop.

try ctx.spawn(watch, .{ self, ctx.io });
fn watch(self: *Plugin, io: std.Io) !void {
while (true) {
try sdk.frame.next(io);
// runs once a frame, on the render thread
}
}

Tasks start on the render thread, where they can draw. Never block there, since the game waits for it. For slow work, hop to a worker and back.

try sdk.frame.toWorker(io);
const result = slowThing();
try sdk.frame.toRender(io);

Before stop, every task is cancelled. Their waits fail with error.Canceled so they can wind down.

Put schemas in a schemas/ folder and they become Zig types, imported as schema.

const schema = @import("schema");
const player: *schema.Player = @ptrFromInt(address);
player.health = 100;

They’re real extern structs with the offsets baked in. Get the schema right in the Workbench first, then copy it in.

When the plugin unloads, Wraith undoes everything it set up and puts the game’s code back. Use stop for your own stuff, like saving settings.

Made with ♥ by Asgard