NSGo Game

modding

game/modding loads and runs capability-sandboxed TSX/JS game mods on top of NSGo's tsx runtime, with mod.json manifest validation, topological dependency resolution, fault isolation, persisted enable/disable state, and a "game" module API.

import "github.com/nsgo-dev/game/packages/game/modding"

Mod manifest (mod.json) and capabilities

Each mod lives in its own directory with a mod.json (ModManifest) and an entry script (mod.tsx or mod.js):

{
  "id": "com.example.boss-rush",
  "name": "Boss Rush",
  "version": "1.2.0",
  "entry": "mod.tsx",
  "gameVersion": ">=0.2.0",
  "capabilities": ["readState", "spawnEntity", "emitEvent", "ui", "storage"],
  "dependencies": {
    "com.example.core-lib": "^1.0.0"
  }
}

Capabilities are bitflags on Capability: CapReadState ("readState"), CapWriteState ("writeState"), CapSpawnEntity ("spawnEntity"), CapEmitEvent ("emitEvent"), CapUI ("ui"), CapAudio ("audio"), and CapStorage ("storage"). Calls outside a mod's granted capabilities fail with *PermissionError without crashing the host.

The "game" TSX module

Mods import "game" (GameModule) to hook fixed simulation steps, emit or listen for events, spawn prefabs, read/write scoped state, play audio, persist per-mod storage, and mount TSX UI panels. Export TypeScript definitions for mod authors with modding.WriteGameAPIDTS("game.d.ts").

import { onStep, onEvent, spawn, getState, mountPanel, log } from "game";

let elapsed = 0;

onStep((dt) => {
  elapsed += dt;
  if (elapsed >= 5) {
    elapsed = 0;
    spawn("slime", 120, 80, { hp: 30 });
  }
});

onEvent("boss_defeated", (payload) => {
  log("Defeated:", payload?.name, "score:", getState("score"));
});

mountPanel("boss-timer", () => <text>Boss Rush Active</text>, "hud");

Managing mod lifecycle in Go (Manager)

Create a Manager on your NSGo scope with a GameBridge connecting mod actions to your game engine, discover mods from disk or io/fs.FS, and step them from game.Loop:

mgr := modding.NewManager(cx, modding.ManagerOptions{
	StorageKey:  "mods",
	GameVersion: "0.2.0",
	Bridge: modding.GameBridge{
		OnSpawn: func(req modding.SpawnRequest) (string, error) {
			return world.SpawnPrefab(req.Prefab, req.X, req.Y, req.Props)
		},
		OnPlaySound: func(req modding.SoundRequest) error {
			return audioMgr.Play(req.Name, req.Volume, req.Rate, req.Loop)
		},
	},
})
defer mgr.Close()

if _, err := mgr.Discover("mods"); err != nil {
	return err
}
_ = mgr.LoadAll() // validates manifests, resolves topological dependency order, isolates faults

// In game.Loop.Update:
mgr.Step(dt)

// Render mod-mounted HUD panels in your NSGo view tree:
hudPanels := mgr.PanelsView("hud")
_ = hudPanels

Control individual mods at runtime with Enable, Disable, Load, Unload, Reload, SetGrant, Emit, Call, List, Info, and Logs. A panicking or throwing mod transitions to StateFailed while the host game and sibling mods keep running.

Edit this page