Skip to content

Plugin structure

Here’s what the template gives you.

my-plugin/
src/main.ts your code
schemas/game.sal the game's types
public/ copied into dist/ as is
wraith.json the manifest
package.json
.wraith/types/ typings, made for you
dist/ the build, what Wraith loads

Your code runs top to bottom when the plugin loads. There’s no start or main to export.

import { config, frame, keybinds, ui } from "wraith";
const settings = config.load({ visible: true });
keybinds.bind("toggle", { name: "Show the window", chord: "ctrl+f8" }, () => {
settings.visible = !settings.visible;
});
frame.onFrame(() => {
if (!settings.visible) return;
ui.window("My Plugin", () => {
ui.text("Hello!");
});
});

Everything comes from the wraith module, and autocomplete shows what’s in it.

You mostly don’t. When the plugin unloads, Wraith undoes everything it set up and puts the game’s code back.

config.load(defaults) gives you an object with the saved values on top of your defaults. Change it and it’s saved. Use gameConfig for settings that should be separate for each game.

Put schemas in schemas/ and import them from "schema", fully typed.

import { Player } from "schema";
const player = Player.at(address);
player.health = 100;

Every build regenerates the types, so they’re always in step with your .sal files. Get the schema right in the Workbench first, then copy it in.

Each field you read or set on player goes to the game’s memory right then, so it’s always current. That costs a little every time, which adds up in loops over lots of objects. For those, take a snapshot:

import { snapshot, save, edit } from "salamander";
const copy = snapshot(player); // one read of the whole struct
total += copy.health + copy.armor; // plain object reads, nothing touches memory
copy.health = 100;
save(copy); // writes only the fields you changed

A snapshot is a plain object. Structs and arrays inside it are plain too, and pointers stay live objects. It doesn’t follow memory, so take a new one when you want fresh values. save writes only what changed since the snapshot was taken, so fields the game changed meanwhile stay as they are, and it gives how many it wrote. Text fields aren’t written.

edit takes a snapshot, hands it to you, and saves it after, even if your function is async:

edit(player, (p) => {
p.health = 100;
p.pos.y += 2;
});

Plugins run in QuickJS, not Node or a browser. Modern JavaScript works, but APIs like fs and fetch aren’t there. npm packages that are plain JavaScript bundle in fine.

The only difference is the file. With --js you get src/main.js, and // @ts-check at the top still checks it against Wraith’s typings.

Made with ♥ by Asgard