Editing and Viewing SKEL Files Without Spine Editor

Convert Spine .skel files into .json files for editing with any text editor. Allows modders to experiment with animation and sprite tweaks without using the Spine Editor.

Intro

I've seen people on Steam, reddit, and the Moonlight Dungeon discord asking about making simple edits to animations without buying a Spine Editor license. While working on my own mod, I've found a reasonable way to do this, so I figured it would be useful to share what I've learned. Using a tool made by brachna on github, Spine .skel files can be converted into .json format, which makes them editable with a text editor. I've been able to make simple changes to sprites like shifting or resizing them and moving attachment points for skill fx's.

Update:
MonteePoke has written a guide on how to use this conversion script along with DragonBones to create Darkest Dungeon compatible animation files. If you're planning on doing anything more complex than resizing/repositioning sprites or moving attachment points, I would recommend taking a look at it. You can check out MonteePoke's guide here: https://steamcommunity.com/sharedfiles/filedetails/?id=2200465472

Convert Spine .skel to .json

To convert skeleton files:

1. Install Python 3.0+ from https://www.python.org/downloads/.
   
2. Download the SpineConverter from https://github.com/brachna/SpineConverter2.1.27. You can just use Clone or download -> Download ZIP.
   
3. Unzip the archieve, start a command prompt in the directory, and start Python.
   
4. At the Python prompt, you call the SpineConverter tool as mentioned in the SpineConverter's readme:
   
   

   from spBinaryReader import spBinaryReader
   from spJsonWriter import spJsonWriter
   binaryReader = spBinaryReader()
   jsonWriter = spJsonWriter()
   skeletonData = binaryReader.readSkeletonDataFile( "vestal.sprite.walk.skel" )
   jsonWriter.writeSkeletonDataFile( skeletonData, "vestal.sprite.walk.json" )
   

   
   Replace "vestal.sprite.walk.skel" and "vestal.sprite.walk.json" with the path to the input and ouput files respectively.
   
   
5. You can also convert in the other direction like this:
   
   

   from spJsonReader import spJsonReader
   from spBinaryWriter import spBinaryWriter
   jsonReader = spJsonReader()
   binaryWriter = spBinaryWriter()
   skeletonData = jsonReader.readSkeletonDataFile( "vestal.sprite.walk.json" )
   binaryWriter.writeSkeletonDataFile( skeletonData,  "vestal.sprite.walk.skel" )
   

I've created a helper script to make using the converter library more convenient. Create a new .py file in the same directory as the converter .py files and copy the following code into it:

import sys, os

from spBinaryReader import spBinaryReader
from spJsonReader import spJsonReader
from spBinaryWriter import spBinaryWriter
from spJsonWriter import spJsonWriter

if (len(sys.argv) >= 2):
    fileName = sys.argv[1]

    if (fileName.endswith(".skel")): 
        print("Converting " + fileName.split("\\")[-1] + " into .json.")

        binaryReader = spBinaryReader()
        jsonWriter = spJsonWriter()

        skeletonData = binaryReader.readSkeletonDataFile(fileName)
        jsonWriter.writeSkeletonDataFile(skeletonData, fileName.replace(".skel", ".json"))
    elif (fileName.endswith(".json")):
        print("Converting " + fileName.split("\\")[-1] + " into .skel.")

        jsonReader = spJsonReader()
        binaryWriter = spBinaryWriter()
        
        skeletonData = jsonReader.readSkeletonDataFile(fileName)
        binaryWriter.writeSkeletonDataFile(skeletonData, fileName.replace(".json", ".skel"))
    else:
        print("Invalid file type.")
else:
    print("Required arguments not found.")

You can then drag and drop any .skel or .json file onto this file and it will convert it to the other format, creating the new file in the same directory as the input file. If the output file name already exists, it will overwrite the old file.


Notes about the .json files:

• The outputed .json won't be nicely formated. I recommend using something like Notepad++ with the JSTool plugin to automatically format it.
  
• Darkest Dungeon won't read .json skeleton files, so you'll need to convert them back to .skel before running the game.
  
• You can check out the official documentation for Spine JSON files at http://esotericsoftware.com/spine-json-format for more info on what does what.

Spine SkeletonViewer

The Spine developers, EsotericSoftware, have created a SkeletonViewer tool that can be used to test-view skeletons and animations. It's a nice tool to have while tweaking the animation files since you can test-view them without having to lanuch the game. It also lets you view things like bone attachment points, meshes, and sprite boundaries. You can also play animations saved in the skeleton file.

