@esengine/cocos-nexus/README.md

类似Unity Odin Inspector的Cocos Creator插件开发框架 - 用TypeScript完全重新定义插件UI开发体验

# Cocos Nexus Framework

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

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

[![npm version](https://badge.fury.io/js/@esengine%2Fcocos-nexus.svg)](https://badge.fury.io/js/@esengine%2Fcocos-nexus)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8.3-blue.svg)](https://www.typescriptlang.org/)

## ✨ 核心特性

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

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

### 🛡️ 企业级功能
- 完整的依赖注入系统
- 智能错误处理和恢复机制
- 统一主题管理
- 插件生命周期管理

### 🎨 丰富的UI组件
- 30+ 内置UI组件
- 即时模式GUI系统
- 响应式布局管理
- 自定义主题支持

### 🔧 完整的工具链
- 自动生成 API 文档
- 配置自动生成器
- 热重载开发支持
- ESLint 和 TypeDoc 集成

## 🚀 快速开始

### 安装

```bash
npm install @esengine/cocos-nexus
```

### 创建你的第一个插件

```typescript
// 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

使用内置的配置生成器：

```typescript
// 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` 装饰器创建插件：

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

### 面板系统

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

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

### 依赖注入

使用依赖注入管理服务：

```typescript
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
    }
}
```

### 错误处理

框架提供智能错误处理：

```typescript
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 组件库

### 基础组件

```typescript
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();
}
```

### 高级组件

```typescript
// 表格组件
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
});
```

## 🔧 高级功能

### 智能文件监听

```typescript
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();
});
```

### 主题管理

```typescript
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');
```

### 性能监控

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

## 📚 API 文档

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

```bash
# 生成文档
npm run docs

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

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

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

## 🔨 开发工具

### 构建配置

```json
{
  "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 配置

```json
{
  "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 必须有完整的文档注释

### 提交规范

```bash
# 功能提交
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](LICENSE) 文件了解详情

## 💬 社区

- 📧 邮件：support@esengine.com
- 🐛 问题反馈：[GitHub Issues](https://github.com/esengine/cocos-nexus/issues)
- 💡 功能建议：[GitHub Discussions](https://github.com/esengine/cocos-nexus/discussions)

---

**Made with ❤️ by ESEngine Team**