API: Three (AB) (r3)

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:

• Includes Three.js release 127.
  • See Three.js documentation.

• Includes the following libraries for loading 3D models:
  • OBJLoader
  • MTLLoader
  • TGALoader
  • GLTFLoader

• Includes jQuery 3.6.0.
• Loads up minimal CSS that should not conflict with user CSS.

• 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.

---

Templates

• World with no Mind

• World with Mind
• Mind

---

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.  

• See a JS code search of all Worlds for ABWorld.init3d.
• See a JS code search of all Worlds for ABWorld.init2d.

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; 	 

• See a JS code search of all Worlds for ABWorld.follow.
• See a JS code search of all Worlds for ABWorld.lookat.

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!

• To override default mouse and touch handling, redefine some or all of the 6 functions.
• For example, drag could drag an object not the camera.
• You can abandon camera functionality entirely. Or you can add your own code and also call the camera functionality by calling the 3 core functions.

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 
  

• See a JS code search of all Worlds for ABHandler.mouseDrag.
• See a JS code search of all Worlds for ABHandler.touchDrag.

Examples

Examples of Worlds that use this API: