API: Three r80

The "Three r80" API has the following features:
  • Based on Three.js release 80. (Three.js continues to develop. But this API stays at this version so runs will never break.)
  • 3D and 2D graphics.
  • Built-in mouse (and touch screen) control of camera. Scroll and drag the mouse (or touch pinch and touch drag) to see camera control in both 3D and 2D Worlds.
  • A 2D world is in fact just a 3D world. This API "supports" it by always keeping the camera pointed straight down.

World() and Mind() classes must be declared. See below. All other declarations are optional.


Global variables

This API, combined with the underlying system, defines the following global variables:
 

 AB;               // instance of class ABClass - general Ancient Brain functionality     
 ABRun;            // instance of class ABRunClass - extra functionality for runs   
 
 threeworld;       // instance of class ThreeWorldClass - basic functionality for this API
 threehandler;     // instance of class ThreeHandlerClass - mouse and touch handling for this API
 

The "threeworld" object

The public variables and methods of "threeworld" are as follows:

 

// start a 3D or 2D scene with camera on the canvas:		

   threeworld.init3d ( startRadius, maxRadius, color );   
   threeworld.init2d ( startRadius, maxRadius, color );  

     // startRadius = start position of camera  
     // maxRadius = camera frustum far plane  
    
    
   threeworld.scene;        // Three.js scene: THREE.Scene 
   threeworld.camera;       // Three.js camera: THREE.PerspectiveCamera                 
   threeworld.renderer;     // Three.js renderer: THREE.WebGLRenderer
	
		
 // change these points to control camera movement:
  
   threeworld.follow;               // THREE.Vector3          
   threeworld.lookat;               // THREE.Vector3        

	  // when camera is in "Track" mode, it will look at threeworld.follow
	  // when camera is in "Move" mode, it will position at threeworld.follow,
	  //   and look at threeworld.lookat
	 
	 
 // Useful "ray casting" function for mouse/touch control of objects:

   threeworld.hitsObject ( x, y, theobject );		 // boolean 

      // returns if click/tap on that x,y screen position hits object in 3D World

See the JS of the examples for instances where threeworld is called.
See Three.js documentation for THREE.Scene and THREE.PerspectiveCamera and THREE.WebGLRenderer.

The "threehandler" object

This implements mouse and touch event handling. The default is that mouse and touch control the camera, but this can be overridden.

The public variables and methods of "threehandler" are as follows:

 
   
// multiply mouse scroll by some factor to increase/decrease how much camera zooms:

   threehandler.SCROLLFACTOR;         // default value: 1 	 

// multiply touch pinch by some factor to increase/decrease how much camera zooms:

   threehandler.PINCHFACTOR;          // default value: 1 	 	
	
// for 2D worlds, multiply mouse (or touch) drag by some factor to increase/decrease how much camera moves:
 
   threehandler.DRAGFACTOR;           // default value: 1	 

   
// maximum position of camera:

   threehandler.MAXCAMERAPOS;         // default value: (startRadius * 2)

   
// does a "ground" exist at altitude zero (that camera should not zoom below):

   threehandler.GROUNDZERO;           // default value: false
	

// functions that can be over-ridden:	
// mouse/touch controls the camera by default
// re-define the following functions to over-ride this and use mouse/touch for something else:	

  threehandler.initMouseDrag = function ( x, y )  ...    
    // start drag now, at screen position x,y   

  threehandler.mouseDrag     = function ( x, y )  ...    
    // drag went to new screen position x, y  
 
  threehandler.mouseZoom     = function ( delta ) ...
    // zoom in or out by some amount 
    // the amount is set up for camera zoom 
    // for other usage of zoom, maybe just ignore delta, or only look at its sign  

	
  threehandler.initTouchDrag = function ( x, y )  ...
  threehandler.touchDrag     = function ( x, y )  ...
  threehandler.touchZoom     = function ( delta ) ...
    

Here is a sample World that over-rides the default mouse and touch actions:


Mouse objects and Tou...
152 runs ♦ 1 likes
Starter user

2D or 3D graphics

2D scenes are merely special cases of 3D scenes. The World initialises the scene by calling one of the following:
threeworld.init3d()
threeworld.init2d()

If it picks 2D, then the API will keep the camera directly overhead. The World should make objects of near-zero height.

In the following example Worlds, the World picks either 2D or 3D, and sets box height to either 1 pixel or full square (view the JS):


