@assetsnap/cocos-converter

CocosStudio CSD to JSON bidirectional converter library with Zod schema validation.

Features

• Bidirectional Conversion: Convert CSD (XML) to JSON and back
• Schema Validation: Full Zod schema validation for CocosStudio 3.x format
• Type Safety: Complete TypeScript types with discriminated unions
• Type Guards: Runtime type checking utilities for widget types
• Programmatic Construction: Build CocosStudio scenes in TypeScript with full IntelliSense

Installation

npm install @assetsnap/cocos-converter

Quick Start

Convert CSD to JSON

import { convertCsdToJson, stringifyJson } from '@assetsnap/cocos-converter';
import { readFileSync, writeFileSync } from 'fs';

const csdContent = readFileSync('scene.csd', 'utf-8');
const gameFile = convertCsdToJson(csdContent);

// Write formatted JSON
writeFileSync('scene.json', stringifyJson(gameFile));

Convert JSON to CSD

import { convertJsonToCsd } from '@assetsnap/cocos-converter';
import { readFileSync, writeFileSync } from 'fs';

const jsonContent = JSON.parse(readFileSync('scene.json', 'utf-8'));
const csdContent = convertJsonToCsd(jsonContent);

writeFileSync('scene.csd', csdContent);

Validate CocosStudio Data

import { validateGameFile, safeValidateGameFile } from '@assetsnap/cocos-converter';

// Throws on invalid data
const validated = validateGameFile(untrustedData);

// Returns result object instead of throwing
const result = safeValidateGameFile(untrustedData);
if (result.success) {
  console.log('Valid:', result.data);
} else {
  console.log('Errors:', result.error.issues);
}

Programmatic Scene Construction

import type { GameFile, SpriteObjectData } from '@assetsnap/cocos-converter';
import { convertJsonToCsd, validateGameFile } from '@assetsnap/cocos-converter';

const sprite: SpriteObjectData = {
  ctype: 'SpriteObjectData',
  Name: 'Logo',
  Tag: 1,
  Position: { X: 480, Y: 320 },
  FileData: {
    Type: 'Normal',
    Path: 'images/logo.png',
    Plist: '',
  },
};

const gameFile: GameFile = {
  ID: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  Version: '3.10.0.0',
  Name: 'MainScene',
  Type: 'Scene',
  Content: {
    Content: {
      ctype: 'GameFileData',
      Animation: {
        Duration: 0,
        Speed: 1,
        Timelines: [],
        ctype: 'TimelineActionData',
      },
      ObjectData: {
        ctype: 'LayerObjectData',
        Name: 'Layer',
        Tag: 1,
        Size: { X: 960, Y: 640 },
        Children: [sprite],
      },
    },
  },
};

// Validate and export
const validated = validateGameFile(gameFile);
const csd = convertJsonToCsd(validated);

Type Guards

import { isSpriteData, isButtonData, isContainerType } from '@assetsnap/cocos-converter';
import type { ObjectData } from '@assetsnap/cocos-converter';

function processWidget(widget: ObjectData) {
  if (isSpriteData(widget)) {
    // TypeScript knows this is SpriteObjectData
    console.log('Sprite path:', widget.FileData?.Path);
  }

  if (isButtonData(widget)) {
    // TypeScript knows this is ButtonObjectData
    console.log('Button text:', widget.ButtonText);
  }

  if (isContainerType(widget)) {
    // Process children
    widget.Children?.forEach(processWidget);
  }
}

API Reference

Converters

• convertCsdToJson(csdContent, options?) - Parse CSD XML to GameFile object
• convertJsonToCsd(gameFile, options?) - Serialize GameFile to CSD XML
• stringifyJson(gameFile) - Format GameFile as pretty JSON string

Validators

• validateGameFile(data) - Validate and return GameFile (throws on error)
• safeValidateGameFile(data) - Validate and return result object
• validateObjectData(data) - Validate single ObjectData node
• safeValidateObjectData(data) - Validate ObjectData returning result object

Type Guards

• isWidgetType(value) - Check if string is valid WidgetType
• isSpriteData(data) - Type guard for SpriteObjectData
• isButtonData(data) - Type guard for ButtonObjectData
• isTextData(data) - Type guard for TextObjectData
• isContainerType(data) - Check if widget can have children
• getWidgetTypes() - Get all valid widget type strings
• getContainerTypes() - Get all container widget type strings

Errors

• CocosConverterError - Base error class
• CSDParseError - XML parsing failure
• ValidationError - Schema validation failure
• FileSizeError - File exceeds max size

Options

interface ConvertOptions {
  skipValidation?: boolean;    // Skip Zod validation (default: false)
  allowUnknownWidgets?: boolean; // Warn instead of fail (default: true)
  maxFileSize?: number;        // Max file size in bytes (default: 10MB)
}

Supported Widget Types

• Containers: LayerObjectData, GameLayerObjectData, SingleNodeObjectData, PanelObjectData
• Scrollable: ScrollViewObjectData, ListViewObjectData, PageViewObjectData
• Display: SpriteObjectData, ImageViewObjectData
• Text: TextObjectData, TextAtlasObjectData, TextBMFontObjectData
• Interactive: ButtonObjectData, CheckBoxObjectData, TextFieldObjectData
• Progress: LoadingBarObjectData, SliderObjectData

License

MIT