File Formats (Inquiry)

[GuyPerfect]

Pardon if I'm blind and can't see something obvious, but I've been unable to find information regarding a few key file types in Don't Starve. To make a good mod, you'd need to make new textues, models, animations, sounds and in some cases maybe even shaders. And I figured since Don't Starve encourages modding, maybe someone can help me out with the file formats.

 

I'll reverse engineer things if need be, but hey, maybe that's not necessary. That's where you come in. (-:

 

The texture file format was pretty easy, and I have that fully documented, and I have partial work on the "build" file, the shader file, the animation file and apparently the audio files are standard-issue FMOD resources. Before I go reinventing the wheel, does anyone have more information about the binary formats for these files?

 

Before you reply, please refrain from suggesting "just use TexTool for this" or "just use such-n-such a utility for that". I know about the utilities out there, but I'm after the actual data formats, so please keep it applicable. (-:

 

I'll be doing a formal write-up of the data formats when I'm done. In the mean time, I'd be more than happy to share what information I do have. Thanks in advance!

[GuyPerfect]

So I wrote a program that uses OpenGL:

 

     

 

Which in turn enabled me to render and save images with fancy transparency and what-not:
 

    

 

So hey, at least the reverse-engineering went well...

 

...

 

And THEN I discovered that Don't Starve processes Spriter animations via a Python script--namely mod_tools/tools/scripts/buildanimation.py--in which I noticed the following:

BUILDVERSION = 6#BUILD format 6# 'BILD'# Version (int)# total symbols;# total frames;# build name (int, string)# num materials#   material texture name (int, string)#for each symbol:#   symbol hash (int)#   num frames (int)#       frame num (int)#       frame duration (int)#       bbox x,y,w,h (floats)#       vb start index (int)#       num verts (int)# num vertices (int)#   x,y,z,u,v,w (all floats)## num hashed strings (int)#   hash (int)#   original string (int, string)ANIMVERSION = 4#ANIM format 4# 'ANIM'# Version (int)# total num element refs (int)# total num frames (int)# total num events (int)# Numanims (int)#   animname (int, string)#   validfacings (byte bit mask) (xxxx dlur)#   rootsymbolhash int#   frame rate (float)#   num frames (int)#       x, y, w, h : (all floats)#       num events(int)#           event hash#       num elements(int)#           symbol hash (int)#           symbol frame (int)#           folder hash (int)#           mat a, b, c, d, tx, ty, tz: (all floats)## num hashed strings (int)#   hash (int)#   original string (int, string)

.

Oh well. Good thing I like hacking and enjoyed every minute of it, eh? (-:

 

Incidentally, the animation's element field "mat" refers to a 2x2 transformation matrix to be processed by the vertex shader. Scaling and rotation of objects is calculated ahead of time so as to boost performance at render-time (presumably, though it certainly made implementation easy). The layout is like this:

 

     sx = Horizontal scale

     sy = Vertical scale

     θ  = Angle of rotation

    

 

To apply that matrix to a 2D point, it's a simple matter of multiplication:

 

    

 

Math wizards may notice that the rotation matrix specifies its elements for a clockwise rotation, whereas the input from Spriter (not to mention the rest of the civilized world) specifies the rotation as counter-clockwise. This isn't a mistake: the game engine flips images vertically when drawing. This means that yes, the output Y coordinate will be inverted. I'd have to double check, but I think this also makes polygons back-facing, though you really wouldn't need to do any culling on this.

 

tx and ty aren't factored into the matrix, likely due to the fact that the object would be unscalable if they were in there. With them split out on their own, a scale can be multiplied with the final X and Y coordinates to change the size of the object.

 

The tz field can be a bit confusing... I mean, it's a 2D image, so why use a Z value? Well, the Z value is used to enforce the z-index reported by Spriter, where objects of lesser z-index appear in front of objects of greater z-index. During conversion to anim.bin, the z-index field is given by the order in which objects appear in the Spriter file (it lists the back-most item first), then a Z translation value is calculated in the range of [-5, 5).

 

Say there are n elements in an animation frame. The value of tz is calculated for each element e (starting at zero) by the expression:

 

      tz = 10 / n * e - 5

 

This means the value of 5 will never actually wind up in tz, but it doesn't really matter.

 

Something to note, though... -5 is the Z translation value assigned to the foremost element in the frame, not the back-most one (negative Z generally moves away from the viewer). Further, the foremost element comes first in the anim.bin file--the reverse order from the data in the Spriter file--meaning things need to be processed starting at the end of the list, which is in turn starating at the back-most element (making tz kind of pointless).

 

Failure to draw back-to-front will cause alpha blending to work incorrectly, even with depth testing configured correctly. I don't suppose it's strictly a necessity for the anim.bin file to list elements in order, but in my testing they've all been that way, and it's like that after compiling a Spriter resoruce.

 

The texture coordinates u, v, and w in the build.bin file correspond with s, t and... well, w isn't used. In fact, W is a clip space scaling component, not a texture coordinate, and appears to be meaningless in the build file (it's always zero). So remember kids, you map textures with ST coordintes, not UV coordinates. (-:

 

Frame duration doesn't appear to have any obvious meaning. It's an integer, and appears to always be 1. I ignored it in my program and animations still work correctly.

[divergence]

I became curious about what's needed for something like a total conversion mod myself which might not get that far anyways since I lack artistic abilities (I tried to get better but several circles later, I am still only able to draw beautiful potatoes...).  Anyways I cheated by googling to see what people has going on thus far .  This was the top result.  I'm curious if you've learned a bunch more and have stuff documented..  I'll go back to googling a bit.