The problem is they only have the lastest version avaiable for download, which is no longer compatible with Darkest Dungeon's skeleton files. I've managed to build an older version of the viewer (2.1.25) which is compatible with Darkest Dungeon's files. You can get it here: https://drive.google.com/file/d/19gtG6dMBKTFIwQk_WOiKqP10zkPm6lCM/view?usp=sharing.

It requires a Java 8 JRE or newer.

Some notes:

• To view a skeleton, you need to have the .skel/.json, .atlas, and .png files all in the same directory with the same file names (minus the extension). For example, if you're viewing the Vestal's Heal animation, make sure "vestal.sprite.attack_heal.png" is in the same directory as "vestal.sprite.attack_heal.atlas" and "vestal.sprite.attack_heal.skel" since Darkest Dungeon stores the .png seperately.
  
• If the viewer is crashing without any error messages, it's likely because it couldn't find or read the input file.

If you want to try building the viewer from source code yourself, you'll need to have some familiarity with Java development. The steps I took were:

1. Download or clone the Spine Runtimes 2.1.25 repositiory on github at https://github.com/EsotericSoftware/spine-runtimes/tree/2.1.25. Make sure it's version 2.1.25 or it might not work the the Darkest Dungeon files.
   
2. Download the libGDX 1.4.1 release build at https://libgdx.badlogicgames.com/old-site/releases/libgdx-1.4.1.zip. This should be a version that works with Spine 2.1.25.
   
3. Install Java 8 JRE/JDK 64-bit or newer. I used the JDK 14.0.1 x64, but the lastest version should be fine.
   
4. Install Eclipse IDE. I used verion 4.15 (2020-03), but the lastest version should be fine.
   
5. Start Eclipse and do any initial setup needed.
   
6. Extract and import the Spine Runtimes projects into Eclipse. You'll only need to select the "spine-skeletonviewer" and "spine-libgdx" projects to run the skeleton viewer.
   
7. Extract and import the libGDX 1.4.1 files into Eclipse.
   
8. Make sure "spine-skeletonviewer" is referencing the "spine-libgdx" project in its build path.
   
9. Setup "spine-libgdx" to reference "gdx.jar" and "gdx-natives.jar" in libGDX 1.4.1.
   
10. Setup "spine-skeletonviewer" to reference "gdx-backend-lwjgl.jar" and "gdx-backend-lwjgl-natives.jar" in libGDX 1.4.1.
    
11. Run the "spine-skeletonviewer" project.
    
12. If it crashes on startup, it could be trying to open a demo skeleton file which doesn't exist. To fix this, you can open SkeletonViewer.java and comment out the following lines:
    

    loadSkeleton(
    	Gdx.files.internal(Gdx.app.getPreferences("spine-skeletontest").getString("lastFile", "spineboy/spineboy.json")), false);
    

    Then try running it again.

There's probably a better way to set it up that doesn't require using Eclipse, but my Java is rusty and I had trouble setting up the dependencies without Eclipse. If anyone has any advice on this, feel free to message me and I'll update the guide.

[Call_Me_Chanka]

is there any king that would tweak position of only one file for me?

[北极企鹅人]

Hi KaoTheaCow I tried to use this tool to convert a skel file, but once I run the script, something weird happend as the readByte() throw an index error. I tried to debug it and it seems that somehow the self.m_byteArray == len(self.m_byteArray). Very werid cause the readString() actually uses a for loop for length-1, so this shouldn't happen. This was specifically triggered within readSkeletonData(), line 518 of skeletonData["images"] = self.readString().

[Vesper]

Yo I just wanna thank you for this. It helped me so much!

[vexion]

I will, thank you very much.

[KaoTheCow]

Sorry I didn't see your question earlier, but if you run into issues getting the helper script to work, just let me know.

[vexion]

Alright i'll try this way. Thank you.

[MonteePoke]

Just skip to helper script after 5th step, it's much easier to use.
You can also check my guide (link is in intro section of this guide) on how to use SpineConverter with free animation software called DragonBones.

[vexion]

Hello. So ... I'm a total newbie to python and I would like to use this tutorial ,so I don't have to spend 300 bucks in the wind. But I'm already stuck at the third step of "Convert Spine .skel to .json" could you help me understand what I should do?

[KaoTheCow]

Ok thats good. Glad you got it working.

[MonteePoke]

There's no problem now except loosing some info then importing to DB. Exporting translation, rotation, scaling and meshes from DB seems to work fine.