插件系统

插件系统允许你以模块化的方式扩展 ECS Framework 的功能。通过插件，你可以封装特定功能（如网络同步、物理引擎、调试工具等），并在多个项目中复用。

概述

什么是插件

插件是实现了 IPlugin 接口的类，可以在运行时动态安装到框架中。插件可以：

• 注册自定义服务到服务容器
• 添加系统到场景
• 注册自定义组件
• 扩展框架功能

插件的优势

• 模块化: 将功能封装为独立模块，提高代码可维护性
• 可复用: 同一个插件可以在多个项目中使用
• 解耦: 核心框架与扩展功能分离
• 热插拔: 运行时动态安装和卸载插件

快速开始

创建第一个插件

创建一个简单的调试插件：

import { IPlugin, Core, ServiceContainer } from '@esengine/ecs-framework';

class DebugPlugin implements IPlugin {
    readonly name = 'debug-plugin';
    readonly version = '1.0.0';

    install(core: Core, services: ServiceContainer): void {
        console.log('Debug plugin installed');

        // 可以在这里注册服务、添加系统等
    }

    uninstall(): void {
        console.log('Debug plugin uninstalled');
        // 清理资源
    }
}

安装插件

使用 Core.installPlugin() 安装插件：

import { Core } from '@esengine/ecs-framework';

// 初始化Core
Core.create({ debug: true });

// 安装插件
await Core.installPlugin(new DebugPlugin());

// 检查插件是否已安装
if (Core.isPluginInstalled('debug-plugin')) {
    console.log('Debug plugin is running');
}

卸载插件

// 卸载插件
await Core.uninstallPlugin('debug-plugin');

获取插件实例

// 获取已安装的插件
const plugin = Core.getPlugin('debug-plugin');
if (plugin) {
    console.log(`Plugin version: ${plugin.version}`);
}

插件开发

IPlugin 接口

所有插件必须实现 IPlugin 接口：

export interface IPlugin {
    // 插件唯一名称
    readonly name: string;

    // 插件版本（建议遵循semver规范）
    readonly version: string;

    // 依赖的其他插件（可选）
    readonly dependencies?: readonly string[];

    // 安装插件时调用
    install(core: Core, services: ServiceContainer): void | Promise<void>;

    // 卸载插件时调用
    uninstall(): void | Promise<void>;
}

插件生命周期

install 方法

在插件安装时调用，用于初始化插件：

class MyPlugin implements IPlugin {
    readonly name = 'my-plugin';
    readonly version = '1.0.0';

    install(core: Core, services: ServiceContainer): void {
        // 1. 注册服务
        services.registerSingleton(MyService);

        // 2. 访问当前场景
        const scene = core.scene;
        if (scene) {
            // 3. 添加系统
            scene.addSystem(new MySystem());
        }

        // 4. 其他初始化逻辑
        console.log('Plugin initialized');
    }

    uninstall(): void {
        // 清理逻辑
    }
}

uninstall 方法

在插件卸载时调用，用于清理资源：

class MyPlugin implements IPlugin {
    readonly name = 'my-plugin';
    readonly version = '1.0.0';
    private myService?: MyService;

    install(core: Core, services: ServiceContainer): void {
        this.myService = new MyService();
        services.registerInstance(MyService, this.myService);
    }

    uninstall(): void {
        // 清理服务
        if (this.myService) {
            this.myService.dispose();
            this.myService = undefined;
        }

        // 移除事件监听器
        // 释放其他资源
    }
}

异步插件

插件的 install 和 uninstall 方法都支持异步：

class AsyncPlugin implements IPlugin {
    readonly name = 'async-plugin';
    readonly version = '1.0.0';

    async install(core: Core, services: ServiceContainer): Promise<void> {
        // 异步加载资源
        const config = await fetch('/plugin-config.json').then(r => r.json());

        // 使用加载的配置初始化服务
        const service = new MyService(config);
        services.registerInstance(MyService, service);
    }

    async uninstall(): Promise<void> {
        // 异步清理
        await this.saveState();
    }

    private async saveState() {
        // 保存插件状态
    }
}

// 使用
await Core.installPlugin(new AsyncPlugin());

注册服务

插件可以向服务容器注册自己的服务：

import { IService } from '@esengine/ecs-framework';

class NetworkService implements IService {
    connect(url: string) {
        console.log(`Connecting to ${url}`);
    }

    dispose(): void {
        console.log('Network service disposed');
    }
}

class NetworkPlugin implements IPlugin {
    readonly name = 'network-plugin';
    readonly version = '1.0.0';

