ThreeJS Runtimes - Creature

Overview

This document describes how to use the ThreeJS 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.

Included Scripts

Here are the scripts that need to be included:

<script src="http://threejs.org/build/three.min.js"></script>
<script src="https://raw.githubusercontent.com/toji/gl-matrix/master/dist/gl-matrix.js"></script>
<script src="CreatureMeshBone.js"></script>
<script src="CreatureThreeJSRenderer.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:

	var texture = new THREE.ImageUtils.loadTexture("character-dragon.png");
	var material = new THREE.MeshBasicMaterial({
        		map: texture,
        		transparent: true,
    			side:THREE.DoubleSide
  			});
  		
	// Create creature renderer
	new_creature_renderer = new 
		CreatureRenderer("CreatureRenderer",scene, new_manager, material);

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 animateScene() callback:

		var animateScene = function () {
		    new_manager.Update(0.05); // update animation by 0.05 delta time
			new_creature_renderer.UpdateData();

			requestAnimationFrame(animateScene);
			renderer.render(scene, camera);
		};

Complete Code Sample

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

<!DOCTYPE html>
	<html>
	
	<head>
      <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
      <title>Three.js - Basic scene</title>
      
      <style>
  		html, body {
    		overflow: hidden;
    		width: 100%;
    		height: 100%;
    		margin: 0;
    		padding: 0;
  		}

		canvas { width: 100%; height: 100% }
	  </style>

   </head>
   
<body>

<h1>My First Web Page</h1>

<p>My first paragraph.</p>

<script src="http://threejs.org/build/three.min.js"></script>
<script src="https://raw.githubusercontent.com/toji/gl-matrix/master/dist/gl-matrix.js"></script>
<script src="CreatureMeshBone.js"></script>
<script src="CreatureThreeJSRenderer.js"></script>

<script>

    var xobj = new XMLHttpRequest();
        xobj.overrideMimeType("application/json");
	xobj.open('GET', 'default.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);
			
			var scene;
			var camera;
			var renderer;
			var new_creature;
			var new_manager;
			var new_creature_renderer;
			
			
			function initScene() {
				// Create scene
			    scene = new THREE.Scene();

	    		// This creates and positions a free camera
	    		camera = new THREE.PerspectiveCamera( 75, window.innerWidth / window.innerHeight, 0.1, 1000 );
				camera.position.z = -20;
				camera.lookAt(scene.position);
				scene.add(camera);
	
				// create renderer
				renderer = new THREE.WebGLRenderer();
				renderer.setSize(window.innerWidth, window.innerHeight );
				document.body.appendChild( renderer.domElement );
				
				new_creature = new Creature(actual_JSON);
			
				var new_animation_1 = new CreatureAnimation(actual_JSON, false);
				var new_animation_2 = new CreatureAnimation(actual_JSON, false);
			
				new_manager = new CreatureManager(new_creature);
				new_manager.AddAnimation(new_animation_1);
				new_manager.AddAnimation(new_animation_2);
				new_manager.SetActiveAnimationName("default", false);
				new_manager.SetShouldLoop(true);
				new_manager.SetIsPlaying(true);
				new_manager.RunAtTime(0);


			
				//var material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } );
				var texture = new THREE.ImageUtils.loadTexture("character-dragon.png");
				var material = new THREE.MeshBasicMaterial({
	        		map: texture,
	        		transparent: true,
        			side:THREE.DoubleSide
      			});
      		
						
  				// Create creature renderer
				new_creature_renderer = new CreatureRenderer("CreatureRenderer",
  															 scene, new_manager, 
  															 material);	  				
  			}

			var animateScene = function () {
			    new_manager.Update(0.05);
				new_creature_renderer.UpdateData();

				requestAnimationFrame(animateScene);
				renderer.render(scene, camera);
			};

			initScene();
			animateScene();
						  			  			
          }
    };
    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