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 loadsmain.ts
Section titled “main.ts”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.
Cleaning up
Section titled “Cleaning up”You mostly don’t. When the plugin unloads, Wraith undoes everything it set up and puts the game’s code back.
Settings
Section titled “Settings”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.
Game types
Section titled “Game types”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 structtotal += copy.health + copy.armor; // plain object reads, nothing touches memorycopy.health = 100;save(copy); // writes only the fields you changedA 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;});What JS can’t do
Section titled “What JS can’t do”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.
TypeScript or JavaScript
Section titled “TypeScript or JavaScript”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
