Castle Game Engine
← Users Developers →
 
Intro
 
News
 
view3dscene
 
The Castle
 
All Programs
 
Forum
 
Donate
 
Engine
 
VRML/X3D
 
Blender
 

Kanim file format

Contents:

What it is

Files with extension *.kanim represent "Castle Game Engine's animations". These are XML files that describe precalculated animation as a sequence of files. Animation shows the transition from the first model to the last. Where models are structurally equal, intermediate frames are created by linear interpolation to show smooth changes.

Since animation by VRML/X3D events and interpolators is implemented in our engine now, Kanim format becomes obsolete. It's useful only if your favorite 3D modeler cannot export VRML/X3D animation with interpolators, but it can export static VRML/X3D files.

Blender exporter for this format is available (online docs), since Blender cannot export animations with interpolators to VRML.

On the positive side, there is at least one open-source program that can create animations with interpolators: White Dune. White dune has even an exporter to Kanim format, given a VRML animation by interpolators it generates a Kanim file and corresponding VRML files for each frame.

If you work with 3D modeler that can export proper VRML animation with interpolators, then you don't need to use Kanim format. Our engine handles events and interpolators perfectly. Internally, they may even be converted (after loading) to precalculated animations.

There's also a crude converter from kanim format to VRML/X3D interpolators in our engine examples (see examples/vrml/tools/kanim_to_interpolators). It's a little crude (works only when you animate only a single mesh), but may be enough for simple uses. So this is one way to generate an animated VRML/X3D file from Blender: export from Blender to kanim, then convert kanim to VRML/X3D.

For more technical insight, see description of animation handling in our VRML engine documentation.


Exact format specification

File format is simple:


<?xml version="1.0"?>
<animation              // Root node is always "animation".
                        // All it's attributes are optional
                        // (default values are shown below).
                        // Some of it's attributes should be treated like a
                        // "hint for the renderer". General programs like
                        // view3dscene may honor them,
                        // but more specialized programs (like "The Castle"
                        // game) may ignore them, since "they know better".

  scenes_per_time="30"  // Suggested number of scenes per time to be generated.
                        // This is a hint for the renderer — by default it's
                        // 30, but it may be ignored. Larger values make
                        // animation smoother, but also much more memory consuming.
                        // Special value 0 is allowed here, and means
                        // that animation will simply show each <frame>,
                        // suddenly changing into the next <frame>,
                        // without any smoothing of transitions with
                        // intermediate scenes.

  equality_epsilon="0.001"
                        // Epsilon to use when comparing animation frames
                        // and deciding which parts didn't move at all between
                        // two adjacent frames. You can set this even to literal
                        // "0.0", but this may cause a lot of memory to be wasted
                        // when loading large animation. It's better to set
                        // this to some very small value — so small that you're
                        // sure that user will not notice such small move
                        // anyway.

  loop="false"          // Should the animation loop ? This is a hint for
                        // the renderer, and may be ignored. Allowed values
                        // are "false" and "true", not case-sensitive.
                        // When this animation is used for creature/item in game,
                        // this is ignored.

  backwards="false"     // Should the animation go backwards after going
                        // forward ? Allowed values
                        // are "false" and "true", not case-sensitive.
                        // When this animation is used for creature/item in game,
                        // this is not ignored.
>

  // A number of <frame> nodes should follow. At least one is required.
  // Note that exactly one <frame> node will actually define a still scene,
  // you need at least 2 frames if you want a real animation.

  <frame

    url="file_1.wrl" // This is a required attribute, and specifies
                     // the URL from which to load this
                     // animation frame. Any 3D file format is allowed here:
                     // most of all, VRML/X3D, but also
                     // other formats understood by view3dscene and our engine.
                     // There is also a deprecated attribute "file_name"
                     // that means the same as "url".

    time="0.0"       // This is a required attribute specifying a
                     // time of this frame. For now, all frames
                     // must be specified in the strictly increasing order
                     // of their "time".
                     // This is understood to be in seconds.
  />

  // For example, assume that the second <frame> node follows.
  // So this defines an animation that changes from
  // file_1.wrl and file_2.wrl in exactly 1 second.

  <frame url="file_2.wrl" time="1.0" />

</animation>

Shortcomings of this format

As I mentioned above, kanim format is obsolete. Some things that cannot be achieved using kanim (and probably never will be, as we would advice everyone to use VRML/X3D interpolators for all your needs):

  • Our collision detection uses the first (or both first and last) frame. Octrees are not updated between frames. So collision detection, mouse picking, ray-tracer look only at the 1st animation frame, because our octree represents only this frame.

    Use instead VRML/X3D interpolators, when octree is properly managed.

  • Background animations do not work (we use MainScene.Background always).

    Use instead VRML/X3D interpolators, when background is fast updated. Note that you can use our ColorSetInterpolator (extension to the interpolation component) to animate sets of colors like skyColor, groundColor. See our VRML/X3D demo models (look inside background/background_animate*) for demos.

  • Some view3dscene features, like saving to VRML/X3D and "Remove Selected Geometry/Face", only work on the 1st animation frame.