Command-line tool for converting Spine skeleton data between different formats (skel/json) and different versions (3.5/3.6/3.7/3.8/4.0/4.1/4.2).
Command-line tool for converting Spine skeleton data between different formats (skel/json) and different versions (3.5/3.6/3.7/3.8/4.0/4.1/4.2).
A powerful command-line tool for converting Spine skeleton data between different formats and different versions, with automatic version detection and support for multiple Spine runtime versions.
.skel or .json files| 3.5 | 3.6 | 3.7 | 3.8 | 4.0 | 4.1 | 4.2 | |
|---|---|---|---|---|---|---|---|
| JSON Reader | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| JSON Writer | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Binary Reader | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Binary Writer | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
Legend: ✅ Supported | In Development | ❌ Not Supported
# Clone the repository
git clone https://github.com/wang606/SpineSkeletonDataConverter.git
cd SpineSkeletonDataConverter
# Create build directory
mkdir build && cd build
# Configure and build
cmake ..
cmake --build . --config Release…A dedicated Python script for converting Spine 4.x atlas files to a 3.x compatible format.
Features:
.atlas file format, applying the scale property to all relevant metrics.scale property.Usage:
python SpineAtlasDowngrade.py input.atlas output_dirThe repository now also provides a native executable SpineAtlasDowngrade that mirrors the Python script.
Build it via CMake and run:
SpineAtlasDowngrade.exe input.atlas output_dirWhen downgrading, textures are resized using stb; currently the native converter only supports PNG texture pages, so convert other formats in advance.
For large directories of Spine assets, use the bundled helper script tools/SpineConverter.py to drive both SpineSkeletonDataConverter.exe and SpineAtlasDowngrade.exe automatically.
python tools/SpineConverter.py \
[-v x.y.z] \
[--format same|json|skel|other] \
[--remove-curve].json, .skel, and .atlas files, preserving the folder structure in the output directory.-v overrides the target skeleton version (defaults to each file's original version).--format controls output formats for .json/.skel files (same keeps the original format, json/skel force a specific format, and other swaps between the two).--remove-curve forwards to the native converter, stripping animation curves instead of translating them when converting between 3.x and 4.x..atlas files are always downgraded through SpineAtlasDowngrade.exe.The project includes comprehensive testing tools to validate conversion accuracy and data integrity across all supported Spine versions.
For each Spine version, we recommend running three rounds of tests to ensure complete functionality:
Tests JSON reading and writing functionality. The generated .json.json files should be identical to the original .json files.
# Step 1: Convert all JSON files to JSON (tests JSON reader/writer)
$ python ./tools/TestSpineSkeletonDataConverter.py --exe ./build/Debug/SpineSkeletonDataConverter.exe ./data/42 .json .json
# Step 2: Compare all original vs converted JSON files
$ python ./tools/json_diff_all.py ./data/42 .json .json.json
# Step 3: Detailed comparison of specific different files (if any)
$ python ./tools/json_diff.py ./data/42/chibi-stickers/export/chibi-stickers.json ./data/42/chibi-stickers/export/chibi-stickers.json.jsonTests SKEL reading functionality. The generated .skel.json files don't need to be identical to original JSON files, as SKEL and JSON formats have inherent differences.
# Step 1: Convert all SKEL files to JSON (tests SKEL reader)
$ python ./tools/TestSpineSkeletonDataConverter.py --exe ./build/Debug/SpineSkeletonDataConverter.exe ./data/42 .skel .json
# Step 2: Compare results (for reference, differences are expected)
$ python ./tools/json_diff_all.py ./data/42 .json .skel.jsonTests complete functionality: JSON reader, SKEL writer, SKEL reader, and JSON writer. The final .json.skel.json files should be identical to the original .json files.
# Step 1: Convert JSON → SKEL → JSON (tests all 4 functions)
$ python ./tools/TestSpineSkeletonDataConverter.py --exe ./build/Debug/SpineSkeletonDataConverter.exe ./data/42 .json .skel.json
# Step 2: Compare original vs final converted files
$ python ./tools/json_diff_all.py ./data/42 .json .json.skel.json
# Step 3: Detailed analysis of any differences
$ python ./tools/json_diff.py ./data/42/example/export/example.json ./data/42/example/export/example.json.skel.jsonThis project is licensed under the PolyForm Noncommercial License 1.0.0.
You may use, modify, and share this project for noncommercial purposes only, and must retain attribution to the original author.
No open issues yet, or sync has not completed.