coco-to-cp-converter

v1.0.0

Published

6 months ago

COCO编辑器到CP编辑器作品转换器 - 支持自定义控件、变量系统和完整的文件格式转换

0High
0Medium
0Low

youmingenzyme

coco cp-editor converter cpwb visual-programming code-editor widget-converter jsx-to-react msgpack gzip

COCO到CP编辑器作品转换器

一个强大的转换工具，可以将COCO编辑器的作品文件转换为CP编辑器兼容的CPWB格式。支持自定义控件、变量系统、屏幕管理等完整功能转换。

✨ 特性

🔄 完整转换: 支持屏幕、控件、变量、媒体资源等所有组件
🎨 自定义控件: 自动转换COCO自定义控件为CP CCL控件
🌐 浏览器支持: 可在网页端直接使用，无需Node.js环境
📱 JSX转换: 自动将JSX语法转换为React.createElement格式
🔧 类型安全: 完整的TypeScript类型定义
📊 转换报告: 详细的转换统计和错误报告
⚡ 高性能: 优化的压缩和打包算法

🚀 安装

npm install coco-to-cp-converter

📖 使用方法

浏览器端使用

<!DOCTYPE html>
<html>
<head>
    <script src="https://unpkg.com/@msgpack/[email protected]/dist/index.umd.js"></script>
    <script src="https://unpkg.com/[email protected]/dist/index.umd.js"></script>
</head>
<body>
    <input type="file" id="cocoFile" accept=".json">
    <button onclick="convertFile()">转换</button>
    
    <script>
        async function convertFile() {
            const fileInput = document.getElementById('cocoFile');
            const file = fileInput.files[0];
            
            if (!file) {
                alert('请选择COCO作品文件');
                return;
            }
            
            try {
                const result = await CocoToCPConverter.convertFromFile(file, {
                    includeBuiltinEntities: true,
                    convertJSXToReact: true,
                    generateReport: true
                });
                
                if (result.success) {
                    // 下载转换后的CPWB文件
                    const url = URL.createObjectURL(result.cpwbBlob);
                    const a = document.createElement('a');
                    a.href = url;
                    a.download = 'converted_work.cpwb';
                    a.click();
                    
                    // 显示转换报告
                    console.log('转换报告:', result.report);
                } else {
                    alert('转换失败: ' + result.error);
                }
            } catch (error) {
                alert('转换过程中出错: ' + error.message);
            }
        }
    </script>
</body>
</html>

Node.js使用

import { CocoToCPConverter } from 'coco-to-cp-converter';

async function convertCocoWork() {
    try {
        const result = await CocoToCPConverter.convertCocoToCP(
            './input/coco_work.json',
            './output/converted_work.cpwb',
            {
                includeBuiltinEntities: true,
                convertJSXToReact: true,
                generateReport: true,
                outputDir: './temp'
            }
        );
        
        if (result.success) {
            console.log('转换成功!');
            console.log('输出文件:', result.outputPath);
            console.log('报告文件:', result.reportPath);
        } else {
            console.error('转换失败:', result.error);
        }
    } catch (error) {
        console.error('转换过程中出错:', error);
    }
}

convertCocoWork();

ES模块使用

import CocoToCPConverterBrowser from 'coco-to-cp-converter';

// 从JSON数据转换
const cocoData = {
    title: "我的作品",
    version: "1.0.0",
    screens: { /* 屏幕数据 */ },
    globalVariableList: [ /* 变量数据 */ ],
    unsafeExtensionWidgetList: [ /* 自定义控件 */ ]
};

const result = await CocoToCPConverterBrowser.convertCocoToCP(cocoData);

if (result.success) {
    // 处理转换结果
    const blob = result.cpwbBlob;
    const report = result.report;
}

🔧 API 参考

CocoToCPConverterBrowser

浏览器端转换器类，提供静态方法进行转换。

`convertCocoToCP(cocoData, options?)`

转换COCO作品数据到CP格式。

参数:

cocoData: CocoWorkData - COCO作品数据对象
options?: ConversionOptions - 转换选项

返回: Promise<ConversionResult>

`convertFromFile(file, options?)`

从文件转换COCO作品。

参数:

file: File - COCO作品文件
options?: ConversionOptions - 转换选项

返回: Promise<ConversionResult>

类型定义

interface CocoWorkData {
  title?: string;
  version?: string | number;
  screens?: Record<string, any>;
  globalVariableList?: any[];
  globalArrayList?: any[];
  globalObjectList?: any[];
  unsafeExtensionWidgetList?: any[];
  imageFileList?: any[];
  soundFileList?: any[];
  fontFileList?: any[];
  screenIds?: string[];
}

interface ConversionOptions {
  includeBuiltinEntities?: boolean;  // 是否包含内置实体 (默认: true)
  convertJSXToReact?: boolean;       // 是否转换JSX语法 (默认: true)
  generateReport?: boolean;          // 是否生成转换报告 (默认: true)
  validateOutput?: boolean;          // 是否验证输出 (默认: true)
}

interface ConversionResult {
  success: boolean;
  cpwbBlob?: Blob;                   // 转换后的CPWB文件
  report?: ConversionReport;         // 转换报告
  error?: string;                    // 错误信息
}

interface ConversionReport {
  originalTitle: string;
  convertedAt: string;
  statistics: {
    screens: number;
    globalVariables: number;
    customWidgets: number;
    mediaFiles: number;
  };
  warnings: string[];
  errors: string[];
}

🎯 转换功能

支持的转换项目

✅ 屏幕系统: 完整的屏幕布局和配置
✅ 控件转换: 自动转换自定义控件为CCL格式
✅ 变量系统: 全局变量、数组、对象
✅ 媒体资源: 图片、音频、字体文件
✅ 事件系统: 控件事件和交互逻辑
✅ JSX语法: 自动转换为React.createElement
✅ 实体管理: 内置实体和自定义实体
✅ 文件压缩: MessagePack + gzip双重压缩

转换流程

解析COCO数据: 读取和验证COCO作品文件
ID映射生成: 为所有实体生成一致的ID映射
格式转换: 将COCO格式转换为CP兼容格式
代码转换: JSX转换为React.createElement
实体创建: 生成必需的内置实体
文件打包: 压缩并打包为CPWB格式
验证输出: 确保输出文件兼容性

🔍 故障排除

常见问题

Q: 转换后的文件无法在CP编辑器中打开？ A: 确保原始COCO文件格式正确，并启用所有转换选项。

Q: 自定义控件显示异常？ A: 检查JSX语法转换是否启用，确保控件代码兼容React格式。

Q: 变量数据丢失？ A: 验证COCO文件中的变量数据格式，确保包含必要的字段。

Q: 浏览器中使用时出现压缩错误？ A: 确保浏览器支持CompressionStream API，或使用polyfill。

调试模式

启用详细的转换报告来诊断问题：

const result = await CocoToCPConverterBrowser.convertCocoToCP(cocoData, {
    generateReport: true,
    validateOutput: true
});

if (result.report) {
    console.log('转换统计:', result.report.statistics);
    console.log('警告信息:', result.report.warnings);
    console.log('错误信息:', result.report.errors);
}

🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目！

📄 许可证

MIT License - 详见 LICENSE 文件

🔗 相关链接

注意: 此工具仅用于教育和学习目的，请遵守相关平台的使用条款。