API | Uses canvas | Graphics libraries | AB framework | Worlds using this API | Starter Worlds |
Three (AB) (r3) | Yes | Three.js | Yes | 1147 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:
ABWorld; // instance of class ABWorldClass - basic functionality for this API ABHandler; // instance of class ABHandlerClass - mouse and touch handling for this API
ABWorld.camera; // Three.js camera: THREE.PerspectiveCamera ABWorld.renderer; // Three.js renderer: THREE.WebGLRenderer ABWorld.scene; // Three.js scene: THREE.Scene // draw camera control buttons (Track/Move/Normal) or not ABWorld.drawCameraControls = true; // change these points to control camera movement: ABWorld.follow; // THREE.Vector3 ABWorld.lookat; // THREE.Vector3 // when camera is in "Track" mode, it will look at ABWorld.follow // when camera is in "Move" mode, it will position at ABWorld.follow, // and look at ABWorld.lookat
The "ABWorld" object
has the following public methods:
// 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 // change the mode of the camera to Track/Move With/Normal ABWorld.cameraTrack(); ABWorld.cameraMove(); ABWorld.cameraFixed(); // Useful functions for finding size of loaded 3D objects. // Size of object along each dimension. ABWorld.objectXsize ( theobject ); ABWorld.objectYsize ( theobject ); ABWorld.objectZsize ( theobject ); // Useful "ray casting" function for mouse/touch control of objects. // Returns if click/tap on that x,y screen position hits object in 3D World. ABWorld.hitsObject ( x, y, theobject ); // boolean // Returns (3D co-ordinates) x,y,z point at which click/tap hits object: ABWorld.hitsObjectPoint ( x, y, theobject ); // returns null if no hit
The "ABHandler" object has the following public data. Default values are shown. These can be changed.
// 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 (or 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;
The "ABHandler" object
defines
the following functions for mouse and touch events.
ABHandler.initMouseDrag = function ( x, y ) { ... }; // start drag now, at screen position x,y ABHandler.mouseDrag = function ( x, y ) { ... }; // drag went to new screen position x, y ABHandler.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 ABHandler.initTouchDrag = function ( x, y ) { ... }; ABHandler.touchDrag = function ( x, y ) { ... }; ABHandler.touchZoom = function ( delta ) { ... };The above functions move the camera by default. To override this, and do your own mouse and touch event handling, simply redefine these functions.
To restore the default mouse/touch camera control, use:
ABHandler.defaultMouse(); // Restore default mouse camera control ABHandler.defaultTouch(); // Restore default touch camera control
Examples of Worlds that over-ride the default mouse and/or touch actions:
ABWorld.init3d() ABWorld.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.
ABWorld.renderer = new THREE.WebGLRenderer ( { antialias: true } ); ABWorld.init3d ( startRadius, maxRadius, color );
This API uses an edited version of Three.js with the THREE.WebGLRenderer property "preserveDrawingBuffer" set to true. This is needed to allow the site generate a World image screenshot from the canvas. This may lead to lower performance, though.
If you are not customising renderer, but rather using init3d and init2d, this issue is taken care of automatically - preserveDrawingBuffer is true on "generate image" runs and false on normal runs.
If you are customising renderer, you will need to manage preserveDrawingBuffer yourself. It will be true by default. You can set it to false:
ABWorld.renderer = new THREE.WebGLRenderer ( { preserveDrawingBuffer: false } );But then your World cannot have a screenshot. So a better approach is to set it to true for "generate image" runs and false for normal runs, which can be done as follows:
if ( AB.isScreenshotRun() ) ABWorld.renderer = new THREE.WebGLRenderer ( { preserveDrawingBuffer : true } ); else ABWorld.renderer = new THREE.WebGLRenderer ( { preserveDrawingBuffer : false } );