Cocos Nexus Framework

🚀 专业级 Cocos Creator 插件开发框架

Cocos Nexus 是专为 Cocos Creator 设计的现代化插件开发框架，采用装饰器驱动的声明式开发模式，让您使用纯 TypeScript 代码创建强大的编辑器插件，享受类似 Unity Odin Inspector 的开发体验。

✨ 核心特性

🎯 装饰器驱动开发

• 使用 @Plugin 和 @Panel 装饰器快速创建插件
• 零配置开发，自动生成 Cocos Creator 扩展配置
• 完整的 TypeScript 类型支持

⚡ 高性能架构

• 智能文件监听系统，支持防抖和过滤
• 组件缓存和状态驱动渲染
• 内存监控和性能优化
• 插件沙盒和错误隔离

🛡️ 企业级功能

• 完整的依赖注入系统
• 智能错误处理和恢复机制
• 统一主题管理
• 插件生命周期管理

🎨 丰富的UI组件

• 30+ 内置UI组件
• 即时模式GUI系统
• 响应式布局管理
• 自定义主题支持

🔧 完整的工具链

• 自动生成 API 文档
• 配置自动生成器
• 热重载开发支持
• ESLint 和 TypeDoc 集成

🚀 快速开始

安装

npm install @esengine/cocos-nexus

创建你的第一个插件

// src/MyPlugin.ts
import { NexusPlugin, NexusPanel, NexusGUI, Plugin, Panel } from '@esengine/cocos-nexus';

@Panel({
    title: "我的面板",
    width: 600,
    height: 400
})
class MyPanel extends NexusPanel {
    private counter = 0;
    private playerName = "玩家";
    private isEnabled = true;

    public onGUI(): void {
        NexusGUI.Label("欢迎使用 Cocos Nexus Framework!", { fontSize: 18, fontWeight: 'bold' });
        NexusGUI.Separator();

        NexusGUI.BeginVertical({ spacing: 10 });
        
        // 计数器
        NexusGUI.Label(`计数器: ${this.counter}`);
        NexusGUI.BeginHorizontal({ spacing: 10 });
        NexusGUI.Button("增加", () => {
            this.counter++;
            this.forceUpdate();
        });
        NexusGUI.Button("减少", () => {
            this.counter--;
            this.forceUpdate();
        });
        NexusGUI.EndHorizontal();

        // 输入控件
        this.playerName = NexusGUI.TextField("玩家名称", this.playerName, (value) => {
            this.playerName = value;
        });
        
        this.isEnabled = NexusGUI.Toggle("启用功能", this.isEnabled, (value) => {
            this.isEnabled = value;
        });

        NexusGUI.Button("保存设置", () => {
            console.log("设置已保存:", { 
                counter: this.counter,
                playerName: this.playerName, 
                isEnabled: this.isEnabled
            });
        });

        NexusGUI.EndVertical();
    }
}

@Plugin({
    name: "my-plugin",
    version: "1.0.0",
    description: "我的第一个 Nexus 插件",
    panels: [MyPanel]
})
export class MyPlugin extends NexusPlugin {
    public onLoad(): void {
        console.log("插件加载成功");
    }

    public onUnload(): void {
        console.log("插件卸载");
    }
}

配置 Cocos Creator

使用内置的配置生成器：

// scripts/generate-config.ts
import { CocosExtensionGenerator } from '@esengine/cocos-nexus';

const generator = new CocosExtensionGenerator();

generator.generateExtensionConfig({
    name: "my-plugin",
    version: "1.0.0",
    description: "我的插件",
    author: "Your Name",
    main: "./dist/index.js",
    panels: {
        "MyPanel": {
            title: "我的面板",
            width: 600,
            height: 400,
            dockable: true
        }
    },
    menu: [
        {
            path: "扩展/我的插件",
            label: "打开我的面板",
            action: "open-MyPanel"
        }
    ]
});

🎯 核心概念

插件系统

使用 @Plugin 装饰器创建插件：

@Plugin({
    name: "advanced-plugin",
    version: "2.0.0",
    description: "高级插件示例",
    dependencies: ["[email protected]"]
})
export class AdvancedPlugin extends NexusPlugin {
    // 插件生命周期
    public onLoad(): void { }
    public onUnload(): void { }
    public onActivate(): void { }
    public onDeactivate(): void { }
}

面板系统

使用 @Panel 装饰器创建面板：

@Panel({
    title: "数据面板",
    width: 800,
    height: 600,
    dockable: true,
    resizable: true
})
class DataPanel extends NexusPanel {
    // 面板生命周期
    public onShow(): void { }
    public onHide(): void { }
    public onGUI(): void { }
}

依赖注入

使用依赖注入管理服务：

import { Injectable, Inject, Dependencies } from '@esengine/cocos-nexus';

@Injectable()
class DataService {
    public getData(): any[] {
        return [/* 数据 */];
    }
}

class MyPanel extends NexusPanel {
    @Inject(DataService)
    private dataService: DataService;

    public onGUI(): void {
        const data = this.dataService.getData();
        // 使用数据渲染UI
    }
}

错误处理

框架提供智能错误处理：

import { Errors, ErrorLevel } from '@esengine/cocos-nexus';