    install(core: Core, services: ServiceContainer): void {
        // 注册网络服务
        services.registerSingleton(NetworkService);

        // 解析并使用服务
        const network = services.resolve(NetworkService);
        network.connect('ws://localhost:8080');
    }

    uninstall(): void {
        // 服务容器会自动调用服务的dispose方法
    }
}

添加系统

插件可以向场景添加自定义系统：

import { EntitySystem, Matcher } from '@esengine/ecs-framework';

class PhysicsSystem extends EntitySystem {
    constructor() {
        super(Matcher.empty().all(PhysicsBody));
    }

    protected process(entities: readonly Entity[]): void {
        // 物理模拟逻辑
    }
}

class PhysicsPlugin implements IPlugin {
    readonly name = 'physics-plugin';
    readonly version = '1.0.0';
    private physicsSystem?: PhysicsSystem;

    install(core: Core, services: ServiceContainer): void {
        const scene = core.scene;
        if (scene) {
            this.physicsSystem = new PhysicsSystem();
            scene.addSystem(this.physicsSystem);
        }
    }

    uninstall(): void {
        // 移除系统
        if (this.physicsSystem) {
            const scene = Core.scene;
            if (scene) {
                scene.removeSystem(this.physicsSystem);
            }
            this.physicsSystem = undefined;
        }
    }
}

依赖管理

声明依赖

插件可以声明对其他插件的依赖：

class AdvancedPhysicsPlugin implements IPlugin {
    readonly name = 'advanced-physics';
    readonly version = '2.0.0';

    // 声明依赖基础物理插件
    readonly dependencies = ['physics-plugin'] as const;

    install(core: Core, services: ServiceContainer): void {
        // 可以安全地使用physics-plugin提供的服务
        const physicsService = services.resolve(PhysicsService);
        // ...
    }

    uninstall(): void {
        // 清理
    }
}

依赖检查

框架会自动检查依赖关系，如果依赖未满足会抛出错误：

// 错误：physics-plugin 未安装
try {
    await Core.installPlugin(new AdvancedPhysicsPlugin());
} catch (error) {
    console.error(error); // Plugin advanced-physics has unmet dependencies: physics-plugin
}

// 正确：先安装依赖
await Core.installPlugin(new PhysicsPlugin());
await Core.installPlugin(new AdvancedPhysicsPlugin());

卸载顺序

框架会检查依赖关系，防止卸载被其他插件依赖的插件：

await Core.installPlugin(new PhysicsPlugin());
await Core.installPlugin(new AdvancedPhysicsPlugin());

// 错误：physics-plugin 被 advanced-physics 依赖
try {
    await Core.uninstallPlugin('physics-plugin');
} catch (error) {
    console.error(error); // Cannot uninstall plugin physics-plugin: it is required by advanced-physics
}

// 正确：先卸载依赖它的插件
await Core.uninstallPlugin('advanced-physics');
await Core.uninstallPlugin('physics-plugin');

插件管理

通过 Core 管理

Core 类提供了便捷的插件管理方法：

// 安装插件
await Core.installPlugin(myPlugin);

// 卸载插件
await Core.uninstallPlugin('plugin-name');

// 检查插件是否已安装
if (Core.isPluginInstalled('plugin-name')) {
    // ...
}

// 获取插件实例
const plugin = Core.getPlugin('plugin-name');

通过 PluginManager 管理

也可以直接使用 PluginManager 服务：

const pluginManager = Core.services.resolve(PluginManager);

// 获取所有插件
const allPlugins = pluginManager.getAllPlugins();
console.log(`Total plugins: ${allPlugins.length}`);

// 获取插件元数据
const metadata = pluginManager.getMetadata('my-plugin');
if (metadata) {
    console.log(`State: ${metadata.state}`);
    console.log(`Installed at: ${new Date(metadata.installedAt!)}`);
}

// 获取所有插件元数据
const allMetadata = pluginManager.getAllMetadata();
for (const meta of allMetadata) {
    console.log(`${meta.name} v${meta.version} - ${meta.state}`);
}

实用插件示例

网络同步插件

import { IPlugin, IService, Core, ServiceContainer } from '@esengine/ecs-framework';

class NetworkSyncService implements IService {
    private ws?: WebSocket;

    connect(url: string) {
        this.ws = new WebSocket(url);
        this.ws.onmessage = (event) => {
            const data = JSON.parse(event.data);
            this.handleMessage(data);
        };
    }

    private handleMessage(data: any) {
        // 处理网络消息
    }

    dispose(): void {
        if (this.ws) {
            this.ws.close();
            this.ws = undefined;
        }
    }
}

class NetworkSyncPlugin implements IPlugin {
    readonly name = 'network-sync';
    readonly version = '1.0.0';

