API: Physics (AB) (r1)

API Uses canvas Graphics libraries AB framework Worlds using this API Starter Worlds
Physics (AB) (r1) Yes Three.js, Physijs Yes 184 Worlds Starter Worlds

This API is for Three.js Worlds with physics using the Physijs library. It comes with an Ancient Brain framework to make writing Worlds easier.

Note: The Physijs project is dormant since 2015.
Our newer physics APIs will use a different physics library.
We will not update this API. Worlds written for this API will continue to work.

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
 Physijs;       // from Physijs library 


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

		// This is a Physijs scene: Physijs.Scene
		// This is NOT a normal 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 


Examples of Worlds that use this API:

Infinite World G...
146 runs ♦ 0 likes
By Enhanced  
Created: 16 Aug 2018
Modified: 17 Sep 2023
Here is a code to get an infinite world that loop without object in it, and with the sun
Infinite World O...
97 runs ♦ 0 likes
By Enhanced  
Created: 16 Aug 2018
Modified: 17 Sep 2023
Here is a code to get an infinite world that loop without object in it, without the sun
Bouncy Balls
529 runs ♦ 3 likes
By Starter user  
Created: 1 Oct 2017
Modified: 17 Sep 2023
Demo of Physics API. Balls bounce under gravity and collide in low friction world. Splash screen...
Collision World
1392 runs ♦ 4 likes
By Starter user  
Created: 21 Sep 2017
Modified: 17 Sep 2023
Demo of Physics API. Blocks fall under gravity and collide. Can modify gravity, friction, etc. S...
First Person Con...
212 runs ♦ 0 likes
By Enhanced  
Created: 21 Jun 2018
Modified: 17 Sep 2023
First person view with mouse controls. Use WASD or Arrows to move, mouse to look around and spac...