kunpo-ec - Cocos Creator 实体配置插件

项目信息

• 商店地址: Cocos Store - 实体组件编辑器
• 支持版本: Cocos Creator 3.7+

🎯 你的游戏开发是否面临这些挑战？

🤔 以下场景是否似曾相识？

✅ 实体泛滥困扰：游戏中存在成百上千的对象或实体，管理维护成为噩梦
✅ 预制体配置地狱：每个预制体都需要手动挂载组件、逐一设置参数，重复劳动让人崩溃
✅ ECS代码重复：每个实体的创建都需要编写代码添加组件，手动设置各种参数，代码冗余严重
✅ 硬编码维护难：通过代码配置实体组件及属性，一旦需要调整就要改代码重新编译
✅ Excel配置混乱：使用Excel表格配置实体参数，数据结构复杂，团队协作困难，版本管理混乱

💡 如果上述任何一种情况让你深有感触…
那么接下来的内容将彻底改变你的开发方式！
准备好告别繁琐的配置流程，拥抱高效的开发体验了吗？ 🚀

项目简介

目标：让实体配置变得简单高效！🚀

kunpo-ec 是一款专为 Cocos Creator 3.7+ 设计的编辑器扩展插件。

旨在解决游戏开发中实体配置管理的核心痛点。通过提供强大的可视化编辑界面和数据驱动的配置方案，帮助开发者快速、准确地配置游戏中的各种实体信息，如角色、道具、技能、怪物等实体配置。

极大的降低程序的工作量。

🎯 核心特性

• 兼容性高：可适用于所有ECS或者EC架构配置（其他使用方式可自行探索）
• 可视化编辑：提供直观的实体编辑器界面，无需在场景中手动配置
• 数据驱动：通过装饰器自动暴露组件属性，实现代码即配置
• 配置分离：支持一键导出 JSON 配置，实现配置与逻辑分离
• 团队协作：程序定义结构，策划独立配置，提升开发效率
• 类型安全：支持丰富的 Cocos Creator 数据类型，确保配置的准确性

为什么要使用此插件？

在标准的 Cocos Creator 开发流程中，当项目实体数量增多、组件和属性变得复杂时，开发者通常会面临各种痛点。本插件通过创新的解决方案，彻底改变了传统的实体配置方式。

📊 传统方式 vs KunpoEC插件 对比

🎯 核心解决方案

1. 集中化管理

• 提供统一的实体编辑面板，所有需要配置的实体及其组件属性一目了然
• 无需在节点树中来回寻找，操作更加直观高效

2. 数据驱动

• 通过在代码中为组件添加装饰器（@ecsclass 和 @ecsprop），即可自动将属性暴露到插件面板中
• 实现了代码即配置，结构清晰，易于维护

3. 配置与场景分离

• 支持一键将所有配置导出为独立的 JSON 文件
• 游戏运行时直接读取 JSON 数据，使配置的归档、版本控制和迁移变得极其简单

4. 提升团队协作

• 程序定义好数据结构后，策划可独立在插件中完成所有数值配置工作
• 分工明确，并行开发，大幅提升开发效率

插件功能说明

3.1 可视化实体编辑器

打开方式：

• 顶部菜单：Kunpo -> 实体编辑器
• 快捷键：Cmd+Shift+N (Mac) / Ctrl+Shift+N (Windows)

核心功能：

• 创建和管理实体：添加新的实体配置或删除不再需要的
• 编辑组件属性：以表单的形式直观地查看和修改所有通过 @ecsprop 暴露的组件属性
• 实时预览：修改后的数据会实时更新，所见即所得

3.2 一键导出配置

打开方式：

• 顶部菜单：扩展 -> Kunpo -> 导出配置
• 快捷键：Cmd+Shift+M (Mac) / Ctrl+Shift+M (Windows)

功能说明：

• 将您在编辑器中配置的所有实体数据，导出为一个 JSON 文件
• 自动刷新 Creator 中的资源，确保配置立即生效

3.3 框架支持与独立使用

本插件可作为通用工具独立使用，不强制绑定任何特定框架。您可以导出 JSON 数据，并在自己的项目框架中进行解析。

同时，为了获得更流畅的开发体验，插件也对以下开源框架提供了良好支持：

• kunpocc-ec: 一种介于 ECS 和 OOP 之间的架构，易于上手
• kunpocc-ecs: 经典的 ECS 架构，性能更优，灵活性更高

支持的数据类型

插件支持丰富的数据类型配置，满足绝大部分开发需求：

🔢 基础数据类型

• string - 字符串类型
• int - 整数类型
• float - 浮点数类型
• boolean - 布尔类型

🎮 Creator 核心类型

• Vec2 - 二维向量
• Vec3 - 三维向量
• Color - 颜色类型
• Size - 尺寸类型

📦 Creator 资源类型

• Node - 节点引用
• Prefab - 预制体资源
• SpriteFrame - 精灵帧资源
• AudioClip - 音频资源
• Animation - 动画资源
• JsonAsset - JSON 资源
• Particle - 粒子资源
• Skeleton - 骨骼资源
• 以及所有 Asset 子类

