API: Three (AB) (r1)

API Uses canvas Graphics libraries AB framework Worlds using this API Starter Worlds
Three (AB) (r1) Yes Three.js Yes 1268 Worlds None

This API is for Three.js Worlds. It comes with an Ancient Brain framework to make writing Worlds easier.

This API has the following features:


Global variables


 ABWorld;       // instance of class ABWorldClass - basic functionality for this API
 ABHandler;     // instance of class ABHandlerClass - mouse and touch handling for this API


This API starts a Three.js environment.
You can access the normal Three.js objects through ABWorld variables.

   ABWorld.camera;       // Three.js camera: THREE.PerspectiveCamera                 
   ABWorld.renderer;     // Three.js renderer: THREE.WebGLRenderer
   ABWorld.scene;        // Three.js scene: THREE.Scene 



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

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

     // startRadius = start position of camera  
     // maxRadius = camera frustum far plane  
// 2D Worlds are merely special cases of 3D Worlds. 
// In 2D Worlds, the camera is set to directly overhead.
// The World should make objects of height about 1 pixel.  

Camera control

// these points are used in some camera modes - see below 
// they can change every step 
   ABWorld.follow;               // THREE.Vector3          
   ABWorld.lookat;               // THREE.Vector3        
// the camera modes
// set these AFTER Initialisation

	// default mode 
	// position: picks a plausible position
	// looks at: centre of the scene 
	// can click to rotate and zoom 
   ABWorld.cameraCustom ( position, lookat );
	// set your own camera position and point to look at 
	// can click to rotate and zoom 
	// position: default   
	// looks at: point defined by ABWorld.follow (can change every step)
	// position: ABWorld.follow (can change every step)
	// looks at: ABWorld.lookat (can change every step)
 // draw camera control buttons (Fixed/Track/Move) 
   ABWorld.drawCameraControls = true; 	 

Size of object


// Find size of loaded 3D object.
// Size of object along each dimension:

   ABWorld.objectXsize ( theobject );
   ABWorld.objectYsize ( theobject );
   ABWorld.objectZsize ( theobject );

Touch and click on object

// "Ray casting" function for mouse/touch control of object.
// Returns boolean - if click on that x,y screen position hits object in 3D World.

   ABWorld.hitsObject ( x, y, theobject );             
// Return the 3D (x,y,z) point at which click/tap hits object
// returns null if no hit

   ABWorld.hitsObjectPoint ( x, y, theobject );       

Custom scene, camera, renderer

You can make your own custom versions of the Three.js objects scene, camera and renderer.
The initialisation function (init3d or init2d) will create a default scene, camera and renderer. You may then manipulate these. But that may not be flexible enough.

To make your own scene, camera or renderer, define them before calling the initialisation function.
Set the variables in ABWorld and then the initialisation function knows not to create them. Sample usage:


ABWorld.renderer = new THREE.WebGLRenderer ( { antialias: true } );

ABWorld.init3d ( startRadius, maxRadius, color ); 
  // will not create renderer, will use my one 

Custom renderer: preserveDrawingBuffer

Here is an important note if you make your own renderer.
This is about allowing runs to generate a World image screenshot from the canvas.
To allow this, the API sets the THREE.WebGLRenderer property "preserveDrawingBuffer" to true by default. The API takes care of this for you.
If you make your own renderer, you need to consider "preserveDrawingBuffer". If you create the renderer like the following, then your World cannot have a screenshot:
ABWorld.renderer = new THREE.WebGLRenderer ( { preserveDrawingBuffer: false } );
To solve this, you can make preserveDrawingBuffer always true, or make it true only on screenshot runs:

if ( AB.isScreenshotRun() )
	ABWorld.renderer = new THREE.WebGLRenderer ( { preserveDrawingBuffer : true } );
	ABWorld.renderer = new THREE.WebGLRenderer ( { preserveDrawingBuffer : false } );


The "ABHandler" object implements mouse and touch handling.
The default is that mouse and touch will control the camera.
The granularity of control is customisable, which may be needed for Worlds of different scales.
// multiply mouse scroll by some factor to increase/decrease how much camera zooms:

   ABHandler.SCROLLFACTOR = 1;          	 

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

   ABHandler.PINCHFACTOR  = 1;           	 	
// for 2D worlds:
// multiply mouse/touch drag by some factor to increase/decrease how much camera moves:
   ABHandler.DRAGFACTOR   = 1;            	 

// maximum position of camera:

   ABHandler.MAXCAMERAPOS;    // given some sensible default depending on World   

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

   ABHandler.GROUNDZERO = false;

Mouse and touch move the camera

The default is that mouse and touch move the camera.
There are 3 core functions:

  ABHandler.initCameraDrag ( x, y ); 
    // start camera drag now, at screen position x,y   

  ABHandler.cameraDrag ( x, y ); 
    // drag went to new screen position x, y  
    // move the camera accordingly
  ABHandler.cameraZoom ( delta );
    // zoom the camera in or out by some amount 
To define mouse and touch to move the camera, we assign these 6 functions as follows:

ABHandler.initMouseDrag = function ( x, y )  { ABHandler.initCameraDrag ( x, y );  };
ABHandler.mouseDrag     = function ( x, y )  { ABHandler.cameraDrag ( x, y );      };
ABHandler.mouseZoom     = function ( delta ) { ABHandler.cameraZoom ( delta );     };

ABHandler.initTouchDrag = function ( x, y )  { ABHandler.initCameraDrag ( x, y );  };
ABHandler.touchDrag     = function ( x, y )  { ABHandler.cameraDrag ( x, y );      };
ABHandler.touchZoom     = function ( delta ) { ABHandler.cameraZoom ( delta );     };

Custom mouse and touch handling

Why did we write it like the above? Are we suggesting you could put your own code inside the chain brackets? Yes!

You can restore the default mouse/touch camera control at any time by doing:

  ABHandler.defaultMouse();   // Restore default mouse camera control 
  ABHandler.defaultTouch();   // Restore default touch camera control