Ancient Brain
Code. Play. Teach. Learn. Research. Demo.

Three.js Starter Tutorial

A tutorial to show you how to code JavaScript Worlds on Ancient Brain using the "Three.js" graphics library.



  1. To create Worlds, you need an account.
  2. Use the following link to register. (Link opens in a new tab.)
  3. Register, and get your password via email.
  4. Login.
Register
  
  

  1. We will use "One Cube World" as a simple Starter World.
  2. Click the image to run it.
  3. This World displays a single cube on screen.
  4. You can drag and scroll the camera to move and zoom.


One Cube World (...
730 runs ♦ 2 likes
By Starter user  
Created: 11 Apr 2018
Modified: 3 Sep 2019
Simple starter World (Three.js version). Cube of random color. Built-in camera control.
  
  

  1. Use the link below to go to the "home page" for the Starter World. (Link opens in a new tab.)
  2. Now you are logged in, you can click "Clone" to make your own copy.
  3. Go to the page for your clone.
  4. Check your clone runs.
Starter World
  
  

On the World page for your clone, click "Edit" to launch the editor.
  1. Edit the title.
  2. Edit the description.
  3. Go back to the World page and reload. You will see the new title and description.

  
  

The editor shows the JavaScript code:
 

const skycolor          = 'LightBlue';          // sky color

const objectsize        = 300;                  // size of object   

const startRadius       = 1000;                 // distance from centre we start the camera at

const maxRadius         = startRadius * 10;     // maximum distance from camera we render things 


// the object is a cube (each dimension equal): 
  
var shape             = new THREE.BoxGeometry ( objectsize, objectsize, objectsize );
var theobject         = new THREE.Mesh ( shape );


// Define what the World does at the start of a run: 

AB.world.newRun = function() 
{
    // start a 3D scene: 
    ABWorld.init3d ( startRadius, maxRadius, skycolor ); 

    // add the object to the scene:
    ABWorld.scene.add ( theobject );
};

 
If you have never seen JavaScript (or any program) before, here is what you are looking at:
  1. The program is a set of instructions for the computer to "execute".
  2. This is real JavaScript code. You can write in here anything that can be written in JavaScript.
  3. Instructions end with ";". This is important.
  4. You can insert blank lines, spaces and tabs in order to change the program layout and normally it does not matter. The program will still work the same.
  5. You can insert "comments". These begin with "//" and continue to the end of line. These are notes to the human reader and are ignored by the computer.

There is a lot to learn about JavaScript but you do not need to learn it all before trying some programming.

 
 
 
 

You can change code, press "Save" and then "Run" the new code. Nothing bad can happen. You cannot damage your machine or our server.

Change the following:

  1. Change the sky color. Here is a list of color names.

  2. Change the object size.

  3. Change the start position of the camera.

  4. The shape is defined as a box of three equal dimensions: ( objectsize, objectsize, objectsize ). That is, a cube. Change the shape to something other than a cube by changing one of the dimensions.
Every time you make a change, press Save, and Run again.



This program uses the following structure to define what code runs once at startup, and what code runs every time step:

// Can define global variables and constants up here, outside both functions  
  
AB.world.newRun = function() 
{
	// Instructions to be executed once, at start of run 
};

AB.world.nextStep = function() 
{
	// Instructions to be executed every time step 
};

Note the chain brackets. These define the start and end of blocks of code. In the World so far, we did not define any "AB.world.nextStep" because we did not have any code to execute on every step. For full reference on this structure, see the World and Mind docs.

We will now add some new code at certain locations within the structure.




The cube is "painted" with a random color each time we run the World. It would be nice to paint it with a JPEG or PNG image.

Insert the following code inside "AB.world.newRun". (Remember the program structure above.)

 const texturefile  = "/uploads/starter/earth.1.jpg";
 var   loader       = new THREE.TextureLoader();
 
 loader.load ( texturefile, function ( thetexture ) 
 // this defines a function to be called whenever the file is loaded 
    {			 
        thetexture.minFilter  = THREE.LinearFilter;
        theobject.material    = new THREE.MeshBasicMaterial ( { map: thetexture } );
    }); 

You will now get something like the following:





  1. Web search for some image you want to use. Right-click and "Copy image".
  2. Go to menu "User" - "My uploads".
  3. Paste (Ctrl-V) and the image is uploaded.
  4. You can also select an image from your computer by browsing files.
  5. Edit the JavaScript code to point to the image. You need the exact file name of the image.
  6. Change:
     /uploads/starter/earth.1.jpg 
    to point to your userid and your file:
     /uploads/your-userid/your-file 
  7. The cube will now be painted with your image.


Use other people's uploads

In the header above, in the search box select "Uploads" to see what other people have uploaded. You can use all their uploads in your World.
 
 
 

We want the object to move on every time step. So we must now define "AB.world.nextStep".

Insert the following code at the end of the program. (Remember the program structure above.)

AB.world.nextStep = function()
{
    theobject.position.x = theobject.position.x + AB.randomIntAtoB ( -30, 30 );        
};


Change the movement

  1. The above code makes a random move in the x dimension on each step.
  2. Change the code to make larger or smaller moves.
  3. Change the code to move smoothly in one direction.

  4. Change the code to make moves in 3 dimensions using:
     theobject.position.y 
    and:
     theobject.position.z 



Now we add some background music. Insert the following code at the end of the program.
 const MUSICFILE = '/uploads/starter/SuspenseStrings.mp3';
 AB.backgroundMusic ( MUSICFILE );

On some browsers (Chrome, mobile) audio will not play automatically, but only in response to user interaction. So the code gives the user play and pause buttons.

See notes on audio autoplay on web browsers and in particular on Chrome.


Use your own music

  1. Get some music you like.
  2. One site with free music is dl-sounds.com. There are many others.
  3. When you find music you like, download the music file to your computer.
  4. Then upload the music file to Ancient Brain.
  5. Edit the code to play your music file.



  1. Errors while writing programs are normal. The important thing is to understand where the error is.
  2. The editor warns you about errors using an X icon on the left-hand side. Hover on it for info.
  3. When you save the file, you will be warned again in the pop-up.
  4. Some errors cannot be detected in the editor and you will only find out when you run the program.
  5. Errors found when the program is run are displayed in the JavaScript console. To see the console, press Ctrl-Shift-J on Chrome and Firefox, or F12 on Edge and IE.

    

See the "Docs" menu for all the documentation you need when coding.


There are more ways of getting help:

 
 
 
 

Clone other Starter Worlds and change them. See:

Many of the Starter Worlds have a section of code called a "tweaker's box" at the top. This contains the easiest parts of code to change.

For example, Blank Three.js World is quite simple to edit. It has multiple sphere objects, stored in a structure called an Array.

When you get more advanced, you will make your own entire Worlds. The Worlds you create are only limited by your imagination.


Blank Three.js World
870 runs ♦ 2 likes
By Starter user  
Created: 20 Nov 2016
Modified: 3 Sep 2019
A simple starter World. An Array of spheres. Painted with textures. Random motion.
 
 
 

Show it off

  1. The system will generate an image to represent your World. To change it, see "New image" on the World page.
  2. The site works on mobile. Show off your World to people on your mobile. For some Worlds, touch will automatically drag and zoom the World's camera.
  3. People can find your World using the search box. So give it a good name.
  4. You can embed your World on another website. See "Embed code" on the World page.
  5. Comment on other people's Worlds. The top menu turns red when you have a new comment.