NSGo Game

modding

game/modding 基于 NSGo 的 tsx 运行时加载并运行按能力沙箱隔离的 TSX/JS 游戏模组,提供 mod.json 清单校验、依赖拓扑排序、故障隔离、持久化启停状态以及 "game" 模块 API。

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

模组清单(mod.json)与权限能力

每个模组位于独立目录中,包含 mod.json(ModManifest)和入口脚本(mod.tsx 或 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"
  }
}

权限由 Capability 位标志控制:CapReadState("readState")、CapWriteState("writeState")、CapSpawnEntity("spawnEntity")、CapEmitEvent("emitEvent")、CapUI("ui")、CapAudio("audio")和 CapStorage("storage")。超出授权范围的调用会返回 *PermissionError,不会导致宿主游戏崩溃。

"game" TSX 模块

模组通过导入 "game"(GameModule)挂载固定步长回调、收发事件、生成预制体、读写受控状态、播放音效、访问隔离存储以及挂载 TSX 界面面板。可用 modding.WriteGameAPIDTS("game.d.ts") 为模组作者导出 TypeScript 类型声明。

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");

在 Go 中管理模组生命周期(Manager)

在 NSGo 作用域上创建 Manager,通过 GameBridge 将模组请求接入你的游戏引擎,从目录或 io/fs.FS 发现模组,并在 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() // 校验清单、按依赖拓扑顺序加载、隔离单个模组故障

// 在 game.Loop.Update 中:
mgr.Step(dt)

// 在 NSGo 视图树中渲染模组挂载的 HUD 面板:
hudPanels := mgr.PanelsView("hud")
_ = hudPanels

运行时可通过 Enable、Disable、Load、Unload、Reload、SetGrant、Emit、Call、List、Info 和 Logs 管理单个模组。异常抛错的模组会被标记为 StateFailed,不会影响宿主游戏或其他正常模组。

编辑此页