{"_id":"@duyquangnvx/cocos-converter","name":"@duyquangnvx/cocos-converter","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@duyquangnvx/cocos-converter","version":"0.1.0","description":"Bidirectional CocosStudio CSD/JSON format converter with Zod schema validation","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"sideEffects":false,"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","typecheck":"tsc --noEmit","lint":"eslint src/","clean":"rimraf dist","example:convert":"tsx example/convert-example.ts","prepublishOnly":"npm run build && npm run test","publish":"npm run build && npm publish --access public"},"dependencies":{"fast-xml-parser":"^4.5.1","zod":"^3.24.1"},"devDependencies":{"@types/node":"^22.10.2","tsup":"^8.3.5","tsx":"^4.19.2","typescript":"^5.7.2","vitest":"^2.1.8","rimraf":"^6.0.1"},"keywords":["cocosstudio","cocos2d","csd","xml","json","converter","parser","zod","schema","validation"],"author":{"name":"duyquangnvx"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/duyquangnvx/cocos-converter.git"},"engines":{"node":">=18.0.0"},"_id":"@duyquangnvx/cocos-converter@0.1.0","gitHead":"78f38e84b011a28d703e2e318d3db7fff60958f3","bugs":{"url":"https://github.com/duyquangnvx/cocos-converter/issues"},"homepage":"https://github.com/duyquangnvx/cocos-converter#readme","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-f3lrRjdeJ6YjVwzLrll2BXo215yGNHcf2qkh6cBk5JO4IQWTxFfjPNeEg+0ENXKw9raoBCUfEMIe3WqFuwsY2g==","shasum":"d003e0f78a5384ff2d178ff9e36fefe21316120b","tarball":"https://registry.npmjs.org/@duyquangnvx/cocos-converter/-/cocos-converter-0.1.0.tgz","fileCount":8,"unpackedSize":914120,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDAXqUVRa68OXiOsnima2c4cdAmVTMw3USnUAkCdEw08gIgZIQk0Ry+nKnI68P8D9tFDs0QDbv4styTmYdQ/kkLvcQ="}]},"_npmUser":{"name":"duyquangnvx","email":"duyquangnvx@gmail.com"},"directories":{},"maintainers":[{"name":"duyquangnvx","email":"duyquangnvx@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cocos-converter_0.1.0_1765985368128_0.34350059360631735"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-17T15:29:28.035Z","0.1.0":"2025-12-17T15:29:28.284Z","modified":"2025-12-17T15:29:28.611Z"},"maintainers":[{"name":"duyquangnvx","email":"duyquangnvx@gmail.com"}],"description":"Bidirectional CocosStudio CSD/JSON format converter with Zod schema validation","homepage":"https://github.com/duyquangnvx/cocos-converter#readme","keywords":["cocosstudio","cocos2d","csd","xml","json","converter","parser","zod","schema","validation"],"repository":{"type":"git","url":"git+https://github.com/duyquangnvx/cocos-converter.git"},"author":{"name":"duyquangnvx"},"bugs":{"url":"https://github.com/duyquangnvx/cocos-converter/issues"},"license":"MIT","readme":"# @assetsnap/cocos-converter\r\n\r\nCocosStudio CSD to JSON bidirectional converter library with Zod schema validation.\r\n\r\n## Features\r\n\r\n- **Bidirectional Conversion**: Convert CSD (XML) to JSON and back\r\n- **Schema Validation**: Full Zod schema validation for CocosStudio 3.x format\r\n- **Type Safety**: Complete TypeScript types with discriminated unions\r\n- **Type Guards**: Runtime type checking utilities for widget types\r\n- **Programmatic Construction**: Build CocosStudio scenes in TypeScript with full IntelliSense\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @assetsnap/cocos-converter\r\n```\r\n\r\n## Quick Start\r\n\r\n### Convert CSD to JSON\r\n\r\n```typescript\r\nimport { convertCsdToJson, stringifyJson } from '@assetsnap/cocos-converter';\r\nimport { readFileSync, writeFileSync } from 'fs';\r\n\r\nconst csdContent = readFileSync('scene.csd', 'utf-8');\r\nconst gameFile = convertCsdToJson(csdContent);\r\n\r\n// Write formatted JSON\r\nwriteFileSync('scene.json', stringifyJson(gameFile));\r\n```\r\n\r\n### Convert JSON to CSD\r\n\r\n```typescript\r\nimport { convertJsonToCsd } from '@assetsnap/cocos-converter';\r\nimport { readFileSync, writeFileSync } from 'fs';\r\n\r\nconst jsonContent = JSON.parse(readFileSync('scene.json', 'utf-8'));\r\nconst csdContent = convertJsonToCsd(jsonContent);\r\n\r\nwriteFileSync('scene.csd', csdContent);\r\n```\r\n\r\n### Validate CocosStudio Data\r\n\r\n```typescript\r\nimport { validateGameFile, safeValidateGameFile } from '@assetsnap/cocos-converter';\r\n\r\n// Throws on invalid data\r\nconst validated = validateGameFile(untrustedData);\r\n\r\n// Returns result object instead of throwing\r\nconst result = safeValidateGameFile(untrustedData);\r\nif (result.success) {\r\n  console.log('Valid:', result.data);\r\n} else {\r\n  console.log('Errors:', result.error.issues);\r\n}\r\n```\r\n\r\n### Programmatic Scene Construction\r\n\r\n```typescript\r\nimport type { GameFile, SpriteObjectData } from '@assetsnap/cocos-converter';\r\nimport { convertJsonToCsd, validateGameFile } from '@assetsnap/cocos-converter';\r\n\r\nconst sprite: SpriteObjectData = {\r\n  ctype: 'SpriteObjectData',\r\n  Name: 'Logo',\r\n  Tag: 1,\r\n  Position: { X: 480, Y: 320 },\r\n  FileData: {\r\n    Type: 'Normal',\r\n    Path: 'images/logo.png',\r\n    Plist: '',\r\n  },\r\n};\r\n\r\nconst gameFile: GameFile = {\r\n  ID: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',\r\n  Version: '3.10.0.0',\r\n  Name: 'MainScene',\r\n  Type: 'Scene',\r\n  Content: {\r\n    Content: {\r\n      ctype: 'GameFileData',\r\n      Animation: {\r\n        Duration: 0,\r\n        Speed: 1,\r\n        Timelines: [],\r\n        ctype: 'TimelineActionData',\r\n      },\r\n      ObjectData: {\r\n        ctype: 'LayerObjectData',\r\n        Name: 'Layer',\r\n        Tag: 1,\r\n        Size: { X: 960, Y: 640 },\r\n        Children: [sprite],\r\n      },\r\n    },\r\n  },\r\n};\r\n\r\n// Validate and export\r\nconst validated = validateGameFile(gameFile);\r\nconst csd = convertJsonToCsd(validated);\r\n```\r\n\r\n### Type Guards\r\n\r\n```typescript\r\nimport { isSpriteData, isButtonData, isContainerType } from '@assetsnap/cocos-converter';\r\nimport type { ObjectData } from '@assetsnap/cocos-converter';\r\n\r\nfunction processWidget(widget: ObjectData) {\r\n  if (isSpriteData(widget)) {\r\n    // TypeScript knows this is SpriteObjectData\r\n    console.log('Sprite path:', widget.FileData?.Path);\r\n  }\r\n\r\n  if (isButtonData(widget)) {\r\n    // TypeScript knows this is ButtonObjectData\r\n    console.log('Button text:', widget.ButtonText);\r\n  }\r\n\r\n  if (isContainerType(widget)) {\r\n    // Process children\r\n    widget.Children?.forEach(processWidget);\r\n  }\r\n}\r\n```\r\n\r\n## API Reference\r\n\r\n### Converters\r\n\r\n- `convertCsdToJson(csdContent, options?)` - Parse CSD XML to GameFile object\r\n- `convertJsonToCsd(gameFile, options?)` - Serialize GameFile to CSD XML\r\n- `stringifyJson(gameFile)` - Format GameFile as pretty JSON string\r\n\r\n### Validators\r\n\r\n- `validateGameFile(data)` - Validate and return GameFile (throws on error)\r\n- `safeValidateGameFile(data)` - Validate and return result object\r\n- `validateObjectData(data)` - Validate single ObjectData node\r\n- `safeValidateObjectData(data)` - Validate ObjectData returning result object\r\n\r\n### Type Guards\r\n\r\n- `isWidgetType(value)` - Check if string is valid WidgetType\r\n- `isSpriteData(data)` - Type guard for SpriteObjectData\r\n- `isButtonData(data)` - Type guard for ButtonObjectData\r\n- `isTextData(data)` - Type guard for TextObjectData\r\n- `isContainerType(data)` - Check if widget can have children\r\n- `getWidgetTypes()` - Get all valid widget type strings\r\n- `getContainerTypes()` - Get all container widget type strings\r\n\r\n### Errors\r\n\r\n- `CocosConverterError` - Base error class\r\n- `CSDParseError` - XML parsing failure\r\n- `ValidationError` - Schema validation failure\r\n- `FileSizeError` - File exceeds max size\r\n\r\n### Options\r\n\r\n```typescript\r\ninterface ConvertOptions {\r\n  skipValidation?: boolean;    // Skip Zod validation (default: false)\r\n  allowUnknownWidgets?: boolean; // Warn instead of fail (default: true)\r\n  maxFileSize?: number;        // Max file size in bytes (default: 10MB)\r\n}\r\n```\r\n\r\n## Supported Widget Types\r\n\r\n- **Containers**: LayerObjectData, GameLayerObjectData, SingleNodeObjectData, PanelObjectData\r\n- **Scrollable**: ScrollViewObjectData, ListViewObjectData, PageViewObjectData\r\n- **Display**: SpriteObjectData, ImageViewObjectData\r\n- **Text**: TextObjectData, TextAtlasObjectData, TextBMFontObjectData\r\n- **Interactive**: ButtonObjectData, CheckBoxObjectData, TextFieldObjectData\r\n- **Progress**: LoadingBarObjectData, SliderObjectData\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md","_rev":"1-371cf9f8f058085f0fb75eae088f2e4e"}