Drag the background!

API: Three (AB) (r3)

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:

  • Includes Three.js release 127.

  • Includes the following libraries for loading 3D models:

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

Global variables

This API defines the following global variables:
 

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

The "ABWorld" object

The "ABWorld" object has the following public data, shown with default values where possible:

 

   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

The "ABHandler" object implements mouse and touch event handling. The default is that mouse and touch control the camera, but this can be overridden.

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:


Touch World
424 runs ♦ 1 like
By Starter user  
Created: 6 Jan 2018
Modified: 18 Apr 2021
How to override default touch handling. Mobile: Touch drag moves agent, touch pinch zooms camera...
Zombie Death Baby
716 runs ♦ 1 like
By Starter user  
Created: 11 Jun 2018
Modified: 4 Jul 2021
How to make a fun touch game for mobile. Touch drag and tap objects. Mouse drag and click object...

2D or 3D graphics

2D scenes are merely special cases of 3D scenes. The World initialises the scene by calling one of the following:
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.


Touch World
424 runs ♦ 1 like
By Starter user  
Created: 6 Jan 2018
Modified: 18 Apr 2021
How to override default touch handling. Mobile: Touch drag moves agent, touch pinch zooms camera...
Complex World
7389 runs ♦ 3 likes
By Starter user  
Created: 1 Oct 2016
Modified: 18 Apr 2021
World with a Mind-controlled agent, actively-pursuing enemy, random maze, skybox, music.

Optional: Customising scene, camera, renderer

The functions init3d and init2d create default forms of scene, camera and renderer. If you want a customised form of these, define the variable before calling init3d or init2d, and then your version will be used, not the default. Example:
 
ABWorld.renderer = new THREE.WebGLRenderer ( { antialias: true } );
ABWorld.init3d ( startRadius, maxRadius, color ); 

Optional: With custom renderer, set preserveDrawingBuffer for performance

If you are not customising renderer, but rather using init3d and init2d, then ignore this section.

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 } );

Templates


Examples

Examples of Worlds that use this API:


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

The background is a program, showing the JavaScript graphics used on this site.
The globes light up when you log in.
 
Font:

Users retain ownership of user content.

Platforms      Stats      The name      Terms and conditions

Call for partners      Contact

Call for partners!
Ancient Brain is looking for partners. In particular, we seek a partner in writing a JavaScript coding book for schools, to be used worldwide. We will integrate your course into the Ancient Brain site. This is an opportunity for someone looking to develop a course and textbook to partner with a site to promote it. Read more.