Creature

Runtimes Introduction

Thursday, September 14, 2017 6:56 PM

Overview

You can export animation data out to a file that can be read in by various Game Engines via tha provided runtimes. A variety of Game Engines are supported: Unity, Cocos2dX, libGDX, MonoGame, ThreeJS, BabylonJS and PixiJS. In addition to that, you can use parts of the runtime code written in their base languages(C++, C#, Java, Javascript) and adapt it to your own custom engine(s).

Overview Video Tutorial

Watch this introductory video below to learn about the various runtime options and file formats to bring your authored Creature characters into target Game Engines:

Non

Optimizing Game Engine Assets for Export Video Tutorial

Watch this tutorial to learn about the different export options and how to export out your Game Engine Assets in an optimal way here

Downloading Runtimes

The runtimes for various game engines can be downloaded here.

Exporting Data

Meshing

Click on the Game Engines button to begin the export. The exported file has the extension .json and is in JSON format. You can use any JSON viewer to inspect that file for debugging purposes.

After you have exported the file, you should also grab the runtimes compatible with the Game Engine you are using.

Testing Exported Data with Web Viewer

There is an online Creature Webviewer that will display your exported JSON and texture atlas PNG files using the WebGL runtimes. This is a fast, convenient way to get a preview of how your exported animation will look like in a Game Engine.

The Web Viewer can be accessed here.

Supported Game Engine Runtimes

The following game engine runtimes are officially supported:

Runtimes Modules/Structure

Even though the Game Runtimes are available in different languages, the general design of their individual modules is the same. Let us examine the modules in depth to get a better idea of how the runtimes are organized:

Meshing

Core Modules

The core modules form the backend of the runtimes. In general you will not need to call or modify these modules directly. They consist of the following:

  • MeshBone: This module represents each bone in the bone hierarchy. Every instantiation of this class has references to any available children MeshBone objects. It has attributes to store the positions of the start and end points of each bone.

  • MeshRenderRegion: This module represents a mesh region of your character. The number of MeshRenderRegion objects instantiated will be the same as the number of mesh regions in your character. This module contains references to MeshBone objects and will use them to pose the final points of the mesh using the PoseFinalPts() function.

  • MeshRenderBoneComposition: This module is a container class that has references to MeshRenderRegions and MeshBone objects.

Frontend Modules

These modules operate on top of the Core Modules to provide Game Engine specific animation playback. You will most likely be calling functions/methods in this section:

  • Creature: This class has a reference to a MeshRenderBoneComposition object containing the bones and mesh regions of the creature. It also contains the points and topology of the data that will be rendered on screen. Any final deformations/transforms applied to the character mesh will be written into this object.

  • CreatureAnimation: This class represents a single animation clip. Each animation clip needs to have a corresponding CreatureAnimation object instantiated for playback to work.

  • CreatureManager: This class manages a Creature object and a list of CreatureAnimation objects. It has functions to add/create CreatureAnimations, set which animations to play, set playback properties(looping, custom time range etc.). It also handles the actual posing and updates of the animation in the function Update(). You can invoke this function at every timestep callback of your Game Engine.

General High Level Usage

In general, using the runtimes goes through the following pattern:

Initialization

  1. Call utility functions provided to load the desired character .json file.

  2. Create a Creature object and pass in the loaded file data.

  3. Create the corresponding CreatureAnimation objects, one each for every animation clip you want to load and playback. These animation objects need to be added to the Creature object. You can either do this manually or call the CreateAnimation() method provided by the Creature object. This will automatically create and add the animation into the Creature object for you.

  4. Create a CreatureManager object and assign it your Creature object. This completes the initialization steps.

Rendering

  1. This is a runtime specific area, each runtime has its own CreatureRenderer type class provided for this purpose.

  2. You typically load your character texture atlas file in .png format and assign it to the CreatureRenderer. You will also assign the CreatureManager object you created earlier to this CreatureRenderer.

Playback

  1. You can set different playback properties for each CreatureAnimation you have available. You can also set which animation is currently active for playback.

  2. At the time update callback of your engine, you will call the Update() method on the CreatureManager to update the animation.

  3. Certain runtimes require you to specifically invoke a draw or update method on the CreatureRenderer type object. Please check the runtime for more details.

JSON File Format

The exported Creature file is in JSON format. Here is the description of the various categories in this file.

Mesh

Mesh contains the overall points, uvs, indices and mesh regions of the character.

  • points: A flat array of floating point pairs (x, y) describing the points of the character. Total number of points = Sizeof(points) / 2

  • uvs: A flat array of floating point pairs (u, v) describing the uvs of the character. Total number of uvs = Sizeof(uvs) / 2

  • indices: A flat array of integer triples (idx1, idx2, idx3) describing the indices of triangles in the character. Total number of triangles = Sizeof(indices) / 3

  • regions: An object that contains children representing the different mesh regions of the character.

Each region has:

  • start_pt_index: the starting index of the index into both the points and uvs array

  • end_pt_index: the ending index of the index into both the points and uvs array

  • start_index: the starting index of the index into the indices array

  • end_index: the ending index of the index into the indices array

Skeleton

This contains the overall skeletal structure of the character. It contains a tree of bone objects.

Each bone has:

  • name: Name of the bone

  • children: A tree of child bone objects

Animation

This stores the available animations of the character. Each child object is named the same name as the animation name.

Each child object has:

  • bones: Child objects named from (starting frame, ending frame). Each object contains bone animation data.

  • meshes: Child objects named from (starting frame, ending frame). Each object contains mesh animation data.

  • uv_swaps: Child objects named from (starting frame, ending frame). Each object contains uv animation data.

Dealing with large JSON files (Zip Compression)

Some of the exported Creature animation might become quite large if mesh motors are used. In general animations that use mesh motors have a much larger file size than animations that just stick to using bone motors.

In general, the JSON files exported from Creature lend themselves extremely well to Zip compression. In fact, compression factors of 8x to 10x are very common. Hence, it is recommended that you compress exported Creature JSON files if larger file sizes become a problem.

In your game you would use a 3rd party library function to decompress the zipped JSON file before reading it in using Creature's runtime functions. Certain runtimes like the Cocos2d-x and Cocos2d runtimes already have built in zip file reading support.