API: Three (AB) (r3)

API Uses canvas Graphics libraries AB framework Worlds using this API Starter Worlds
Three (AB) (r3) Yes Three.js Yes 1482 Worlds Starter Worlds


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:



Templates



Global variables

 

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

ABWorld

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 

Initialisation

 

// 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

   ABWorld.cameraFixed();
	// 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 
   
   ABWorld.cameraTrack(); 
	// position: default   
	// looks at: point defined by ABWorld.follow (can change every step)
	
   ABWorld.cameraMove();
	// 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 } );
else                       
	ABWorld.renderer = new THREE.WebGLRenderer ( { preserveDrawingBuffer : false } );


ABHandler

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

Examples of Worlds that use this API:


Touch World
457 runs ♦ 1 like
By Starter user  
Created: 6 Jan 2018
Modified: 17 Sep 2023
How to override default touch handling. Mobile: Touch drag moves agent, touch pinch zooms camera...
Castle World
786 runs ♦ 4 likes
By Starter user  
Created: 11 Nov 2016
Modified: 17 Sep 2023
Demo of how to insert 3d model into World. Mind-controlled agent, actively-pursuing enemy. Splas...
User-controlled ...
919 runs ♦ 2 likes
By Starter user  
Created: 12 Feb 2017
Modified: 17 Sep 2023
3d model World. User controlled on desktop. Keyboard arrows to move. Switch to "Move with" camer...
Password Websock...
67 runs ♦ 0 likes
By Starter user  
Created: 14 Nov 2022
Modified: 17 Sep 2023
Password version of "Websockets boxes"
Websockets boxes
803 runs ♦ 0 likes
By Starter user  
Created: 29 Feb 2020
Modified: 17 Sep 2023
Demo of Websockets in 3D World. Click to change the boxes on the other user's machine, while the...
Complex World
8204 runs ♦ 5 likes
By Starter user  
Created: 1 Oct 2016
Modified: 17 Sep 2023
World with a Mind-controlled agent, actively-pursuing enemy, random maze, skybox, music.
Model World
856 runs ♦ 2 likes
By Starter user  
Created: 8 Nov 2016
Modified: 17 Sep 2023
Demo of how to insert 3d models into World. Mind-controlled agent, actively-pursuing enemy. Skybox.
Blank Three.js World
1506 runs ♦ 2 likes
By Starter user  
Created: 20 Nov 2016
Modified: 17 Sep 2023
A simple starter World. An Array of spheres. Painted with textures. Random motion.
Simple World
1647 runs ♦ 2 likes
By Starter user  
Created: 1 Oct 2016
Modified: 17 Sep 2023
Simple World with a Mind-controlled agent, randomly-moving enemy, paint blocks with texture.
One Cube World (...
1114 runs ♦ 2 likes
By Starter user  
Created: 11 Apr 2018
Modified: 17 Sep 2023
Simple starter World (Three.js version). Built-in camera control.
MineCraft
1116 runs ♦ 2 likes
By Starter user  
Created: 27 Nov 2016
Modified: 17 Sep 2023
Use keyboard to draw blocks like in MineCraft. Use arrow keys and PgUp, PgDn to draw. Can save w...
Zombie Death Baby
771 runs ♦ 1 like
By Starter user  
Created: 11 Jun 2018
Modified: 17 Sep 2023
How to make a fun touch game for mobile. Touch drag and tap objects. Mouse drag and click object...