插件开发指南

插件系统允许你扩展调试器的功能，添加自定义的 UI 按钮、监听游戏事件、甚至注入新的功能模块。

插件格式

插件是一个标准的 JavaScript 文件（.js），遵循特定的结构：

javascript

// 插件文件结构
(function() {
    'use strict';

    // 1. 插件元数据
    const pluginMeta = {
        id: 'your-plugin-id',      // 唯一标识（必须）
        name: '插件显示名称',       // 显示名称
        version: '1.0.0',         // 版本号
        author: '作者名',          // 作者
        description: '插件功能描述', // 描述
        category: 'analysis',      // 分类（可选）
        requires: ['1.9.0']        // 依赖的调试器版本（可选）
    };

    // 2. 插件实现
    const plugin = {
        // 生命周期：加载时
        onLoad: function(api) {
            // 初始化代码
        },
        
        // 生命周期：卸载时
        onUnload: function(api) {
            // 清理代码
        }
    };

    // 3. 注册插件
    if (window.TankiDebug && window.TankiDebug.registerPlugin) {
        window.TankiDebug.registerPlugin(pluginMeta, plugin);
    } else {
        window.addEventListener('TankiDebugReady', function() {
            window.TankiDebug.registerPlugin(pluginMeta, plugin);
        });
    }
})();

插件元数据

字段	类型	必需	说明
`id`	string	✅	唯一标识符，不能与其他插件重复
`name`	string	✅	显示名称
`version`	string	✅	版本号
`author`	string	✅	作者名称
`description`	string	✅	功能描述
`category`	string	❌	分类（debug/analysis/enhance/kernel）
`requires`	array	❌	依赖的调试器版本，如 `['1.9.0']`

API 对象

插件 onLoad 和 onUnload 接收一个 api 参数，提供与调试器交互的方法。

`api.log(msg, type)`

输出日志到控制台。

参数：

参数	类型	说明
`msg`	`string`	日志内容
`type`	`string`	日志类型（`info`/`warn`/`error`），默认 `info`

示例：

javascript

api.log('插件已加载');
api.log('出错了', 'error');

`api.showToast(msg)`

显示提示弹窗。

参数：

参数	类型	说明
`msg`	`string`	提示内容

示例：

javascript

api.showToast('操作完成！');

`api.getKernel()`

获取内核探针对象（如果可用）。

返回值： object | null - tankiKeysCache 对象，包含 position、Quaternion、velocity

示例：

javascript

const kernel = api.getKernel();
if (kernel) {
    const x = kernel.position.x;
    const y = kernel.position.y;
    const z = kernel.position.z;
    api.log(`当前位置: (${x}, ${y}, ${z})`);
}

`api.addButton(config)`

在调试器面板中添加自定义按钮。

参数：

参数	类型	说明
`config`	`object`	按钮配置
`config.id`	`string`	按钮唯一标识
`config.text`	`string`	按钮文字
`config.onClick`	`function`	点击回调

示例：

javascript

api.addButton({
    id: 'my-button',
    text: '我的按钮',
    onClick: () => {
        api.showToast('按钮被点击了！');
    }
});

内核探针完整 API

通过 api.getKernel() 获取的对象包含以下属性：

属性	类型	说明
`position.x`	`number`	X 坐标（左右）
`position.y`	`number`	Y 坐标（前后）
`position.z`	`number`	Z 坐标（上下/高度）
`Quaternion.w`	`number`	四元数 W 分量
`Quaternion.x`	`number`	四元数 X 分量
`Quaternion.y`	`number`	四元数 Y 分量
`Quaternion.z`	`number`	四元数 Z 分量
`velocity.x`	`number`	X 方向速度
`velocity.y`	`number`	Y 方向速度
`velocity.z`	`number`	Z 方向速度

示例：

javascript

const kernel = api.getKernel();
if (kernel) {
    // 瞬移到 (100, 200, 50)
    kernel.position.x = 100;
    kernel.position.y = 200;
    kernel.position.z = 50;
    
    // 清空速度防止回弹
    kernel.velocity.x = 0;
    kernel.velocity.y = 0;
    kernel.velocity.z = 0;
}

生命周期

`onLoad(api)`

插件被加载时调用。在此进行初始化：

添加按钮
启动定时器
注册事件监听

`onUnload(api)`

插件被卸载时调用。在此进行清理：

清除定时器
移除事件监听
恢复被修改的数据

完整示例

以下是一个完整的插件示例，演示了所有 API 的用法：

javascript

