Getting started

By the end of this tutorial, you will know how to create this kind of panel in your Three.js projects :

live demo of the above scene

setup

What you need before to get started :
- node.js (server environment in JavaScript)
- NPM (package manager for node.js)
- GIT (version control manager)

get the minimal three.js app

As three-mesh-ui is designed to work on top of a normal three.js workflow, we will start this tutorial by cloning a minimal Three.js VR application.

• Go to this repository, click on Clone or download, and copy the url which appears.

• Open a terminal on your computer (command prompt) and navigate to the directory where you want your app directory the be, then type git clone + the url you copied.

• Once the app is cloned, navigate to its directory, then type npm install in your terminal.

By the end of this step, you have a working minimal three.js VR app, that you can run locally by typing npm start in your terminal in the app directory, which should open a window of your default browser at the adress http://localhost:8080/

It is VR-ready, so if you visit this page with a VR headset, you can press the "Enter VR" button and start immersion.

You should see this :

install three-mesh-ui

• In your terminal, type npm install three-mesh-ui, which will install three-mesh-ui in the node_modules directory as a dependency of your project.

• In your preferred code editor, open src/index.js, which contains the entirety of the Three.js code of this app, we will only work on this file.

create a three-mesh-ui panel

• Near the import statements at the top of the file, import three-mesh-ui :

import ThreeMeshUI from 'three-mesh-ui'

• You must tell three-mesh-ui when to update. Just add this line at the beginning of the loop function:

ThreeMeshUI.update();

From now on, we will only write in the makeUI() function.

• Create a Block, position it, rotate it, then add it to the THREE.Scene :

const container = new ThreeMeshUI.Block({
	height: 1.5,
	width: 1
});

container.position.set( 0, 1, -1.8 );
container.rotation.x = -0.55;
scene.add( container );

This is what you should see :

add sub-blocks

• Create two new blocks, that will contain a picture and some text :

const imageBlock = new ThreeMeshUI.Block({
	height: 1,
	width: 1,
	offset: 0.1 // distance separating the inner block from its parent
});

const textBlock = new ThreeMeshUI.Block({
	height: 0.4,
	width: 0.8,
	margin: 0.05, // like in CSS, horizontal and vertical distance from neighbour
	offset: 0.1 // distance separating the inner block from its parent
});

container.add( imageBlock, textBlock );

This is what you should see :

add an image to a block

• Instantiate a THREE.TextureLoader :

const loader = new THREE.TextureLoader();

• Load an image, then pass it to a Block as backgroundTexture attribute :

loader.load( './assets/spiny_bush_viper.jpg', (texture)=> {

	imageBlock.set({ backgroundTexture: texture });

});

This is what you should see :

add text

• Before to add text to a Block, it needs a font. Add a font and choose a text type :

container.set({
	fontFamily: './assets/Roboto-msdf.json',
	fontTexture: './assets/Roboto-msdf.png',
});

Note that when a Block does not have any font assigned, it look at the parent's font, that's why we are assigning this font to the container Block.

Learn more about font files and how to create your own fonts.

• Add a Text component with some content :

const text = new ThreeMeshUI.Text({
	content: 'The spiny bush viper is known for its extremely keeled dorsal scales.'
});

textBlock.add( text );

style the text

• Set the font material and size :

text.set({
	fontColor: new THREE.Color( 0xd2ffbd ),
	fontSize: 0.04
});

• Tell the text container where to render the text :

textBlock.set({
	// alignContent: 'right', // could be 'center' or 'left'
        // alignContent has been deprecated, rely on alignItems or textAlign
        textAlign: 'right',
	justifyContent: 'end', // could be 'start', 'center', 'end', 'space-between', 'space-around', 'space-evenly'  
	padding: 0.03
});

This is what you should see :

add more text to the same paragraph

textBlock.add(
	new ThreeMeshUI.Text({
		content: ' Mind your fingers.',
		fontSize: 0.07,
		fontColor: new THREE.Color( 0xefffe8 )
	})
);

This is what you should see :

that's it

To prepare this app for production, type npm run build in your terminal, and serve the content of the /dist folder. (for instance in Github Pages)

It's all it takes to add user interfaces to your VR experiences.
The final code of this tutorial is available here, and a live demo is available here.

Now that you grasped the basics, you can learn more advanced technics by browsing the examples and studying their code. It is helpful to read the API documentation to learn more about the different attributes you can use to style your user interfaces.