Candidate for final file format (expanded)

[timpart]

Tweening

Just been looking at tweening in more detail.

I notice that the (timeline) key lets you change the sprite being shown. Is that intended to be a sudden change at that point in time? I presume so, rather than some strange fade in fade out process.

I imagine this kind of thing would be useful if the animator wanted to change the sprites used for the body parts if the body turned from facing front to sideways. I was thinking that the animator might want to specify a start and end point for the movement, then in finer detail during that time period change the sprites used. How easy would that be to do? It would mean having the movement tween cover several key positions for sprite changes.

Fortunately, if I remember correctly, the bezier style linear, quadratic and cubic tweening you are using has the handy property that you can cut it into pieces at arbitrary times and the resulting pieces can all be defined using the same method. Lots of little pieces not so handy for the animator though who might wish to edit the whole tween later. Perhaps some kind of flag saying tween is part of a larger whole? Or a flag to say that during editing a tween should be made to stay smooth with the previous and / or next one? Which might be almost the same thing, not thought it through in detail.

[lucid]

Parent ID

I think I didn't make my question about what does the parent ID contain clear enough. I am perfectly happy with the idea of having parents and swapping them around as needed.

From you previous comments you intend having groups as well as bones. They're two different types I think as bones act a bit differently to groups, though groups might be a super type of bones.

Suppose a sprite has a parent. You want to put its ID into an attribute. Bones have IDs, groups will have IDs too. If bones and groups have separate ID sequences then when a sprite refers to a parent ID , that is ambiguous as we don't know if a bone or a group is intended.

I would suggest that the way round this is to make bones and groups have a common ID sequence.

I see what you're saying. My fault for being unclear in thoughts I've had and revisions made to those plans in the intervening time, and since we've been having this review. I think bones and entity's combined should be sufficient to cover both needs, but having bones be a subtype of some hierarchical object or 'group' sounds good. since it's basically a group that it's own spatial data

Supertype

