Overview

This document describes how to use the PixiJS runtimes. The language of the runtimes is in JavaScript. We will go through an example of how to load an exported JSON file and play it back in the scene.

Grabbing the runtimes

You can either download the runtimes directly from the Creature Game Runtimes window or grab them from the repository here.

Picking a File Format and Runtime type

There are 2 types of runtimes you can choose: JSON/Creature FlatData or CreaturePack Web Format.

  • JSON/Creature FlatData : Gives you the full bone structure, is more feature complete but larger in size and more expensive to evaluate if you are not using point caching.

  • CreaturePack Web Format. : Only gives you the deformed points, uvs and colours. You do not get the skeletal structure of the character. However, it can be a lot smaller and is very cheap to evaluate, making playback very fast.

JSON/Creature FlatData

Included Scripts

Here are the scripts that need to be included:

<script src="pixi.js"></script>
<script src="https://raw.githubusercontent.com/toji/gl-matrix/master/dist/gl-matrix.js"></script>
<script src="CreatureMeshBone.js"></script>
<script src="CreaturePixiJSRefRenderer.js"></script>

Loading and Initialization

Let us assume we have an exported dragon animation file called default.json. We also have its corresponding texture atlas called character-dragon.png. We start off by first loading the file assets:

var xobj = new XMLHttpRequest();
    xobj.overrideMimeType("application/json");