    install(core: Core, services: ServiceContainer): void {
        // 注册网络服务
        services.registerSingleton(NetworkSyncService);

        // 自动连接
        const network = services.resolve(NetworkSyncService);
        network.connect('ws://localhost:8080');
    }

    uninstall(): void {
        // 服务会自动dispose
    }
}

性能分析插件

class PerformanceAnalysisPlugin implements IPlugin {
    readonly name = 'performance-analysis';
    readonly version = '1.0.0';
    private frameCount = 0;
    private totalTime = 0;

    install(core: Core, services: ServiceContainer): void {
        const monitor = services.resolve(PerformanceMonitor);
        monitor.enable();

        // 定期输出性能报告
        const timer = services.resolve(TimerManager);
        timer.schedule(5.0, true, null, () => {
            this.printReport(monitor);
        });
    }

    uninstall(): void {
        // 清理
    }

    private printReport(monitor: PerformanceMonitor) {
        console.log('=== Performance Report ===');
        console.log(`FPS: ${monitor.getFPS()}`);
        console.log(`Memory: ${monitor.getMemoryUsage()} MB`);
    }
}

最佳实践

命名规范

• 插件名称使用小写字母和连字符：my-awesome-plugin
• 版本号遵循语义化版本规范：1.0.0

class MyPlugin implements IPlugin {
    readonly name = 'my-awesome-plugin';  // 好
    readonly version = '1.0.0';           // 好
}

清理资源

始终在 uninstall 中清理插件创建的所有资源：

class MyPlugin implements IPlugin {
    readonly name = 'my-plugin';
    readonly version = '1.0.0';
    private timerId?: number;
    private listener?: () => void;

    install(core: Core, services: ServiceContainer): void {
        // 添加定时器
        this.timerId = setInterval(() => {
            // ...
        }, 1000);

        // 添加事件监听
        this.listener = () => {};
        window.addEventListener('resize', this.listener);
    }

    uninstall(): void {
        // 清理定时器
        if (this.timerId) {
            clearInterval(this.timerId);
            this.timerId = undefined;
        }

        // 移除事件监听
        if (this.listener) {
            window.removeEventListener('resize', this.listener);
            this.listener = undefined;
        }
    }
}

错误处理

在插件中妥善处理错误，避免影响整个应用：

class MyPlugin implements IPlugin {
    readonly name = 'my-plugin';
    readonly version = '1.0.0';

    async install(core: Core, services: ServiceContainer): Promise<void> {
        try {
            // 可能失败的操作
            await this.loadConfig();
        } catch (error) {
            console.error('Failed to load plugin config:', error);
            throw error; // 重新抛出，让框架知道安装失败
        }
    }

    async uninstall(): Promise<void> {
        try {
            await this.cleanup();
        } catch (error) {
            console.error('Failed to cleanup plugin:', error);
            // 即使清理失败也不应该阻止卸载
        }
    }

    private async loadConfig() {
        // 加载配置
    }

    private async cleanup() {
        // 清理
    }
}

配置化

允许用户配置插件行为：

interface NetworkPluginConfig {
    serverUrl: string;
    autoReconnect: boolean;
    timeout: number;
}

class NetworkPlugin implements IPlugin {
    readonly name = 'network-plugin';
    readonly version = '1.0.0';

    constructor(private config: NetworkPluginConfig) {}

    install(core: Core, services: ServiceContainer): void {
        const network = new NetworkService(this.config);
        services.registerInstance(NetworkService, network);
    }

    uninstall(): void {
        // 清理
    }
}

// 使用
const plugin = new NetworkPlugin({
    serverUrl: 'ws://localhost:8080',
    autoReconnect: true,
    timeout: 5000
});

await Core.installPlugin(plugin);

常见问题

插件安装失败

问题: 插件安装时抛出错误

原因:

• 依赖未满足
• install 方法中有异常
• 服务注册冲突

解决:

1. 检查依赖是否已安装
2. 查看错误日志
3. 确保服务名称不冲突

插件卸载后仍有副作用

问题: 卸载插件后，插件的功能仍在运行

原因: uninstall 方法中未正确清理资源

解决: 确保在 uninstall 中清理：

• 定时器
• 事件监听器
• WebSocket连接
• 系统引用

何时使用插件

适合使用插件:

• 可选功能（调试工具、性能分析）
• 第三方集成（网络库、物理引擎）
• 跨项目复用的功能模块

不适合使用插件:

• 核心游戏逻辑
• 简单的工具类
• 项目特定的功能

相关链接

• 服务容器 - 在插件中使用服务容器
• 系统架构 - 在插件中添加系统
• 快速开始 - Core 初始化和基础使用