This guide builds a small 3D showroom. A camera orbits a pedestal with a spinning box on it. A grid, a sphere, and a cube are drawn directly each frame, and a model can stand behind the pedestal. You light the scene and add a line of text on top.
BornEngine has two ways to put 3D things on screen, and this guide uses both. Each section adds one piece. The last section has the complete main.ts.
What you will build
- A camera you orbit with
LeftandRightand move closer or farther withUpandDown. - A grid, a red sphere, and a green cube drawn in immediate mode.
- A pedestal and a spinning box made from retained scene nodes.
- A directional light and an ambient light.
- A text overlay with the number of scene nodes.
- An optional model file that appears when it exists.
Two ways to draw
- Immediate mode: you call a draw method such as
drawCube()every frame. Nothing is kept. If you stop calling it, the shape is gone. Use it for prototypes, debug shapes, and things that change every frame. - Retained mode: you create a scene node once and set its shape, color, and place. The engine draws it every frame until you hide or dispose it. Use it for the permanent parts of a scene. Nodes are objects from
game.sceneGraph.
The world is right-handed, with +Y up, and its unit is the meter. A rotation about the Y axis is called a yaw, and it is measured in radians.
Setup
Create a project that can load models, and a folder for them:
bornengine new Showroom --game-type 2.5d
cd Showroom
mkdir -p assets/modelsThe 2.5d profile includes model loading. The default 2d profile does not, so loadModel would report a failed load. The 3d profile adds the physics library as well, which this guide does not need. See Project commands for the profiles.
The model is optional. To see it, put a glTF or GLB file at assets/models/statue.glb. Without the file the scene still runs, and the program prints a warning.
Game loop
A 3D frame follows the same steps as a 2D frame. loop(deltaTime) changes state, and render() clears the screen and draws. In render(), you give the renderer a camera, draw 3D things, and end the pass. Text and other 2D drawing come after the pass.
This is a complete main.ts with an orbiting camera and three immediate-mode shapes:
import { Colors, Game } from '@bornengine/engine';
import type { Camera3D } from '@bornengine/engine';
class OrbitGame extends Game {
private yaw = 0;
constructor() {
super({ window: { title: 'Orbit', width: 1024, height: 576 }, targetFps: 60 });
}
protected override loop(deltaTime: number): void {
this.yaw += deltaTime * 0.5;
}
protected override render(): void {
this.renderer.clear({ r: 20, g: 26, b: 38, a: 255 });
const camera: Camera3D = {
position: { x: Math.sin(this.yaw) * 10, y: 5, z: Math.cos(this.yaw) * 10 },
target: { x: 0, y: 1, z: 0 },
up: { x: 0, y: 1, z: 0 },
fovy: 45,
projection: 'perspective',
};
if (this.renderer.begin3D(camera)) {
this.renderer.drawGrid(20, 1);
this.renderer.drawCube({ x: -3, y: 0.5, z: 0 }, { x: 1, y: 1, z: 1 }, Colors.GREEN);
this.renderer.drawSphere({ x: 3, y: 0.5, z: 0 }, 0.5, Colors.RED);
this.renderer.end3D();
}
this.renderer.drawText('Orbiting camera', { x: 16, y: 16 }, 18, Colors.WHITE);
}
}
new OrbitGame().run();Run it with bornengine run main.ts.
How it works:
- A
Camera3Dhas aposition, atargetit looks at, anupdirection, a field of viewfovyin degrees, and aprojection:'perspective'or'orthographic'. With an orthographic camera,fovyis the height of the view in world units. Geometry nearer than 0.01 or farther than 1000 units is not drawn. begin3D(camera)starts the 3D pass and returnsfalseif it cannot, for example when a pass is already open.end3D()closes it. Always pair them, and draw 3D things between them.drawGrid(slices, spacing),drawCube(position, size, color), anddrawSphere(position, radius, color)take the center of the shape. A cube of height 1 aty: 0.5rests on the grid.drawTextafterend3D()draws in window pixels on top of the picture.- The camera moves on a circle.
yawgrows each frame, and the sine and cosine place the camera. Multiplying bydeltaTimekeeps the speed the same at any frame rate.
Retained scene nodes
A node starts empty. You give it a shape and a material, and you place it. The next module has two helpers. addBox makes a box by extruding a rectangle upward. addModel loads a model file and puts it in a node.
import { Game } from '@bornengine/engine';
import type { Color, SceneNode } from '@bornengine/engine';
function addBox(
game: Game,
name: string,
width: number,
depth: number,
height: number,
color: Color,
roughness: number,
metalness: number,
): SceneNode {
const node = game.sceneGraph.createNode({ name });
if (!node.isLoaded) throw new Error(node.error ?? 'Could not create the scene node ' + name);
const x = width / 2;
const z = depth / 2;
node.extrudePolygon(
[
{ x: -x, y: 0, z: -z },
{ x, y: 0, z: -z },
{ x, y: 0, z },
{ x: -x, y: 0, z },
],
height,
);
node.setColor(color);
node.setPbr(roughness, metalness);
return node;
}
function addModel(game: Game, path: string, x: number, y: number, z: number): SceneNode | null {
const model = game.assets.loadModel(path);
if (model === null || !model.isLoaded) return null;
const node = game.sceneGraph.createNode({ name: path });
if (!node.isLoaded || !node.attachModel(model)) return null;
node.setTrs({ x, y, z }, 0, 1);
return node;
}createNode()returns a node even when something goes wrong. Checknode.isLoaded, and readnode.errorwhen it isfalse.extrudePolygon(points, depth)fills the outline you give it with a solid that extends fromy = 0up toy = depth. It uses thexandzof each point. The engine calculates normals and texture coordinates. For other shapes,updateGeometry(vertices, indices)takes your own mesh: 12 numbers per vertex (position, normal, color, and texture coordinates).setColor(color)tints the node with 0 to 255 channels.setPbr(roughness, metalness)sets the material. PBR means physically based rendering: a roughness near 0 gives a mirror-like surface, and a metalness near 1 gives a metal.setTrs(position, yaw, scale)places a node with a position, a rotation about the Y axis in radians, and one uniform scale. For any other rotation or a non-uniform scale, callsetTransform(matrix)with a column-major matrix of 16 numbers.attachModel(model)draws a loaded model through the node.game.assets.loadModel(path)caches the model by path, as it does for textures. Always checkisLoaded: a missing file or a project without model support gives a model that did not load.- Nodes belong to the game and are drawn on every frame. Call
node.setVisible(false)to hide one. Callnode.dispose()to remove one, which also removes its children. The game disposes the rest when it stops.game.sceneGraph.nodeCountcounts the live nodes.
Lights
The renderer clears its lights at the start of every frame. Add your lights from render(), every frame, before you begin the 3D pass:
import { Game } from '@bornengine/engine';
function applyLights(game: Game): void {
game.sceneGraph.setAmbientLight({ r: 255, g: 255, b: 255, a: 255 }, 0.25);
game.sceneGraph.addDirectionalLight({ x: 0.4, y: 1, z: 0.3 }, { r: 255, g: 244, b: 224, a: 255 }, 0.9);
}setAmbientLight(color, intensity)lights every surface equally, so that shadowed sides are not black.addDirectionalLight(direction, color, intensity)is a light that is infinitely far away, like the sun. The direction points from the scene toward the light, so(0.4, 1, 0.3)is a light above the scene. It does not need to be normalized.addPointLight(position, range, color, intensity)adds a light that fades to nothing atrange.
Complete example
Replace main.ts with this file:
import { Colors, Game, Key, Mathf } from '@bornengine/engine';
import type { Camera3D, Color, SceneNode } from '@bornengine/engine';
function addBox(
game: Game,
name: string,
width: number,
depth: number,
height: number,
color: Color,
roughness: number,
metalness: number,
): SceneNode {
const node = game.sceneGraph.createNode({ name });
if (!node.isLoaded) throw new Error(node.error ?? 'Could not create the scene node ' + name);
const x = width / 2;
const z = depth / 2;
node.extrudePolygon(
[
{ x: -x, y: 0, z: -z },
{ x, y: 0, z: -z },
{ x, y: 0, z },
{ x: -x, y: 0, z },
],
height,
);
node.setColor(color);
node.setPbr(roughness, metalness);
return node;
}
function addModel(game: Game, path: string, x: number, y: number, z: number): SceneNode | null {
const model = game.assets.loadModel(path);
if (model === null || !model.isLoaded) return null;
const node = game.sceneGraph.createNode({ name: path });
if (!node.isLoaded || !node.attachModel(model)) return null;
node.setTrs({ x, y, z }, 0, 1);
return node;
}
function applyLights(game: Game): void {
game.sceneGraph.setAmbientLight({ r: 255, g: 255, b: 255, a: 255 }, 0.25);
game.sceneGraph.addDirectionalLight({ x: 0.4, y: 1, z: 0.3 }, { r: 255, g: 244, b: 224, a: 255 }, 0.9);
}
class ShowroomGame extends Game {
private yaw = 0.6;
private distance = 12;
private spin = 0;
private spinner: SceneNode | null = null;
constructor() {
super({ window: { title: 'Showroom', width: 1024, height: 576 }, targetFps: 60 });
}
protected override onStart(): void {
addBox(this, 'Pedestal', 2, 2, 0.5, { r: 176, g: 124, b: 70, a: 255 }, 0.35, 0.8);
this.spinner = addBox(this, 'Spinner', 1, 1, 1, { r: 70, g: 150, b: 220, a: 255 }, 0.5, 0.1);
this.spinner.setTrs({ x: 0, y: 0.5, z: 0 });
if (addModel(this, 'assets/models/statue.glb', 0, 0, -4) === null) {
console.warn('The statue is off: could not load assets/models/statue.glb');
}
}
protected override loop(deltaTime: number): void {
if (this.input.isKeyDown(Key.LEFT)) this.yaw -= deltaTime;
if (this.input.isKeyDown(Key.RIGHT)) this.yaw += deltaTime;
if (this.input.isKeyDown(Key.UP)) this.distance -= 6 * deltaTime;
if (this.input.isKeyDown(Key.DOWN)) this.distance += 6 * deltaTime;
this.distance = Mathf.clamp(this.distance, 4, 24);
this.spin += deltaTime;
if (this.spinner !== null) this.spinner.setTrs({ x: 0, y: 0.5, z: 0 }, this.spin, 1);
}
protected override render(): void {
this.renderer.clear({ r: 20, g: 26, b: 38, a: 255 });
applyLights(this);
const camera: Camera3D = {
position: { x: Math.sin(this.yaw) * this.distance, y: 5, z: Math.cos(this.yaw) * this.distance },
target: { x: 0, y: 1, z: 0 },
up: { x: 0, y: 1, z: 0 },
fovy: 45,
projection: 'perspective',
};
if (this.renderer.begin3D(camera)) {
this.renderer.drawGrid(20, 1);
this.renderer.drawSphere({ x: 3, y: 0.5, z: 0 }, 0.5, Colors.RED);
this.renderer.drawCube({ x: -3, y: 0.5, z: 0 }, { x: 1, y: 1, z: 1 }, Colors.GREEN);
this.renderer.end3D();
}
this.renderer.drawText('Left/Right: orbit Up/Down: zoom', { x: 16, y: 16 }, 18, Colors.WHITE);
this.renderer.drawText('Scene nodes: ' + this.sceneGraph.nodeCount, { x: 16, y: 40 }, 18, Colors.LIGHTGRAY);
}
}
new ShowroomGame().run();Run it with bornengine run main.ts. The blue box spins on the pedestal, and the camera orbits.
What each part does:
onStart()creates the permanent parts once: the pedestal, the spinner, and the optional statue. A game’sonStartruns after the window exists, so creating nodes there is safe.loop()reads the keys and updates numbers. It moves the spinner by callingsetTrswith a new yaw. Retained nodes change only when you call a method on them.render()clears, applies the lights, and runs the 3D pass. The retained nodes draw with the camera frombegin3D. For that reason, callbegin3Dandend3Devery frame, even if you draw no immediate shapes between them.- The grid, the sphere, and the cube are redrawn every frame. They are gone from any frame where you do not draw them.
- The two lines of text are 2D drawing after the 3D pass.
Limits to know
- A model needs a project with model support. In a
2dproject,loadModelreports a failed load. - Leave the
renderModeoption out, or set it to'3d'or'2.5d'. WithrenderMode: '2d'the engine uses a faster 2D path that skips retained nodes. - Do not start a pass inside another pass. Calling
begin3Dwhile a 2D or 3D pass is open returnsfalse. - Retained nodes belong to the
Game, not to aScene. Changing the active scene does not remove them.
Next steps
- Scene graph API covers the node hierarchy, geometry, materials, lights, and picking.
- Models API covers loading models and creating meshes, materials, and animations.
- Skeletal animation plays animated characters.
- Add physics gameplay puts bodies into a 3D scene.
- Organize assets and worlds loads a whole level from a world file.