xobj.open('GET', 'default.json', true); // Load the JSON file
	xobj.onreadystatechange = function () {
      if (xobj.readyState == 4 && xobj.status == "200") {
       // Required use of an anonymous callback as .open will NOT return a value but simply returns undefined in asynchronous mode
       var response = xobj.responseText;
      // Parse JSON string into object
		var actual_JSON = JSON.parse(response);
		
		...

The above will load the JSON data from disk and into memory. Next, let us create the actual objects that can make use of these loaded assets:

		var new_creature = new Creature(actual_JSON, false);
		
		var new_animation_1 = new CreatureAnimation(actual_JSON, "default", false);
		var new_animation_2 = new CreatureAnimation(actual_JSON, "second", false);
		
		var new_manager = new CreatureManager(new_creature);
		new_manager.AddAnimation(new_animation_1);
		new_manager.AddAnimation(new_animation_2);

In the example above, the JSON file has 2 animation clips: default and second. Hence, we will need to create 2 animations from the creature_manager object to make them available for playback.

Now that we are done loading, we can set the active animation to default for playback, as well as some playback properties:

		new_manager.SetActiveAnimationName("default", false);
		new_manager.SetShouldLoop(true);
		new_manager.SetIsPlaying(true);
		new_manager.RunAtTime(0);

We will now go ahead and create the object(s) required to render the character animation:

		// create a texture from an image path
		var texture = PIXI.Texture.fromImage("character-dragon.png");
		
		var creatureContainer = new PIXI.DisplayObjectContainer();
		creatureContainer.position.x = window.innerWidth/2;
		creatureContainer.position.y = window.innerHeight/2;

		creatureContainer.scale.set(35.0);
		stage.addChild(creatureContainer);
		
		var new_creature_renderer = new CreatureRenderer(new_manager, texture);
		creatureContainer.addChild(new_creature_renderer);

Character Animation and Rendering Updates

Once we have loaded the character, we need to call the corresponding update calls to update the animation and render the character. This is done in the animate() callback:

		function animate() {

    		requestAnimationFrame( animate );
    		
		    new_manager.Update(0.05);
		    new_creature_renderer.refresh();
    		
    		// render the stage   
    		renderer.render(stage);
		}
		

Complete Code Sample

Here is the complete code layout. Most the the code is generated from the default PixiJS project starter template:

<!DOCTYPE html>
    <html>
	
	<head>
      <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
      <title>PixiJs - Basic scene</title>
      
      <style>
      
      	canvas {
 		   border: 1px dashed gray;
	  	}
	  	
  		html, body {
    		overflow: hidden;
    		width: 100%;
    		height: 100%;
    		margin: 0;
    		padding: 0;
  		}

	  </style>

   </head>
   
<body>

<h1>My First Web Page</h1>

<p>My first paragraph.</p>

<script src="pixi.dev.js"></script>
<script src="https://raw.githubusercontent.com/toji/gl-matrix/master/dist/gl-matrix.js"></script>
<script src="CreatureMeshBone.js"></script>
<script src="CreaturePixiJSRefRenderer.js"></script>

<script>

    var xobj = new XMLHttpRequest();
        xobj.overrideMimeType("application/json");
	xobj.open('GET', 'dragonTest.json', true); // Replace 'my_data' with the path to your file
	xobj.onreadystatechange = function () {
          if (xobj.readyState == 4 && xobj.status == "200") {
            var response = xobj.responseText;
            // Parse JSON string into object
			var actual_JSON = JSON.parse(response);
			
  			new_creature = new Creature(actual_JSON, false);
		
			new_animation_1 = new CreatureAnimation(actual_JSON, "default", false);
			new_animation_2 = new CreatureAnimation(actual_JSON, "pose2", false);
			
			var new_manager = new CreatureManager(new_creature);
			new_manager.AddAnimation(new_animation_1);
			new_manager.AddAnimation(new_animation_2);
			new_manager.SetActiveAnimationName("pose2", false);
			new_manager.SetShouldLoop(true);
			new_manager.SetIsPlaying(true);
			new_manager.RunAtTime(0);
			
			// create an new instance of a pixi stage
    		var stage = new PIXI.Stage(0x000000);
 
    		// create a renderer instance.			
    		var renderer = PIXI.autoDetectRenderer(window.innerWidth, window.innerHeight);
    		
    		if (renderer.type == PIXI.WEBGL_RENDERER) {
  				console.log('Using WebGL');
			} else {
  				console.log('Using Canvas');
			};
 
    		// add the renderer view element to the DOM
    		document.body.appendChild(renderer.view);
    		    		
    		// create a texture from an image path
    		var texture = PIXI.Texture.fromImage("character-dragon.png");
    		
    		var creatureContainer = new PIXI.DisplayObjectContainer();
			creatureContainer.position.x = window.innerWidth/2;
			creatureContainer.position.y = window.innerHeight/2;

			creatureContainer.scale.set(35.0);
			stage.addChild(creatureContainer);
			
			var new_creature_renderer = new CreatureRenderer(new_manager, texture);
			creatureContainer.addChild(new_creature_renderer);
			creatureContainer.scale.x = -creatureContainer.scale.x;
  
		function animate() {

    		requestAnimationFrame( animate );
    		
		    new_manager.Update(0.05);
		    new_creature_renderer.refresh();
    		
    		// render the stage   
    		renderer.render(stage);
		}
		
		animate();
      }
    };
    xobj.send(null);  
 
 
</script>

</body>
</html> 

Custom Time/Frame Range

You can set custom time/frame ranges for the currently active animation. Say you wanted to limit the playback to the frame range of 10 to 20, you would do the following:

new_creature_manager.SetUseCustomTimeRane(true);
new_creature_manager.SetCustomTimeRange(10, 20);

Animation Blending

You can blend between 2 animation clips by doing the following:

curManager.SetBlending(true);	
curManager.SetBlendingAnimations("default", "pose2");
curManager.SetBlendingFactor(0.5);	 // 0 to 1 blends between the 2 clips

Speeding up Load Times + Reducing Memory Usage with Creature Flat Binary Data

You can speed up load times + reduce memory usage of large character assets by converting your Creature JSON files over into the Creature Flat Binary Data format. If you are running out of heap memory on your device, we recommend using the Flat Binary Data format for loading of Creature character assets.

First, go onto the Creature Tools Github Page:

  1. Go into the FlatData directory.

  2. You can either compile the CreatureFlatData converter program or just grab the binaries for your system (Mac or Windows) from the Bin directories.

Running the CreatureFlatData Converter

This is a command line program that will take your input exported Creature Character JSON file and convert it into a binary Creature Flat Data file. We recommend you use for the final converted output binary file to have an extension of .bytes so that Unity can recognize it as a binary asset.

To run the CreatureFlatData Converter, load up the terminal/command prompt:

CreatureFlatData <Input JSON File> <Output .bytes File>

Using the Creature Flat Binary

First, retrieve the binary file as you would in your current framework. Then, do the following:

		var actual_data = CreatureModuleUtils.LoadCreatureFlatData(game.cache.getBinary('myFlatDataBinary.bin'));
		
		new_creature = new Creature(actual_data, true);			
		new_animation_1 = new CreatureAnimation(actual_data, "idle", true);

As you can see, all you are doing is to grab a reference to the flat data object. Then set the last parameter in the Creature and CreatureAnimation creation to true. This triggers a binary flat data load.

CreaturePack Web Format

Tuning the CreaturePack Web Format

In the Game Engine Export Window of Creature, you have the following options:

  • Gap Step : This decides how much approximation is done on export. The higher the number, the smaller the file size but lower the quality. A value of 1 means no approximation. Try anything from 1 to 6.

  • UV Swaps : Check this on or off to decide whether to export UV swapping. If you are using image swaps, you should check this option to ON.

  • Color Changes :Check this on or off to decide whether to export any opacity changes. If you are fading regions, check this option to ON.

File sizes can be reduced quite a bit by increasing the Gap Step at the expense of some quality loss.

Included Scripts

You will need the following:

	<script src="msgpack.js"></script>
	<script src="CreaturePackModule.js"></script>
	<script src="CreaturePixiPackJSRenderer.js"></script>

Loading and Initialization

Grab the binary buffer of your file and pass it into the CreaturePackLoader:

		creature_pack = new CreaturePackLoader(game.cache.getBinary('raptorPack').buffer);
		

Rendering

Have a look at the file: CreaturePixiJSRenderer.js Also check the Phaser Documentation for more information since it the concepts are very similar.