spine-godot breaking change

September 26th, 2022

We released our spine-godot runtimes almost 2 months ago. Since then, we've further improved the runtime based on your feedback and bug reports. Eventually, one unfortunate issue cropped up: Godot plugins and modules may fight over a generic file extension like .json when trying to import it.

This leads to issues when spine-godot is combined with other plugins or modules, like Dialogic. When both spine-godot and Dialogic are loaded into the Godot editor, one of them will be chosen by Godot to import all .json files, preventing the other from importing files with that file extension.

Godot 4.0 has introduced JSON as resource files that helps any new plugins to co-exist happily. However, since we continue to support Godot 3.5 for the foreseeable future, we have to introduce a breaking change.

Starting today, spine-godot will no longer be able to import JSON skeleton files with the .json extension. Instead, JSON skeleton files must use the extension .spine-json. This change will apply if you download the latest pre-built Godot editor from us, or if you rebuild your local Godot editor from the latest spine-godot sources. This applies to both the 4.1 and 4.2-beta branches in the spine-runtimes repository.

If you have an existing Godot project using spine-godot and want to update to the latest version of spine-godot, we are here to help. Here's how you can do that without issues:

  1. Backup your existing project.
  2. Make sure you have the latest Python installed and can run it on the command line by adding its bin/ folder to your PATH environment variable (only needed on Windows).
  3. Download our Python script that will convert your Godot project from using .json skeleton files to .spine-json files.
  4. Run the script on the command line, providing it with the full path to your Godot project directory, e.g. python convert.py c:\myproject

The script will then:

  1. Rename all .json skeleton files to .spine-json and delete the .json.import files. The .import files will be recreated next time you open the project in Godot.
  2. Fix the paths to all external resources of type SpineSkeletonFileResource in all your project's .tscn and .tres files.

Once the script has converted your project, you can open it with the latest Godot editor built from the latest spine-godot sources.

Discuss this post on the Spine forum.