daviscook477 / kparser

Conversion tool between Klei animation files and Spriter projects

K-Parser

A bidirectional converter between scml projects and klei animation files.

Please take a look at an updated version by skairunner here. It is a convenient to use standalone program with additional features like interpolating between keyframes

For the direction (klei animation files -> scml project) this tool must be used in tandem with a unity asset extractor. You will have to use the asset extractor to get the game files - specifically you are looking for the atlas file (a single png that contains image data for an animation) and the corresponding (they have the same name) *.build and *.anim file. Then this tool can convert that into an scml project.

For the direction (scml project -> klei animation files) this tool must be used in tandem with an actual full unity install. Use version 2018 because that is the version that Oxygen not included runs on. This is because after this tool creates the klei animation files from your scml project you will need to use unity to create an asset bundle that contains the atlas file (*.png file), the build file (*.build) and the animation file (*.anim).

The conversion from (klei animation files -> scml project) is a lossy conversion because klei animation format is more powerful than spriter (main limitation is skew transforms aren't part of spriter). But the conversion from (scml project -> klei animation file) is correct.

Both directions have been tested and confirmed to work. A more clear tutorial on how to use this tool to create asset mods for Oxygen not included will be made.

Spriter Project Warning - IMPORTANT - MUST READ

Because of limitations of the klei animation format you cannot convert all Spriter projects to klei animations. The requiremets for a Spriter project to be converted to a klei animation are listed here. If you do not exactly follow these requirements in your Spriter project it will not convert to a klei animation properly and you will be sad and I will be unable to help.

• Name all of your image files with an underscore and a number at the end. For example if you have an image blob.png instead name it blob_0.png. The numbering for an individual sprite must start at 0. If you had two different versions of blob you would name them blob_0.png and blob_1.png. If you have separate sprites they each start at 0, for example blob_0.png and head_0.png. This is required for how the tool is currently written.
• You absolutely must enable snapping for your project. The klei animation format expects your keyframes to be in a specific interval. So if you do not enforce that your Spriter project snaps all keyframes to this interval it will be unable to be converted. To turn on snapping you will need to click the triple dots in the timeline panel for opening the settings and then making sure that the Enable Snapping option is checked. Additionally you should make all your animations at 33 ms interval to fit within the game's animation style as that is the interval used by klei's own animations for Oxygen Not Included.
• You absolutely cannot utilize Spriter's feature of setting a pivot point on individual sprites on individual keyframes. What is meant by this is: klei's animation format expects every sprite to have a specific consistent pivot point across the entire animation, i.e. the pivot point of a sprite never changes in a klei animation. As such if you were to change the pivot point of a sprite in your animation (do note that this ability is supported by Spriter which is why you must be so careful to avoid doing it) you simply cannot! This is because there is no way to convert a moving pivot point in Spriter to a consistent pivot in a klei animation. It is not mathematically possible to do so. What you want to do for setting the pivot properly is to set it once for every sprite by setting it in the palette window before dragging any of the sprites into your animation.
• Below is example of modifying the pivot on an individual sprite. This is an example of what you should not do. The red box shows the pivot location after manually moving it on an individual sprite. If you do not move the pivot on the sprite manually it will be a red circle instead of the grey circle.

Usage Guide

Extracting an SCML Project

1. Install uTinyRipper from here.
2. Extract uTinyRipper from the zip file
3. Run uTinyRipper from the exe file
4. With uTinyRipper running open your file system and navigate to your OxygenNotIncluded_Data folder. On Windows it should be located at "C:\Program Files (x86)\Steam\steamapps\common\OxygenNotIncluded\OxygenNotIncludedData". You are looking for "sharedassets0.assets", "sharedassets1.assets", and "sharedassets2.assets"
5. Now you will need to drag and drop "sharedassets0.assets" onto your uTinyRipper application window.
6. Now your uTinyRipper should look like this with a large export button in the middle. When you click this button it will prompt you to find a location to put the exported files in. I would recommend putting it in a new folder called "ONI-Exports" under your user's "Documents" directory.
7. After uTinyRipper has exported "sharedassets0.assets" you may go ahead and export the the other two "sharedassets" files or you can leave that for later and continue with the tutorial for now. You will need to bring up that directory in which your exported the ONI game files.
8. In the "Assets" folder of one of the "sharedassets" directories you will find two folders. These are "TextAsset" and "Texture2D". A Klei animation is composed of three files - 1st an image file that contains the raw picture data for the animation (this is considered a Texture2D), 2nd and 3rd are two binary files called the build and animation files (both are considered a TextAsset).
9. Now we can actually bring together all the files that make up a Klei animation. For this example we will look at the Klei animation called "airconditioner". In the game, this animation is used for the building called the "Thermo Regulator". The files you will need for the "airconditioner" animation are "Texture2D/airconditioner_0.png", "TextAsset/airconditioner_build.bytes", and "TextAsset/airconditioner_anim.bytes".
10. All of the files for the "airconditioner" animation together looks like this.
11. Now download the jar version of K-Parser from the releases section of this github repository. Click here to download it. Put the jar somewhere useful. I recommend putting it near your folder containing the animation files.
12. For this next step you will need to be using at least java 9. Run the jar file with the animation files as the parameters to create the scml file. Note the order of the parameters. They must be in this order: image, build, anim.
13. Now you will have the "scml" project file contained inside the new "scml" directory. Additional the original texture file will have been split into its component pieces.
14. Next open the scml file in Spriter. You can now examine and edit the Klei animation as a spriter project.

Compiling Klei Animation Files

1. Assuming you have K-Parser installed already (if not see step 11 of the scml extraction section of this tutorial) it is simple to run the compiler on the single scml file.
2. Now you will have created your three Klei animation files in the same directory as the scml project.
3. The final step before you can use this new animation you have created in an ONI mod is to copy these three Klei animation files to the "anim/assets" folder of your mod. All animations in that folder will automatically be loaded as Klei animations in ONI that are. All animations have _kanim appended to the end of them when referenced in your mod code. For example if you copied your three Klei animation files to a directory called "anim/assets/mysupercoolanimation" then in game you will refer to that as "mysupercoolanimation_kanim".

kparser's Issues

Support for non animation klei files

For when they use it for non-animated sprites/icons. The current program works if you pass in a file for it to try to use, but it would be nice to be able to not need to specify an animal if there is none.

Please provide license!

Hi!

I'd like to use part of this project for my own (Java-based Oxygen Not Included animated graphics exporter, for the purpose of documenting beta graphics, changes etc.) but, unless I'm missing something, your project has no software license and thus I can't presume you allow derivative work.

Could you please provide license to your source or permit derivative works in some way? Thank you!

Tampered scml files can't convert to kanim?

I was able to convert from kanim to scml no problems at all. I payed attention to the limitations I have using spriter to animate. I tested it with a scml file of a metal meteor that I've opened before but that didn't work. For some reason an scml file of an aquatuner I barely touched worked. I don't know what I did wrong or if it's the code itself, though all I know is that there is something missing a value.

Gas storage to kanim error

I converted gasstorage to scml. If I try to convert back without changes I have an error NullPointerException (top picture). I know, meter_level_0.png absent.
If I add meter_level_0.png then next time i have another NullPointerException (bottom picture). All "meter_level" present. Error on 18th meter_level.

Add. I totally removed meter animation and kparser convert to kanim without error. But gasstorage_build.bytes compiled incorrect. In ONI it makes errors. For clarity I changed this file (replace and rename liquidreservior converted before) - no errors in ONI (but ofcouse incorrect visualisation).