Editing and Viewing SKEL Files Without Spine Editor

Darkest Dungeon®★ 4 · 28 ratings3.9k views86 favorites5 min readby KaoTheCowUpdated Aug 25, 2020View on Steam ↗

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:

Install Python 3.0+ from https://www.python.org/downloads/.
Download the SpineConverter from https://github.com/brachna/SpineConverter2.1.27. You can just use Clone or download -> Download ZIP.
Unzip the archieve, start a command prompt in the directory, and start Python.
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.
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:

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.
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.
Install Java 8 JRE/JDK 64-bit or newer. I used the JDK 14.0.1 x64, but the lastest version should be fine.
Install Eclipse IDE. I used verion 4.15 (2020-03), but the lastest version should be fine.
Start Eclipse and do any initial setup needed.
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.
Extract and import the libGDX 1.4.1 files into Eclipse.
Make sure "spine-skeletonviewer" is referencing the "spine-libgdx" project in its build path.
Setup "spine-libgdx" to reference "gdx.jar" and "gdx-natives.jar" in libGDX 1.4.1.
Setup "spine-skeletonviewer" to reference "gdx-backend-lwjgl.jar" and "gdx-backend-lwjgl-natives.jar" in libGDX 1.4.1.
Run the "spine-skeletonviewer" project.
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.