Skip to content

Your first mod

This tutorial makes a small script mod from an empty folder: it writes Link’s hearts to the log when they change, shows them on the HUD, and turns them red at a number of hearts the player chooses. On the way it covers the tools, the manifest, the game’s dev mode, tests without the game, a HUD, a setting, and packing the mod to share it. It takes about half an hour.

The finished mod is in the repository as modapi/examples/first-mod, with its tests: copy it if you would rather start from the end. Each snippet below is a step of that mod, and its tests run in Longshot’s checks.

The API is a preview (0.x). Script mods run in the game, but few have been played with yet, and a new minor version of the API may change anything here. File mods (textures, models, texts) need none of this: using mods and the file mod contract cover them.

Steps: 1. The tools · 2. The folder · 3. The manifest · 4. A first script · 5. In the game · 6. Tests · 7. A HUD · 8. A setting · 9. Lint and pack · Next

1. Install the tools

  • Node.js, through mise. Install mise (its getting started: curl https://mise.run | sh on Linux and macOS, winget install jdx.mise on Windows), then, in the mod’s folder (step 2):

    Terminal window
    mise use node@26

    That writes a mise.toml beside mod.json pinning the mod’s Node, and mise puts that Node on the PATH whenever you are in the folder. longshot-mod needs Node 22 or later; 26 is the one Longshot’s own mods use. Plain node from anywhere (nodejs.org, your system’s packages) works too, if it is 22 or later. The game never runs Node: it is only for your tools, the type checker, longshot-mod and its fake game.

  • A Longshot checkout. The two packages a mod uses, @longshot/api (the API’s types) and @longshot/mod-tools (the longshot-mod command), are not on a package registry yet, so a mod points at them in a checkout:

    Terminal window
    mkdir my-mods && cd my-mods
    git clone https://git.magicbean.dev/MagicBeanDev/Longshot.git

    Don’t install anything named @longshot/... from the public registry: nobody there owns that scope.

  • TypeScript 7 comes with each mod, through npm ("typescript": "7.0.2" in its package.json; npm install puts it in the mod’s folder), not through mise. Mods are written in TypeScript: your editor and tsc know the whole API, so a misspelt call, a missing permission or a value that can be null is marked before anything runs. tsc only checks: there is no build step. The game compiles your TypeScript to JavaScript itself as it loads it, and the tools’ fake game does the same with the same compiler (How TypeScript runs).

  • The game, built by the launcher, to try the mod in (step 5). Steps 6 to 9 need no game.

2. Make the mod’s folder

There is no longshot-mod new command yet (nor npm create longshot-mod), so make the folder by hand, beside the checkout:

my-mods/
Longshot/ the checkout
first-mod/
mod.json the manifest (step 3)
mise.toml the mod's Node (mise use node@26)
package.json
tsconfig.json
src/
main.tsx the script (step 4)
test/
first-mod.test.ts its tests (step 6)

src/ is what the game runs: there is no dist/ and nothing to build.

package.json names the tools, and gives each step a short command:

{
"name": "first-mod",
"private": true,
"type": "module",
"scripts": {
"check": "longshot-mod check",
"test": "longshot-mod test",
"lint": "longshot-mod lint",
"pack": "longshot-mod pack"
},
"devDependencies": {
"@longshot/api": "file:../Longshot/modapi/packages/api",
"@longshot/mod-tools": "file:../Longshot/modapi/packages/mod-tools",
"typescript": "7.0.2"
}
}

tsconfig.json sets TypeScript up for the game: the language the game runs (ES2023), ES modules, no DOM and no Node, and TSX for the HUD of step 7. tsc only checks the types (noEmit); the game compiles src/main.tsx itself, with the same JSX runtime and target whatever this file says:

{
"compilerOptions": {
"target": "ES2023", // the language QuickJS-ng runs in the game
"lib": ["ES2023"], // the language alone: no DOM, no Node, as in the game
"module": "NodeNext", // ES modules, imports with their extension ("./format.js")
"moduleDetection": "force", // every file is a module, as the game loads it
"moduleResolution": "NodeNext",
"jsx": "react-jsx", // TSX compiles to calls of longshot/ui's JSX runtime
"jsxImportSource": "longshot/ui",
"types": ["@longshot/api"], // the API's modules: "longshot", "longshot/game"...
"strict": true,
"isolatedModules": true, // each file compiles alone, as the game compiles it
"verbatimModuleSyntax": true, // a type-only import says so (import type)
"noEmit": true // tsc only checks: the game compiles src/
},
// longshot-env.d.ts: written by longshot-mod check (and dev, and types) from mod.json's "requires" and "settings"
"include": ["src", "test", "longshot-env.d.ts"]
}

Then, in first-mod/:

Terminal window
mise use node@26 # once: the mod's mise.toml (or skip it, with a Node 22 or later of your own)
npm install

npm install puts the mod’s own tsc in node_modules (TypeScript 7 is a native compiler: npm installs the one for your OS), and oxc-transform, the npm build of the game’s compiler, which @longshot/mod-tools brings for its fake game. Keep mise.toml with the mod’s sources; leave node_modules/, longshot-env.d.ts and *.lsmod out of version control: they are all made from the rest.

3. The manifest: mod.json

Every mod has a mod.json. Start with this one:

{
"id": "local/first-mod",
"name": "First Mod",
"version": "0.1.0",
"license": "GPL-3.0-or-later",
"api": "0.1",
"runtime": "js",
"entry": "src/main.tsx",
"game": { "builds": ["*"] },
"permissions": ["state.read"],
"requires": ["player.state.life", "player.state.maxLife"]
}
Field What it says
id owner/name. The owner is local until you publish: then it is your account’s name
name, version, license What the Mods tab shows. A version has three parts
api The API version the mod is written for. While the API is 0.x, a mod written for another minor version stays off, and says so
runtime, entry "js", and the module that runs first: its source, src/main.tsx, which the game compiles as it loads it
game.builds The game builds the mod works with: * for any
permissions What the mod needs. state.read reads the game (“Can see what happens in your game”); the player is asked for it when they turn the mod on
requires Parts of the API the mod cannot run without. On a game build that lacks one, the mod stays off and its line says why. Here: Link’s life and its maximum

Every field is in the manifest guide, and every permission in the permission table.

4. A first script

src/main.tsx:

import { update } from "longshot/game";
import player from "longshot/player";
import log from "longshot/log";
let last: number | null = null;
update.on(() => {
const p = player.state();
if (!p) { // no Link: the title screen, loading
last = null;
return;
}
if (p.life !== last) {
log.info(`hearts: ${p.life / 4} / ${p.maxLife / 4}`); // life is in quarter hearts
last = p.life;
}
});

What it does:

  • Imports, not globals. The API is a set of modules: longshot/game (the game and its frame), longshot/player (Link), longshot/log and the others (the module layout). A mod reaches nothing it does not import.
  • The top level runs once, when the mod starts. That is where you subscribe to events. After that, your code runs only in event callbacks, at fixed points of the game’s frame.
  • update fires once per game frame, where the game’s state is read consistently (it needs state.read). on() returns a subscription; off() ends it (events).
  • player.state() is null when there is no Link (the title screen, loading): check it. Its values are the game’s own units, here quarter hearts.
  • p.life is a number, never null, because mod.json requires player.state.life: longshot-mod check (and dev, and types) writes longshot-env.d.ts from requires, and the types drop the null a game build without it would give.

There is nothing to build: the game loads src/main.tsx and compiles it. Check it, if you like (it is optional, and worth it):

Terminal window
npm run check

longshot-mod check reads mod.json, compiles the modules as the game will and links them without running them (so an import of a name a module does not export fails here, not in the game), then runs tsc --noEmit for the types. Your editor shows the same type errors as you type. The game checks no types: a type error it never sees, it runs.

5. Run it in the game

Turn on dev mode. In the game folder (the folder with image.bin in it; the launcher’s Open folder), make a text file longshot_env.txt with this line, or add it to the file that is there:

HOS_MODS_DEV=1

The game reloads a mod in its mods folder when its files change, dev mode or not, without a restart and without leaving the place you are testing (hot reload); dev mode adds the overlay, Shift+F8 to reload and your log.debug lines. Players never need it, and it changes nothing a mod may do.

Start the loop. In first-mod/:

Terminal window
npx longshot-mod dev --game /path/to/the/game/folder

longshot-mod dev watches the mod; at each change it checks its types and copies what a package of it would hold (mod.json, src/, your other files; never tests or node_modules/) into the game’s mods folder, as mods/local/first-mod/. It prints the game’s log lines that name the mod. To skip --game each time, put { "game": "/path/to/the/game/folder" } in a .longshot-mod.json beside mod.json.

Start the game, from the launcher as usual. The game finds the mod at its start, and runs confined (in its sandbox) because a script mod is there. (A game started before the mod was copied finds it too, but its line says to restart the game: scripts only run in the sandbox, which a start sets up.)

  1. Open the menu (F1), go to the Mods tab and select First Mod, under Your mods. A mod found for the first time is off until you have seen what it asks for.
  2. Turn it on. The game asks: “First Mod 0.1.0 asks to: Can see what happens in your game”. Choose Allow.
  3. It starts at once: a script mod with nothing else switches while you play. Load a save.

The terminal shows the mod’s lines:

mod runtime: local/first-mod: hearts: 3 / 3

Now change the script (say, hearts left: ...) and save. longshot-mod dev copies it, and the game compiles and runs the new code within a second; the log says script runtime: local/first-mod: reloading (its files changed). A change to mod.json (its permissions, its settings) takes a restart of the game: longshot-mod dev says so.

F8 opens the mod inspector: what each mod is doing, its time each frame against its budget, its faults and its last log lines. Shift+F8 reloads every folder mod at once.

6. Test it without the game

longshot-mod test runs your mod against the fake game: the same API with no game behind it, where a test sets the game’s state and steps its frames. No game, no game files, any PC. test/first-mod.test.ts:

import type { Tests } from "@longshot/mod-tools";
export default {
"logs the hearts once, then when they change": async (game, assert) => {
game.enterMap("test-field").setPlayer({ life: 12, maxLife: 12 });
await game.frames(3);
game.setPlayer({ life: 10 });
await game.frames(3);
assert.deepEqual(game.logs.map((l) => l.text), ["hearts: 3 / 3", "hearts: 2.5 / 3"]);
},
"does not start without state.read": async (game, assert) => {
game.revoke("state.read");
await assert.rejects(game.start(), /PermissionError/);
},
} satisfies Tests;
Terminal window
npm test
local/first-mod: tests against the fake game, API 0.1
ok - test/first-mod.test.ts: logs the hearts once, then when they change
ok - test/first-mod.test.ts: does not start without state.read
2 passed, 0 failed
  • Nothing is built first: the fake game compiles src/ with oxc-transform, the npm build of the game’s compiler at the same version and with the same options, so a test runs the JavaScript the game would. The test files are compiled by it too. A test checks no types (npm run check does).
  • Each test gets a fresh fake game for the mod, not started yet, and Node’s assert/strict.
  • enterMap puts Link in a map (make the name up: tests, like everything you publish, carry nothing of the game’s files), setPlayer sets his state, frames(n) steps n frames, and game.logs holds every line the mod wrote.
  • A test starts with the permissions of mod.json; revoke takes one away, grant adds one.
  • A callback that throws fails the test, with the mod’s own stack, and a value of the wrong type passed to the API throws ArgumentError, as in the game.

Every call of the fake game is in the author’s guide. The fake game is not a sandbox: your tests are ordinary Node code, so run them on mods you trust.

7. Add a HUD

A mod draws its own UI with components in TSX, from longshot/ui: it is shaped like React (function components, hooks), but it is Longshot’s own, and the game draws it. Add the permission to mod.json:

"permissions": ["state.read", "ui.hud"],

and the HUD to src/main.tsx, after the update listener:

import { Hud, Text, mount, useGame } from "longshot/ui";
function Hearts() {
// read at each `update`; the component renders again only when the value changes
const hearts = useGame(() => {
const p = player.state();
return p ? { life: p.life, maxLife: p.maxLife } : null;
});
if (!hearts)
return <Hud region="top-left" margin={24} />;
const low = hearts.life <= 4; // one heart or less
return (
<Hud region="top-left" margin={24}>
<Text color={low ? "danger" : "ink"} weight={low ? "bold" : "regular"}>
{hearts.life / 4} / {hearts.maxLife / 4} hearts
</Text>
</Hud>
);
}
mount(<Hearts />);
  • mount() shows a surface: a Hud is drawn over the game, in one of its regions. Its tree is kept by the game, and only what changes is sent, so an idle HUD costs nothing.
  • useGame(selector) reads the game at each update and renders the component again only when what it returns changes.
  • Colours are the menu’s style tokens ("ink", "danger", "accent"…), not CSS.

Since mod.json changed, restart the game: it asks for the new permission (“Can draw on your screen over the game”) before the mod starts. In a test, the fake game keeps the UI’s tree, so a test can read it:

"shows the hearts on the HUD": async (game, assert) => {
game.enterMap("test-field").setPlayer({ life: 12, maxLife: 12 });
await game.frames(1); // (the HUD shows from the end of the first frame)
const [hud] = game.ui.hud();
assert.equal(game.ui.text(hud), "3 / 3 hearts");
assert.equal(game.ui.find("3 / 3 hearts").props.color, "ink");
},

Windows, lists, buttons, pictures, labels over the world and the mod’s own settings page are in Mods’ UI.

8. Add a setting

The player should choose when the hearts turn red. A mod declares its settings in mod.json, and the game draws them on the mod’s page of the Mods tab, with the menu’s own rows: there is no menu to write. Add to mod.json:

"settings": [
{ "id": "warn_at", "type": "slider", "label": "Warn at", "min": 1, "max": 10, "step": 1, "default": 1,
"unit": "hearts", "help": "The hearts on the HUD turn red at this many hearts or fewer." }
]

and read it in the HUD with useSetting, which renders the component again when the player changes it:

import { Hud, Text, mount, useGame, useSetting } from "longshot/ui";
function Hearts() {
const hearts = useGame(() => {
const p = player.state();
return p ? { life: p.life, maxLife: p.maxLife } : null;
});
const [warnAt] = useSetting("warn_at"); // in hearts
if (!hearts)
return <Hud region="top-left" margin={24} />;
const low = hearts.life <= warnAt * 4;
// ... as before
}

longshot-mod check (and dev, and types) writes the setting’s type into longshot-env.d.ts: warnAt is a number, and a misspelt id does not compile. Outside the UI, get("warn_at") of longshot/settings reads it, and its changed event hears it change. Settings need no permission: they are the mod’s own.

Restart the game (mod.json changed), then open First Mod in the Mods tab: Warn at is there, under its switch and its permissions. In a test, game.setSetting changes it as the player would:

"turns red at the hearts the player chose": async (game, assert) => {
game.enterMap("test-field").setPlayer({ life: 8, maxLife: 12 });
await game.frames(1);
assert.equal(game.ui.find("2 / 3 hearts").props.color, "ink");
game.setSetting("warn_at", 2);
await game.frames(2);
assert.equal(game.ui.find("2 / 3 hearts").props.color, "danger");
},

Every type of setting (toggles, choices, text, colours, keys), their scopes and how they are kept is in Settings.

9. Lint and pack it

Lint says what the game, the launcher and the portal would say of the mod, without running it: the manifest by the game’s own rules, the permissions the code uses against those mod.json declares, imports of other mods, and any of the game’s own files in the mod.

Terminal window
npm run lint
ok - mod.json: read as the game reads it (local/first-mod 0.1.0)
ok - the permissions the code uses are declared (state.read, ui.hud)
hint: mod.json: the owner "local" is for mods never published: the portal takes a release under your own account's name
lint: no problems

A permission the code uses and mod.json does not declare is an error (the call would throw PermissionError in the game); one declared and never used is a warning, since the player is asked for it.

Pack makes the one file players install:

Terminal window
npm run pack
local/first-mod: packed 2 files into /.../my-mods/first-mod/local.first-mod_0.1.0.lsmod

longshot-mod pack zips mod.json, src/ (what the game compiles and runs) and your other files (pictures, sounds, a README, a LICENSE), checked against the game’s archive rules; tests and the npm and TypeScript files (package.json, tsconfig.json, node_modules/) stay out. A player copies the .lsmod into their mods folder (installing mods).

Publishing waits for the mod portal, which is not built yet. longshot-mod publish --dry-run already lints, packs and writes the release record the portal will take (the tools). Before you publish, change the local owner in the id to your own name.

Without TypeScript

Mods are written in TypeScript, but a mod can also be plain JavaScript: mod.json, a main.js beside it ("entry": "main.js") and tests in test/*.test.js. The game, longshot-mod test and longshot-mod pack take the folder as it is. The author’s guide says how.

Where to go next