示例：hello-world

官方最小示例，同时也是 UI 里 Mods → 上传 Mod → 下载示例脚本 下载到的那份模板。

目录

hello-world/
├── manifest.json
└── index.js

manifest.json

{
  "id": "hello-world",
  "name": "Hello World",
  "version": "1.0.0",
  "author": "findor-team",
  "description": "最简单的 Mod 示例",
  "main": "index.js",
  "permissions": []
}

index.js

export function onLoad(ctx) {
    // 加载时调用：只做初始化，不要在这里注册事件（禁用/启用会反复触发）
    ctx.logger.log('Hello World! 我被加载了');
}

export function onEnable(ctx) {
    // 启用时调用：注册事件与命令；把返回的取消函数保存下来，在 onDisable 里调用
    ctx.logger.log('Hello World! 我被启用了');
    ctx.ui.notify('Hello World 已启用', 'success');
}

export function onDisable(ctx) {
    // 禁用时调用：务必清理事件/命令，避免重复注册
    ctx.logger.log('Hello World! 我被禁用了');
}

export function onUnload(ctx) {
    // 卸载时调用：释放一切资源
    ctx.logger.log('Hello World! 我被卸载了');
}

进阶示例：事件 + 命令 + 设置持久化

下面这份把常见能力都用上了，可以当作第二个模板（官方种子 Mod auto-highlight 就是这个结构）。

const DEFAULT_SETTINGS = {
    enabled: true,
    delay: 2000,
};

let settings = { ...DEFAULT_SETTINGS };
let offEnter, offLeave;

export function onLoad(ctx) {
    // 从存储恢复设置
    settings = { ...DEFAULT_SETTINGS, ...ctx.storage.get('settings', {}) };
    ctx.logger.log('设置已加载', settings);
}

export function onEnable(ctx) {
    // 订阅全局事件
    offEnter = ctx.events.on('game:enterBattle', () => {
        if (!settings.enabled) return;
        ctx.logger.log(`进入战斗，${settings.delay}ms 后执行`);
        setTimeout(() => ctx.ui.notify('延迟任务完成', 'success'), settings.delay);
    });
    offLeave = ctx.events.on('game:leaveBattle', () => ctx.logger.log('离开战斗'));

    // 注册聊天命令：/my-mod:toggle 、/my-mod:delay 500
    ctx.commands.register('toggle', (send) => {
        settings.enabled = !settings.enabled;
        ctx.storage.set('settings', settings);
        send(`已${settings.enabled ? '启用' : '禁用'}`);
    }, { args: 0, usage: '/my-mod:toggle' });

    ctx.commands.register('delay', (send, args) => {
        const ms = parseInt(args[0], 10);
        if (isNaN(ms) || ms < 0) return send('用法: /my-mod:delay <毫秒>');
        settings.delay = ms;
        ctx.storage.set('settings', settings);
        send(`延迟已设为 ${ms}ms`);
    }, { args: 1, usage: '/my-mod:delay <毫秒>' });

    ctx.logger.log('已启用');
}

export function onDisable(ctx) {
    offEnter?.();
    offLeave?.();
    ctx.logger.log('已禁用');
}

对应的 manifest 需要声明用到的能力：

{
  "id": "my-mod",
  "name": "我的 Mod",
  "version": "1.0.0",
  "author": "your-name",
  "description": "事件 + 命令 + 设置持久化示例",
  "main": "index.js",
  "tags": ["示例"],
  "permissions": ["events", "commands", "storage", "ui"]
}

运行验证

1. 安装并启用 Mod
2. 控制台应出现 [Mod:hello-world] Hello World! 我被启用了
3. 界面上应弹出 [hello-world] Hello World 已启用
4. 对进阶示例：进入一场战斗应看到日志；聊天框输入 /my-mod:toggle 应有回显

下一步：ctx 全量 API · 常见问题排查