Keyboard and Touch
163 runs ♦ 1 likes
Starter user
Complex World
1456 runs ♦ 2 likes
Starter user

Optional: Customising scene, camera, renderer

The functions init3d and init2d create default forms of scene, camera and renderer. If you want a customised form of these, define the variable before calling init3d or init2d, and then your version will be used, not the default. Example:
 
threeworld.renderer = new THREE.WebGLRenderer ( { antialias: true } );
threeworld.init3d ( startRadius, maxRadius, color ); 

Note if you are customising renderer: To be able to generate World image screenshots, you need:

 
threeworld.renderer = new THREE.WebGLRenderer ( { preserveDrawingBuffer: true } );	


Examples

Examples of Worlds that use this API:


Blank Three.js World
458 runs ♦ 2 likes
Starter user
Simple World
797 runs ♦ 2 likes
Starter user

Blank JavaScript templates

Here are blank JavaScript templates for Worlds and Minds.

See Object Oriented programming in JavaScript



World with no Mind


// Customise AB run parameters (optional).
// The following 3 parameters can be customised. (They have default values.)

AB.clockTick       = int;    

	// Speed of run: Step every n milliseconds. Default 100.
	
AB.maxSteps        = int;    

	// Length of run: Maximum length of run in steps. Default 1000.

AB.screenshotStep  = int;   
  
	// For automatic generation of World images.
	// Take screenshot on this step. (All resources should have finished loading.) Default 50.

	

function World() { 

	// Optional declaration:
	// If endCondition is declared, runs will check for endCondition true and then terminate.
	// If not declared, runs will make no such check.
	
	this.endCondition = false;				  


	// Optional functions:
	// The following 3 function declarations are optional.
	// If not declared, nothing happens and the run continues.
	
	this.newRun = function()
	{
		// Code for Three.js initial drawing of objects.
		// Should include one of:
	 	// threeworld.init2d ( arguments ); 	
	 	// threeworld.init3d ( arguments ); 	
	};


	this.nextStep = function()		 
	{
		// Code for Three.js re-drawing of objects.  
		
		if ( some condition )	   // Optional: Check for condition that will end the run early.
		{
			this.endCondition = true;	// This will end the run. 
		}
	};


	this.endRun = function()
	{
	};

}



World with a Mind


// Customise AB run parameters (optional).
// The following 3 parameters can be customised. (They have default values.)

AB.clockTick       = int;    

	// Speed of run: Step every n milliseconds. Default 100.
	
AB.maxSteps        = int;    

	// Length of run: Maximum length of run in steps. Default 1000.

AB.screenshotStep  = int;   
  
	// For automatic generation of World images.
	// Take screenshot on this step. (All resources should have finished loading.) Default 50.

	

function World() { 

	// Optional declaration:
	// If endCondition is declared, runs will check for endCondition true and then terminate.
	// If not declared, runs will make no such check.

	this.endCondition = false;				  

	
	// Optional functions:
	// The following 5 function declarations are optional.
	// If not declared, either nothing happens, or, if a return is expected, return is taken as 0.

	this.newRun = function()
	{
		// Code for Three.js initial drawing of objects.
		// Should include one of:
 		// threeworld.init2d ( arguments ); 	
 		// threeworld.init3d ( arguments ); 	
	};


	this.getState = function()
	{
	  return ( state );  				// State format defined by this World.
	};


	this.takeAction = function ( action )		// Action format defined by this World.
	{
		// Code for Three.js re-drawing of objects.  
		
		if ( some condition )	   // Optional: Check for condition that will end the run early.
		{
			this.endCondition = true;	// This will end the run. 
		}
	};


	this.endRun = function()
	{
	};


	this.getScore = function()
 	{
	 return ( float );		
	};

}



Mind


function Mind() { 

	// Optional functions:
	// The following 3 function declarations are optional.
	// If not declared, either nothing happens, or, if a return is expected, return is taken as 0.

	
	this.newRun = function()
	{
	};


	this.getAction = function ( state )		// State format is defined by each World.
	{ 
	 return  ( action );		 		// Action format is defined by each World.
	};


	this.endRun = function()
	{
	};

}

The background is a program, showing the JavaScript graphics used on this site.
Customise background:  
Font:

© Ancient Brain Ltd. All rights reserved.

Ancient Brain ™ is a trademark of Ancient Brain Ltd.

Beta      Bug bounty      Contact      Stats      The name      Terms and conditions