// 全局错误处理
Errors.setErrorHandler((error, context) => {
    console.error(`[${context.plugin}] ${error.message}`);
    // 自动恢复策略
    if (error.level === ErrorLevel.RECOVERABLE) {
        context.recover();
    }
});

// 插件沙盒
class SafePlugin extends NexusPlugin {
    public onLoad(): void {
        try {
            // 可能出错的代码
            this.initializePlugin();
        } catch (error) {
            Errors.handleError(error, { plugin: this.name });
        }
    }
}

🎨 UI 组件库

基础组件

public onGUI(): void {
    // 文本和标签
    NexusGUI.Label("标题", { fontSize: 16, color: "#333" });
    NexusGUI.TextField("输入框", this.text, (value) => this.text = value);
    
    // 按钮
    NexusGUI.Button("点击我", () => console.log("按钮被点击"));
    
    // 开关和选择
    NexusGUI.Toggle("开关", this.enabled, (value) => this.enabled = value);
    NexusGUI.Slider("滑块", this.value, 0, 100, (value) => this.value = value);
    
    // 布局
    NexusGUI.BeginHorizontal({ spacing: 10 });
    NexusGUI.Button("按钮1", () => {});
    NexusGUI.Button("按钮2", () => {});
    NexusGUI.EndHorizontal();
}

高级组件

// 表格组件
NexusGUI.Table({
    columns: [
        { key: "id", title: "ID", width: 60 },
        { key: "name", title: "名称", width: 200 },
        { key: "status", title: "状态", width: 100 }
    ],
    data: this.tableData,
    onRowClick: (row) => console.log("点击行:", row)
});

// 树形组件
NexusGUI.TreeView({
    data: this.treeData,
    onNodeClick: (node) => console.log("选中节点:", node),
    onNodeExpand: (node) => console.log("展开节点:", node)
});

// 图表组件
NexusGUI.Chart({
    type: 'line',
    data: this.chartData,
    width: 400,
    height: 300
});

🔧 高级功能

智能文件监听

import { AutoWatcher, SmartFileFilter } from '@esengine/cocos-nexus';

// 创建智能文件监听器
const watcher = new AutoWatcher({
    watchPaths: ['src/**/*.ts'],
    filters: [
        SmartFileFilter.createExtensionFilter(['.ts', '.js']),
        SmartFileFilter.createSizeFilter({ max: 1024 * 1024 }) // 1MB以下
    ],
    debounceDelay: 300,
    enableMetrics: true
});

watcher.start();

// 监听文件变化
watcher.on('change', (event) => {
    console.log('文件变化:', event.path);
    // 自动重新加载插件
    this.reloadPlugin();
});

主题管理

import { Theme } from '@esengine/cocos-nexus';

// 设置主题
Theme.setTheme({
    primaryColor: '#007acc',
    backgroundColor: '#f5f5f5',
    textColor: '#333333',
    borderColor: '#dddddd',
    borderRadius: 4,
    spacing: 8
});

// 获取主题变量
const primaryColor = Theme.getVariable('primaryColor');

性能监控

// 自动性能监控
const metrics = AutoWatcher.getMetrics();
console.log('性能指标:', {
    memoryUsage: metrics.memoryUsage,
    processingTime: metrics.processingTime,
    fileCount: metrics.fileCount
});

📚 API 文档

完整的 API 文档可以通过以下方式查看：

# 生成文档
npm run docs

# 启动文档服务器
npm run docs:serve

# 监听文档变化
npm run docs:watch

访问 http://localhost:3000 查看完整的 API 文档。

🔨 开发工具

构建配置

{
  "scripts": {
    "build": "rollup -c",
    "dev": "rollup -c -w",
    "docs": "typedoc",
    "docs:serve": "node scripts/generate-docs.js serve",
    "docs:watch": "node scripts/generate-docs.js watch",
    "lint": "eslint src/**/*.ts"
  }
}

TypeScript 配置

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ES2020",
    "moduleResolution": "node",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

🤝 贡献指南

我们欢迎所有形式的贡献！

1. Fork 项目
2. 创建 功能分支 (git checkout -b feature/amazing-feature)
3. 提交 更改 (git commit -m 'Add some amazing feature')
4. 推送 到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

代码规范

• 使用 TypeScript 5.8.3+
• 遵循 TSDoc 注释标准
• 使用 ESLint 检查代码质量
• 所有公共 API 必须有完整的文档注释

提交规范

# 功能提交
git commit -m "feat: 添加新的UI组件"

# 修复提交
git commit -m "fix: 修复面板布局问题"

# 文档提交
git commit -m "docs: 更新API文档"

📋 版本历史

v2.1.0 (当前版本)

• ✨ 新增智能文件监听系统
• 🔧 完善 Cocos Creator 集成工具
• 📚 完整的 API 文档系统
• 🛡️ 智能错误处理机制
• ⚡ 性能监控和优化

v2.0.0

• 🎯 装饰器驱动开发
• 📦 依赖注入系统
• 🎨 统一主题管理
• 🔌 插件沙盒机制

v1.0.0

• 🚀 初始版本发布
• 🎪 基础UI组件库
• 🔧 即时模式GUI系统

📄 许可证

MIT License - 查看 LICENSE 文件了解详情

💬 社区

• 📧 邮件：[email protected]
• 🐛 问题反馈：GitHub Issues
• 💡 功能建议：GitHub Discussions

Made with ❤️ by ESEngine Team