API: Three 1.0

3D Worlds. Three.js release 80. jQuery 1.12.4.


This API has the following features:

  • Based on Three.js release 80. (Three.js continues to develop. But this API stays at this version so runs will never break.)
  • 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:
 

 threeworld;       // instance of class ThreeWorldClass - basic functionality for this API
 threehandler;     // instance of class ThreeHandlerClass - mouse and touch handling for this API
 

The "threeworld" object

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

 

   threeworld.camera;       // Three.js camera: THREE.PerspectiveCamera                 
   threeworld.renderer;     // Three.js renderer: THREE.WebGLRenderer
   threeworld.scene;        // Three.js scene: THREE.Scene 
	
	
 // draw camera control buttons (Track/Move/Normal) or not 
 
   threeworld.drawCameraControls = true; 	 
	
	
 // change these points to control camera movement:
  
   threeworld.follow;               // THREE.Vector3          
   threeworld.lookat;               // THREE.Vector3        

	  // when camera is in "Track" mode, it will look at threeworld.follow
	  // when camera is in "Move" mode, it will position at threeworld.follow,
	  //   and look at threeworld.lookat
	 


The "threeworld" object has the following public methods:

 

// start a 3D or 2D scene with camera on the canvas:		

   threeworld.init3d ( startRadius, maxRadius, color );   
   threeworld.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
 
   threeworld.cameraTrack(); 
   threeworld.cameraMove();
   threeworld.cameraFixed();

	 
// Useful functions for finding size of loaded 3D objects.
// Size of object along each dimension.

   threeworld.objectXsize ( theobject );
   threeworld.objectYsize ( theobject );
   threeworld.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.

   threeworld.hitsObject ( x, y, theobject );		 // boolean 

See Three.js documentation.

The "threehandler" object

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

The "threehandler" 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:

   threehandler.SCROLLFACTOR = 1;          	 

// multiply touch pinch by some factor to increase/decrease how much camera zooms:

   threehandler.PINCHFACTOR  = 1;           	 	
	
// for 2D worlds, multiply mouse (or touch) drag by some factor to increase/decrease how much camera moves:
 
   threehandler.DRAGFACTOR   = 1;            	 

   
// maximum position of camera:

   threehandler.MAXCAMERAPOS;    // given some sensible default depending on World   

   
// does a "ground" exist at altitude zero (that camera should not zoom below):

   threehandler.GROUNDZERO = false;
	


The "threehandler" object defines the following functions for mouse and touch events to move the camera by default. To override this, and do your own mouse and touch event handling, simply redefine these functions:

 

  threehandler.initMouseDrag = function ( x, y )  { your code };    
    // start drag now, at screen position x,y   

  threehandler.mouseDrag     = function ( x, y )  { your code };   
    // drag went to new screen position x, y  
 
  threehandler.mouseZoom     = function ( delta ) { your code };
    // 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  

	
  threehandler.initTouchDrag = function ( x, y )  { your code };
  threehandler.touchDrag     = function ( x, y )  { your code };
  threehandler.touchZoom     = function ( delta ) { your code };
    


Examples of Worlds that over-ride the default mouse and/or touch actions:


Zombie Death Baby
155 runs ♦ 0 likes
Starter user
How to make a fun touch game for mobile. Touch drag and tap objects. Mouse drag and click object...
Touch World
206 runs ♦ 1 likes
Starter user
How to override default touch handling. Mobile: Touch drag moves agent, touch pinch zooms camera...

2D or 3D graphics

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


Complex World
1558 runs ♦ 2 likes
Starter user
World with a Mind-controlled agent, actively-pursuing enemy, random maze, skybox, music.
Touch World
206 runs ♦ 1 likes
Starter user
How to override default touch handling. Mobile: Touch drag moves agent, touch pinch zooms camera...

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:
 
threeworld.renderer = new THREE.WebGLRenderer ( { antialias: true } );
threeworld.init3d ( startRadius, maxRadius, color ); 

Note if you are customising renderer: To be able to generate World image screenshots, you need:

 
threeworld.renderer = new THREE.WebGLRenderer ( { preserveDrawingBuffer: true } );	


Examples

Examples of Worlds that use this API:


Blank Three.js World
521 runs ♦ 2 likes
Starter user
A simple starter World. An Array of spheres. Painted with textures. Random motion.
One Cube World
456 runs ♦ 2 likes
Starter user
Simplest possible starter World. Background color. A cube of random color.
Simple World
845 runs ♦ 2 likes
Starter user
Simple World with a Mind-controlled agent, randomly-moving enemy, paint blocks with texture.

The background is a program, showing the JavaScript graphics used on this site.
 
Font:

© Ancient Brain Ltd. All rights reserved.

Ancient Brain ™ is a trademark of Ancient Brain Ltd.

Beta      Bug bounty      Contact      Stats      The name      Terms and conditions