As I mentioned before I would go further than just a common sequence. Create a super type "object" that has sub types of sprite, bone, group, collision box etc etc. Then rather than specifying different tags for sprite, bone, group, collsion box within mainline key with virtually identical attributes, just have an "object" tag which refers to the actual thing it is. That makes the format more flexible for adding things in the future. (A few sub types like axis aligned collision boxes can't be rotated, and action points have no change if rotated since they are points.)

All objects would have a common ID sequentce, and the parent of an object would be another object.

You have partly gone down this route already by making both ref bone and ref sprite point to a timeline. So timeline is what happens to an object over time. Instead you could have had a sprite-timeline and a bone-timeline. (I'm not suggesting that you do.)

I think the supertype thing is a good idea, and does make for more simple expansion, as well as greatly simplifying the format definition. What if instead of //, there was just

Sprite vs Timeline Key

I suggested that these two are the same concept. You pointed out that you have put a time on Timeline Key but not Sprite.

As a counter argument I would suggest that the time attribute is something redundant (but very useful) that you have put on the Timeline Key. If you were to get rid of it (I'm not suggesting you do) you could still find out what time the key happened, by following the link to the mainline key, in the same way that a sprite knows what time it happened by looking at the mainline key it is contained in. Equally you could put an unneeded attribute of time onto the sprite.

Tim

The time attribute is not redundant for the timeline keys, as they do not have to correspond with each mainline key.

as you can see not every persistent object(object with it's own timeline) has to have a keyframe for each mainline key. The mainline keys have universal values, such as zorder (you can't change the zorder for one object, and disregard the others) and parentage for bones. Assuming the red line is the current time: in the mainline key 1, references to timeline 0 would specify the redundant helper 'key' value at 1 for timeline 0, and 0 for timeline 1 and 2. This is to avoid having to step through each key, and check the time value until you find the current key. But the time aspect is still important. If we want tweening, not forcing every keyframe to key every tweenable object is absolutely essential for animators to be able to do their job well, and without frustration.

Tweening

Just been looking at tweening in more detail.

I notice that the (timeline) key lets you change the sprite being shown. Is that intended to be a sudden change at that point in time? I presume so, rather than some strange fade in fade out process.

I imagine this kind of thing would be useful if the animator wanted to change the sprites used for the body parts if the body turned from facing front to sideways. I was thinking that the animator might want to specify a start and end point for the movement, then in finer detail during that time period change the sprites used. How easy would that be to do? It would mean having the movement tween cover several key positions for sprite changes.

Fortunately, if I remember correctly, the bezier style linear, quadratic and cubic tweening you are using has the handy property that you can cut it into pieces at arbitrary times and the resulting pieces can all be defined using the same method. Lots of little pieces not so handy for the animator though who might wish to edit the whole tween later. Perhaps some kind of flag saying tween is part of a larger whole? Or a flag to say that during editing a tween should be made to stay smooth with the previous and / or next one? Which might be almost the same thing, not thought it through in detail.

Actually, I think entities will hand this problem well, as well as shortcut it, and automate it as well. See 'subanimations' in that previous linked procedural.pdf. I'll reexplain it here as well, when I upload the rest of the file format.

[cyberchris]

I have one thought about the image size or image scale property.

I am developing my games for different plattforms.

For me it would be great, if the artist could create the animations once with the big size images and then scale all images at once to a smaller size and store it in a different folder for the smartphone variant of the game.

If the spriter format stores the image size in pixel, he could just exchange the images and everything looks still ok and would be stretched accordingly.

What do the other think? Would releative or absolut values for image width or scaleX be better?

Bye,

Chris

[lucid]

Hi everyone. We'll have another file format review soon, with the remaining features integrating all the ideas we've discussed so far, and this will be the complete file format. We'll still review the format further before it's final, but we'll be reviewing the format in it's entirety. As soon as we mark it as final, developers can begin implementation so by the time Spriter has each feature, the implementation can already be complete aside from testing.

I'm in the middle of building Spriter's new ui, so it may be a few days before I post the rest of the file format.

Also, just a few thoughts. I think it would be useful to have 'license' included in the meta-data, so people can release free for non-commercial use characters, or watermarked SCML examples of their commercial work, with a standardized method of presenting the licensing information to the user.

On that note, I'm currently researching different licenses for SCML itself. I know many people are passionate about licensing and or may have specific needs we may not have anticipated, so I think it's a good idea to get everyone involved in the process. What we want is for developers to be free to use implementations of the format in their games/editors/api's/plugins/etc for free or commercial use without need for attribution. We want to maintain control and ownership of the format, and we don't want anyone(including us) to be able to sell the format description itself, or any derivative of it. The format description should be able to be redistributed freely as long as it comes with the license information/authorship/etc, and only in unaltered form. Developers can of course alter their implementation for their own purposes, but at least until SCML establishes itself firmly we want to avoid fragmentation by allowing several flavors of SCML floating around.

And lastly, it seems 'y' increases as you move upward, 'angle' represented in counterclockwise degrees is the clear winner. And just to make sure we're on the same page here, an arrow pointing to 0 degrees will be pointing up, down, left, or right?

edit:

...

you should be able to get the same result by multiplying everything by the sizeratio I believe. So if the new images are half the size of the one's in the spriter file, you would just multiply all the x and y values *0.5, and use the current xratio/yratio with no changes. The benefit of using xscale is when you do character maps and other custom image replacement, you multiply the new files' heights and widths by the same ratio. If one choice for your character's head was wearing a helmet with a long feather at the top, you wouldn't want the height squished down to the height of the original head. By using ratios you solve this problem, while still allowing each part to be stretched and squashed.

[mrwonko]

And just to make sure we're on the same page here, an arrow pointing to 0 degrees will be pointing up, down, left, or right?

Does it make any difference?

[lucid]

And just to make sure we're on the same page here, an arrow pointing to 0 degrees will be pointing up, down, left, or right?

Does it make any difference?

I'm sure some have their preference. It will look the same no matter what, but if 0 degrees is pointing to the right on your platform of choice, and you want to spawn a fireball in the direction the arm is facing, it's convenient to have that value match up instead of having to do -90 every time. My choice was different than the majority for clockwise and y up/down, so I'd prefer to go with the majority again. Seems like a minor detail, but if it makes it more convenient for 75% of developers, we may as well reach a consensus on that as well.

[mrwonko]

It will look the same no matter what, but if 0 degrees is pointing to the right on your platform of choice, and you want to spawn a fireball in the direction the arm is facing, it's convenient to have that value match up instead of having to do -90 every time.

I doubt anyone uses polar coordinates for their objects... It'd be more like rotationMatrix(degrees) * vector(1, 0). Also, doesn't the arm's rotation in degrees depend on its initial rotation as defined by the artist?

As far as I'm concerned, any rotation is relative to some initial position, there's no absolute direction it describes. That said when I hear 0° I usually think "X-Axis rotated 0 degrees", i.e. right/east.

[Thinksquirrel]

I usually think of 0 degrees as oriented to the original image. So if the arrow is pointing right in the image, 0 degrees will be pointing right, if it is pointing up, 0 degrees will have it pointing up.

Eager to see the final file format - I have a few more comments but I want to hold off on them until everything is seen in its entirety.

Note: The following only applies if say, a developer has mod support for their game, and uses a modified version of the SCML specification, and would like to publish that modified specification to their community. If they are using the default SCML specification, they could just direct users to the official SCML spec and won't need to worry about any licensing issues. I'm pretty sure this is the route most developers would take. Also a disclaimer, I am not an attorney so I may be incorrect about some of this, and it obviously depends on the licenses in question.

About SCML licensing - I'm not exactly sure which license will fit you best. You may want to look into a documentation license.

Also, keep in mind you may want to make sure the license you choose is compatible with both commercial licenses, and strict copyleft licenses so that it can be integrated in both fully open source documentation, and commercially licensed documentation.

Your ideal license has restrictions on its distribution - it doesn't allow anyone to sell an SCML spec. That makes it incompatible with strict copyleft. Thus, anyone with open-source documentation may run into issues. They will likely need to have the documentation of their SCML specification separate from the rest of their documentation, and may run into other problems.

On the commercial side, they would need to take extra care to not include the specification within their software itself. For example, if someone includes the documentation of the SCML format (the version specific for their game) within their manual under "Modding ", and package it and sell it with their game, that is technically a license violation. If you want to restrict the sale of the specification, you need to make it clear that you want to restrict the sale of the specification (and derivatives) under the purposes of being a specification, and not packaged with a product - something fairly hard to do.

I think that in this case, having a tool like Spriter and a central body already in control over the main SCML format will already help stop fragmentation. It will also keep other parties from trying to monetize the SCML file spec itself - they could try, but would be very unlikely to succeed with a free version of the specification available from you guys.

[Pnikosis]

Hi guys, first of all, this is my first message, so hello and nice to meet you all.

I know I'm late in this discussion but I'd love to have an additional feature in the format, sorry if this has been covered before (I made a search, but didn't find anything).

Having a custom property, or even better: an array of custom properties. Just with two fields, 'name' and 'value'. In my current game, where I implemented my own skeleton based animation system, some bones were "attached" to physical objects, and some other bones weren't, so I'm able to switch from an animated character to a ragdoll quickly (just create a physical 'bone' attached to its parent and let the physics engine do the rest). So in this case for example, if I want to port my poorly programmed animation system to Spriter, a custom property for each entity/bone like "isInRagdoll" would be quite useful.

Just my 2c :)

[jmcmorris]

I have not been keeping up with this too much but I did want to add in something. The SCML should contain a bool for animation looping. I was just working on my engine and found that I have to add in additional logic to be able to turn off looping for animations instead of just reading it from the SCML.

[timpart]

Been thinking a bit more about tweening, and realised that the only ways a sprite can move between two key frames are a straight line or a rotation (or some combination of these, possibly influenced by the parent moving too). Is there any intention in the future to have a curved movement path beween the two keys? If so it might be best to qualify c1, c2 and other related bits to make it clear they apply to the time "curve" and not a physical path to move along. (time_c1 etc) Or perhaps even split them out into a contained object (but that might make parsing a little trickier).

[Fabryz]

I still hope about classic JSON format instead of XML.

[bluepeak]

Eventually spriter will suport skeletal animation with quad deformation, so in some form per-vertex data will be needed. It might get complicated, because one bone may influence multiple vertices on multiple sprites. I'm not sure if the current structure of the file format will be able to accomodate such data, when the feature is ready?

Also, I'd like to second the JSON file format feature request. JSON parsers are generally significantly faster than XML parsers. And these files will have a lot of data, and being able to parse them during runtime would be nice.

[lucid]

Having a custom property, or even better: an array of custom properties. Just with two fields, 'name' and 'value'. .

hi pnikosis. yes, I haven't released the the full filespec yet, but this is planned for each most things in the file. the file itself can have any number of name/value pairs, the character can have any amount of pairs, each animation, each key, each sprite, etc. Also anything that can have a name/value pair, will also be able to have any number of tags, which are just a single name value, as opposed to a pair

I have not been keeping up with this too much but I did want to add in something. The SCML should contain a bool for animation looping. I was just working on my engine and found that I have to add in additional logic to be able to turn off looping for animations instead of just reading it from the SCML.

yes. thanks for pointing that out.

Been thinking a bit more about tweening, and realised that the only ways a sprite can move between two key frames are a straight line or a rotation (or some combination of these, possibly influenced by the parent moving too). Is there any intention in the future to have a curved movement path beween the two keys? If so it might be best to qualify c1, c2 and other related bits to make it clear they apply to the time "curve" and not a physical path to move along. (time_c1 etc) Or perhaps even split them out into a contained object (but that might make parsing a little trickier).

right. I'll take that into consideration for the next format release.

I still hope about classic JSON format instead of XML.

I'd like to second the JSON file format feature request.

It's possible in the future, but in the short term, we want one single format, and most are happy with XML. In the meantime it's easy to convert xml to json. there are tons of free converters online.

Eventually spriter will suport skeletal animation with quad deformation, so in some form per-vertex data will be needed. It might get complicated, because one bone may influence multiple vertices on multiple sprites. I'm not sure if the current structure of the file format will be able to accomodate such data, when the feature is ready?

the format is fairly flexible, even internally in Spriter. I can think of a few ways to add a new type of deformable sprites without having to changes what's there. It'd just be a matter of working out the specifics.

...

thanks for the info Thinksquirrel, and sorry for the delay with the full spec. learning a few things from implementing the internals of the next version of Spriter. Will release the full spec shortly before the release of the next version.

[NateS]

Hi, I'm Nate, co-author of libgdx. I've been building a skeletal animation framework lately. I'm not building tools to build animations, etc. I am building the framework to load skeletons and skins and run animations. I've built tools so Softimage can be used to design skeletons, skins, and animations. Some day it would be nice to have a loader for the Spriter format, which brings me to this thread. A couple notes on Spriter's file format with general ramblings mixed in...

* IMO, skeletal animation should be in from the start. It will affect the file format, how you do animations, etc.

* cx1 and cx2 using 0 to 1 is good, but not cy1, cy2. Imagine frame1's value is 0 and frame2's value is 0, but the bezier interpolation is a bell curve. How do you get useful values from this curve? Probably you plan to use the y value on the bezier curve to scale the difference from frame1 to frame2, but in this scenario frame1 and frame2 are the same, so this interpolation doesn't have any affect. It is more powerful to plot cy1 and cy2 in the value space, probably relative to frame1 and frame2's values. Now the bezier curve knows the scale and the numbers are more useful. Otherwise you force animators to use extra keyframes.

* Less is more. I would only bother supporting linear and bezier interpolations. Maybe stepped (instant).

* It seems all keyframes have all properties? This limits animators, requiring many more keyframes. It makes some animations difficult, as it can be hard to insert a keyframe in the middle of a rotation when fancy interpolation is used. It would be more powerful to animate x, y, scalex, scaley, rotation, etc separately. If this is how it works by omitting properties from keyframes, it would make parsing the format easier to list the properties separately. Eg, {bone:{rot:[{time:123,value:45},{time:456,value:90}}],x:[{time:123,value:10}]}. This is how applications need to load the data to apply animations, so the file format should make it as easy as possible.

* Not sure why elements have IDs? The editor shouldn't affect the file format. Ideally the number of references to objects elsewhere in the file is kept to a minimum.

* JSON > XML. :) JSON doesn't have unnecessary features, is easier to read, is smaller, is easier to parse, and libraries that parse it are smaller.

* Here is how I organize things: I have a "skeleton", which is the bone positions and each bone has any number of "slots". The slots are ordered to define the drawing order. I have a "skin", which is the images and their offset position, scale, rotation for each slot they can go in. I have a "model" (in code only) which has a skeleton and manages state, such as what images are in what slot. Programmers tell the model what slots have what images, and the model draws the images in the right order at the bone locations. I have an "animation", which has keyframes for bones (for each property) and slots (set image, clear image, color). The animation can pose the skeleton of a model. If it helps, my file format looks like this:

http://pastebin.com/raw.php?i=bsLbscqf

* It seems lots of features are getting packed into the file format (reparent bones, etc). I have a feeling that with so many libs that need to implement running animations built with Spriter, many libs will only have a partial implementation. Eg, my implementation is not based on Spriter, but it is a fully capable 2D skeletal framework. I'm probably not going to add some features Spriter supports, but Spriter could still be useful for building animations for my framework. Maybe Spriter could toggle features based on compatibility with the target library (eg, disallow reparenting).

[Mike at BrashMonkey]

Hi NateS,

Thanks so much for the detailed and really well thought-out post! I'm just the artist of the team but I can assure you your suggestions will be carefully considered.

Obviously our goal for finalizing this default data format for Spriter 1.0 is to make it accessible, understandable, and comfortable to work with for the majority of users. It's a very strong possibility that some day Spriter will export to several different formats, or at the very least there will be readily available tools to convert from this default format to others hand-tailored to specific platforms.

Edgar and I had already discussed the likelihood of settings within Spriter to limit features and change which data is exported..this is also highly likely in the long run.

Flexibility is a huge part of our philosophy for Spriter, so we are thrilled to hear it could be useful for creating animations for your bone animation system.

cheers,

Mike@BrashMonkey

[timpart]

* cx1 and cx2 using 0 to 1 is good, but not cy1, cy2. Imagine frame1's value is 0 and frame2's value is 0, but the bezier interpolation is a bell curve. How do you get useful values from this curve? Probably you plan to use the y value on the bezier curve to scale the difference from frame1 to frame2, but in this scenario frame1 and frame2 are the same, so this interpolation doesn't have any affect. It is more powerful to plot cy1 and cy2 in the value space, probably relative to frame1 and frame2's values. Now the bezier curve knows the scale and the numbers are more useful. Otherwise you force animators to use extra keyframes.

Hi Nate, The c1, c2 confused me too. They relate to the velocity curve the speed at which movement takes place, not any physical movement in space. They are just two values not an (x,y,) pair. In your example moving from 0 to 0 can take place at any speed profile since it doesn't move at all. I do appreciate your point though that for actual movements, getting the velocities to join up at each end is tricky if the amount moved is different between different key frames.

As far as I can tell you can only move a sprite position in a linear manner between two keyframes. (Or change a rotation relative to something else in a linear manner.) There are no bezier controlled movements between keyframes in Spriter.

Regards,

Tim

[NateS]

Hi Nate, The c1, c2 confused me too. They relate to the velocity curve the speed at which movement takes place, not any physical movement in space. They are just two values not an (x,y,) pair. In your example moving from 0 to 0 can take place at any speed profile since it doesn't move at all. I do appreciate your point though that for actual movements, getting the velocities to join up at each end is tricky if the amount moved is different between different key frames.

As far as I can tell you can only move a sprite position in a linear manner between two keyframes. (Or change a rotation relative to something else in a linear manner.) There are no bezier controlled movements between keyframes in Spriter.

I guess I still don't understand how c1 and c2 are used. I have a feeling it doesn't matter, because the best thing to do is support linear with no values or bezier with 4 values: cx1, cy1, cx2, cy2. :) Animation with only linear would be a huge inconvenience.

[timpart]

Hi Nate, The c1, c2 confused me too. They relate to the velocity curve the speed at which movement takes place, not any physical movement in space. They are just two values not an (x,y,) pair. In your example moving from 0 to 0 can take place at any speed profile since it doesn't move at all. I do appreciate your point though that for actual movements, getting the velocities to join up at each end is tricky if the amount moved is different between different key frames.

As far as I can tell you can only move a sprite position in a linear manner between two keyframes. (Or change a rotation relative to something else in a linear manner.) There are no bezier controlled movements between keyframes in Spriter.

I guess I still don't understand how c1 and c2 are used. I have a feeling it doesn't matter, because the best thing to do is support linear with no values or bezier with 4 values: cx1, cy1, cx2, cy2. :) Animation with only linear would be a huge inconvenience.