🔧 高级类型

• Enum - 枚举类型
• Array - 数组类型（支持任意嵌套）
• Object - 对象类型（支持复杂嵌套结构）

快速开始

5.1 安装插件

1. 安装插件到你的项目：{Creator项目目录}/extensions/kunpo-ec/
2. 重启 Cocos Creator，插件将自动加载
3. 在顶部菜单中可以看到 kunpo 选项

5.2 基本使用流程

1. 定义组件结构：使用装饰器定义需要配置的组件和属性
2. 打开编辑器：通过菜单或快捷键打开实体编辑器
3. 配置数据导出路径：在可视化界面中点击导出路径输入框后的放大镜按钮，选择文件夹
4. 配置实体数据：在可视化界面中配置实体属性
5. 导出配置：一键导出 JSON 配置文件
6. 运行时加载：在游戏运行时加载配置数据

5.3 进阶使用流程

• 实体分组：支持将实体按功能或类型进行分组管理
• 双击分组改名：双击分组名称可以快速重命名分组
• 双击实体改名：双击实体名称可以快速重命名实体
• 拖拽实体分组：可以将实体拖拽到对应的分组中进行分类管理

使用示例

6.1 基础属性示例

import { Color, Enum, Size, Vec2, Vec3 } from 'cc';
import { _ecsdecorator } from 'db://kunpo-ec/ECSDecorator';

const { ecsclass, ecsprop } = _ecsdecorator;

/** 基础属性示例 */
@ecsclass("BaseComponent", { describe: "基础组件" })
export class BaseComponent {
    @ecsprop({ type: "int", defaultValue: 0, displayName: "血量" })
    hp: number = 0;

    @ecsprop({ type: 'float', defaultValue: 0, displayName: "最大血量" })
    maxHp: number = 0;

    @ecsprop({ type: 'string', defaultValue: "", displayName: "字符串" })
    string: string = "";

    @ecsprop({ type: 'boolean', defaultValue: false, displayName: "布尔值" })
    bool: boolean = true;
}

6.2 单层复合属性示例

import { _ecsdecorator } from 'db://kunpo-ec/ECSDecorator';

enum HealthType {
    One = 1,
    Two = 2,
    Three = 3
}

@ecsclass("CompositeComponent", { describe: "复合属性组件" })
export class CompositeComponent {
    @ecsprop({ type: "enum", format: Enum(HealthType), defaultValue: HealthType.One, displayName: "枚举" })
    hpeunm: HealthType = HealthType.One;

    @ecsprop({ type: "array", format: "entity", displayName: "单层数组" })
    list: string[] = [];

    @ecsprop({ type: "array", format: "int" })
    arr: number[];

    @ecsprop({ type: "vec2", displayName: "向量2" })
    vec2: Vec2;

    @ecsprop({ type: "vec3", displayName: "向量3" })
    vec3: Vec3;

    @ecsprop({ type: "color", defaultValue: Color.RED, displayName: "颜色" })
    color: Color;

    @ecsprop({ type: "size", displayName: "尺寸" })
    size: Size;
}

6.3 Creator资源属性示例

@ecsclass("AssetComponent", { describe: "资源组件" })
export class AssetComponent {
    // 编辑器中配置的实体 也可以拖拽引用，导出后是实体名
    @ecsprop({ type: "entity", defaultValue: "", displayName: "实体", tips: "实体" })
    entityName: string = "";

    // cc中的资源类型 导出后是资源的uuid
    @ecsprop({ type: "spriteframe", displayName: "精灵帧" })
    spriteFrame: string = "";

    @ecsprop({ type: "asset", displayName: "资源" })
    asset: string = "";

    @ecsprop({ type: "prefab", displayName: "预制体" })
    prefab: string = "";

    @ecsprop({ type: "skeleton", displayName: "骨骼动画" })
    skeleton: string = "";

    @ecsprop({ type: "particle", displayName: "粒子" })
    particle: string = "";

    @ecsprop({ type: "animation", displayName: "动画" })
    animation: string = "";

    @ecsprop({ type: "audio", displayName: "音频" })
    audio: string = "";

    @ecsprop({ type: "jsonAsset", displayName: "json资源" })
    jsonAsset: string = "";
}

注意事项

⚠️ 重要提醒：代码混淆兼容性

本插件使用到了类名和属性名，如果您的游戏上线时会进行代码混淆，请务必注意：

问题说明：

• 开发阶段导出的配置文件使用原始的类名和属性名
• 代码混淆会改变类名和属性名，导致运行时无法正确匹配配置数据

解决方案：

• 后续可能支持抗混淆版本的装饰器
• 或自行实现抗混淆版本的装饰器（装饰器的代码在ECSDecorator.ts中，只有100行左右，可以自行实现）

📝 其他注意事项

• 本插件仅导出数据，数据使用需要自行解析
• 资源类型导出后是资源的 uuid
• 插件支持 Cocos Creator 3.7+ 版本

通过 Kunpo EC 插件，您可以彻底告别繁琐的实体配置流程，享受高效、直观的开发体验。无论是独立开发者还是团队项目，这款插件都能显著提升您的开发效率！