// 坐标记录器插件
(function() {
    'use strict';

    const pluginMeta = {
        id: 'position-logger',
        name: '坐标记录器',
        version: '1.0.0',
        author: 'YourName',
        description: '记录坦克移动轨迹',
        category: 'analysis',
        requires: ['1.9.0']
    };

    let enabled = false;
    let records = [];
    let timer = null;

    const plugin = {
        onLoad: function(api) {
            api.log('坐标记录器已加载');
            
            api.addButton({
                id: 'start-log',
                text: '开始记录',
                onClick: () => this.startLogging(api)
            });
            
            api.addButton({
                id: 'stop-log',
                text: '停止记录',
                onClick: () => this.stopLogging(api)
            });
        },
        
        onUnload: function(api) {
            this.stopLogging(api);
            api.log('坐标记录器已卸载');
        },
        
        startLogging: function(api) {
            if (enabled) return;
            
            const kernel = api.getKernel();
            if (!kernel) {
                api.showToast('内核未就绪，请先进入战斗');
                return;
            }
            
            enabled = true;
            records = [];
            api.showToast('开始记录坐标');
            
            timer = setInterval(() => {
                const k = api.getKernel();
                if (k && enabled) {
                    records.push({
                        time: Date.now(),
                        x: k.position.x,
                        y: k.position.y,
                        z: k.position.z
                    });
                    api.log(`记录点 ${records.length}: (${k.position.x}, ${k.position.y}, ${k.position.z})`);
                }
            }, 1000);
        },
        
        stopLogging: function(api) {
            if (!enabled) return;
            
            enabled = false;
            if (timer) {
                clearInterval(timer);
                timer = null;
            }
            
            api.showToast(`已记录 ${records.length} 个点`);
            api.log('轨迹记录:', records);
        }
    };

    if (window.TankiDebug && window.TankiDebug.registerPlugin) {
        window.TankiDebug.registerPlugin(pluginMeta, plugin);
    } else {
        window.addEventListener('TankiDebugReady', function() {
            window.TankiDebug.registerPlugin(pluginMeta, plugin);
        });
    }
})();

安装插件

打开调试器面板
点击「插件管理中心」
点击右上角的 📁 图标
选择 .js 插件文件
插件会自动加载并显示在列表中

插件管理

查看已安装插件

在「插件管理中心」可以看到所有已安装的插件列表。

卸载插件

点击插件右侧的 🗑️ 图标 即可卸载。插件代码会从本地存储中删除。

禁用插件

在插件列表中点击开关可以临时禁用插件（如果支持）。

开发建议

1. 使用唯一 ID

插件 ID 必须唯一，避免与其他插件冲突。建议格式：作者-功能名称

javascript

id: 'yourname-position-logger'

2. 清理资源

在 onUnload 中务必清理所有资源：

javascript

onUnload: function(api) {
    if (this.timer) {
        clearInterval(this.timer);
        this.timer = null;
    }
    if (this.observer) {
        this.observer.disconnect();
        this.observer = null;
    }
}

3. 错误处理

使用 try-catch 避免插件崩溃影响调试器：

javascript

startLogging: function(api) {
    try {
        const kernel = api.getKernel();
        if (!kernel) throw new Error('内核未就绪');
        // 正常逻辑
    } catch (e) {
        api.log(e.message, 'error');
        api.showToast('启动失败：' + e.message);
    }
}

4. 避免性能问题

不要在高频回调中执行复杂计算
使用 setInterval 时注意清理
避免在 onLoad 中执行耗时操作

5. 插件分类建议

分类	说明	示例
`debug`	调试辅助	变量监控、日志输出
`analysis`	数据分析	轨迹记录、统计报表
`enhance`	UI 增强	快捷按钮、界面优化
`kernel`	内核扩展	高级游戏对象操作

调试插件

控制台日志

插件日志会带有 [Plugin:插件ID] 前缀：

[Plugin:position-logger] 坐标记录器已加载
[Plugin:position-logger] 开始记录轨迹...

查看插件状态

javascript

// 控制台查看已加载的插件
console.log(TankiDebug.plugins);

手动卸载插件（开发时）

javascript

TankiDebug.unregisterPlugin('your-plugin-id');

发布插件

插件可以：

在技术群分享（公开版）
在核心群分享（涉及内核功能的）
保存在本地自行使用

⚠️ 注意：包含内核探针操作的插件应仅在核心群流通，遵守保密规定。

插件开发指南 ​

插件格式 ​

插件元数据 ​

API 对象 ​

api.log(msg, type) ​

api.showToast(msg) ​

api.getKernel() ​

api.addButton(config) ​

内核探针完整 API ​

生命周期 ​

onLoad(api) ​

onUnload(api) ​

完整示例 ​

安装插件 ​

插件管理 ​

查看已安装插件 ​

卸载插件 ​

禁用插件 ​

开发建议 ​

1. 使用唯一 ID ​

2. 清理资源 ​

3. 错误处理 ​

4. 避免性能问题 ​

5. 插件分类建议 ​

调试插件 ​

控制台日志 ​

查看插件状态 ​

手动卸载插件（开发时） ​

发布插件 ​

相关文档 ​

插件开发指南

插件格式

插件元数据

API 对象

`api.log(msg, type)`

`api.showToast(msg)`

`api.getKernel()`

`api.addButton(config)`

内核探针完整 API

生命周期

`onLoad(api)`

`onUnload(api)`

完整示例

安装插件

插件管理

查看已安装插件

卸载插件

禁用插件

开发建议

1. 使用唯一 ID

2. 清理资源

3. 错误处理

4. 避免性能问题

5. 插件分类建议

调试插件

控制台日志

查看插件状态

手动卸载插件（开发时）

发布插件

相关文档