lucid explained in more detail towards the end of his 14th May post in this thread. (page 2 of the thread for me)

[NateS]

Ok. I looked at the HTML5 example and this seems like a very limited way of defining curves. Maybe a chart would make it more clear.

Here is Softimage:

The chart shows all the keys for the whole animation. Pay attention only to the white line. The first red dot is keyframe1, the second red dot is keyframe2. The leftmost black dot is c1x,c1y defined relative to keyframe1, and the rightmost black dot is c2x,c2y defined relative to keyframe2. With these 4 values you can define a complex curve between keyframes, which is extremely useful. The x-axis is time, the y-axis is property value.

Some of my questions in my first post still aren't answered. Eg, how do keyframes work? Are all properties keyed together?

[lucid]

Hi NateS,

sorry for the late reply. unfortunately because release is in a few days I can't give a detailed answer at the moment, but the design, which will undoubtedly evolve is meant to balance several factors, including maximizing the ability to run all features in realtime on all devices, flexibility, and ease of use. Eventually, the format will be fully documented, and at that point supporting re-parenting will be trivial to implement. Spriter will save enough information to the file that there will be no additional math involved to reparent, so it should run efficiently as well.

As far as choosing export options for different plugins and api's, we want to avoid differing export options as much as possible, and multiple versions of the file format, aside from the artist just not using certain features. We want to avoid fragmentation, and help establish it as a firm standard that artists and developers can trust to behave the same on all platforms. The less fragmentation will also facilitate the development of a healthy artist/developer ecosystem, where people can share art, implementations, and advice and tutorials on either regardless of intended target platform. This will work best if everyone can use everything anyone else created with little to no complications and where the target platform doesn't add additional requirements or specifics to learn.

With the current file format you can do varying degrees of ease in or fast in, ease out of fast out, and combinations of them (not supported in the UI yet in this upcoming version, just the file format). You cannot do things like bounce curves between 2 keyframes, but you can approximate the same effect without any great effort with multiple keys and less processing power. I think there's enough flexibility to achieve the visual end an animator wants, while keeping the ui very out of the way and uncluttered and the required processing at a minimum.

Also, the format is designed to allow for arbitrary expansion. For instance, the eventual sprite deformation is not mentioned in this format, and some procedural animation features, but I can think of several ways to add those features to the current format, which would only require additions to support the new features, but not any editing of already working parsing or processing code. So if the current speed curve system proves to be lacking, expanding it is definitely something we can look into at a future point.

Thanks for the input. Also, there is a more up to date posting of the file format here: http://www.brashmonkey.com/forum/viewtopic.php?f=2&t=609