← Back to Documentation Index

🎮 3D Graphics API

Complete 3D rendering system using Three.js for meshes, materials, lighting, and cameras

📋 Overview

The 3D Graphics API provides a complete Three.js-powered 3D rendering system with mesh management, primitive shapes, material system, lighting, and GLB model loading.

💡 Key Features
  • Mesh Management – ID-based system for creating and destroying 3D objects
  • Primitives – Cube, sphere, plane, cylinder, cone, capsule, torus
  • Material System – PBR materials with metalness, roughness, and environment map reflections
  • Transforms – setPosition, setRotation, setScale, rotateMesh, getPosition
  • Model Loading – GLB/GLTF model support with async loading
  • Lighting – Directional, point, and ambient lights with fog

🎨 Mesh Creation

createCube(size, color, position, options)

Creates a cube mesh with the specified properties.

size number - Cube dimensions (default: 1)
color hex number - Color in hex format (e.g., 0xff0000 for red)
position array [x, y, z] - Initial position (default: [0, 0, 0])
options object - Material options (metalness, roughness, etc.)
Returns: number - Mesh ID for later reference
Example:
const cubeId = createCube(2, 0xff0000, [0, 1, 0], { metalness: 0.5 });
createSphere(radius, color, position, segments, options)

Creates a sphere mesh.

radius number - Sphere radius (default: 1)
color hex number - Sphere color
position array [x, y, z] - Initial position
segments number - Detail level (default: 8)
options object - Material options
Returns: number - Mesh ID
Example:
const ballId = createSphere(1.5, 0x00ff00, [5, 2, 0], 16);
createPlane(width, height, color, position)

Creates a flat plane mesh (ground, walls, etc.).

width number - Plane width
height number - Plane height
color hex number - Plane color
position array [x, y, z] - Initial position
Returns: number - Mesh ID
Example:
const groundId = createPlane(100, 100, 0x808080, [0, -1, 0]);
createCylinder(radiusTop, radiusBottom, height, color, position, options?)

Creates a cylinder (or truncated cone when radii differ).

radiusTop number – Top face radius
radiusBottom number – Bottom face radius (set equal to radiusTop for a true cylinder)
height number – Cylinder height
color hex number – Colour
position array [x,y,z] – World position
options object – Material options
Returns: number – Mesh ID
Example
const pillar = createCylinder(0.5, 0.5, 4, 0x888888, [3, 2, 0]);
const barrel = createCylinder(0.6, 0.8, 1.2, 0x8B4513, [0, 0.6, 5]);
createCone(radius, height, color, position, options?)

Creates a cone — useful for projectiles, trees, directional indicators, and hat shapes.

radius number – Base radius
height number – Cone height
color hex number – Colour
position array [x,y,z] – World position
options object – Material options
Returns: number – Mesh ID
Example
const tree = createCone(1.5, 4, 0x228b22, [0, 2, -5]);
const bullet = createCone(0.1, 0.4, 0xffff00, [px, py, pz]);
createCapsule(radius, height, color, position, options?)

Creates a capsule (cylinder capped with hemispheres) — ideal for humanoid character bodies and rounded obstacles.

radius number – Hemisphere radius
height number – Total capsule height (including caps)
color hex number – Colour
position array [x,y,z] – World position
options object – Material options
Returns: number – Mesh ID
Example
const player = createCapsule(0.4, 1.8, 0x4488ff, [0, 0.9, 0]);
createTorus(radius, tube, color, position, options?)

Creates a torus (donut shape) — good for rings, portals, halos, and pickup items.

radius number – Distance from the torus centre to the tube centre
tube number – Tube radius
color hex number – Colour
position array [x,y,z] – World position
options object – Material options
Returns: number – Mesh ID
Example
const ring = createTorus(2, 0.3, 0xffd700, [0, 5, 0]); // golden ring portal

🔧 Mesh Management

getMesh(meshId)

Retrieves a mesh object by its ID for direct manipulation.

meshId number - ID returned from create function
Returns: THREE.Mesh - Three.js mesh object
Example:
const mesh = getMesh(cubeId);
mesh.rotation.y += 0.01;
destroyMesh(meshId)  ·  removeMesh(meshId)

Removes a mesh from the scene and frees its GPU resources. Both names are identical — either works.

meshId number - Mesh ID to destroy
Returns: void - No return value
Example:
destroyMesh(cubeId); // or removeMesh(cubeId) — both are identical
setMeshVisible(meshId, visible)

Shows or hides a mesh without removing it from the scene.

meshId number – Mesh ID
visible boolean – true to show, false to hide
Example
setMeshVisible(ghostId, false); // hide without destroying
setMeshVisible(ghostId, true);  // show again

🔄 Transforms

setPosition(meshId, x, y, z)

Moves a mesh to an absolute world position.

meshId number – Mesh ID
x, y, z number – World coordinates
Example
setPosition(enemyMesh, enemy.x, enemy.y, enemy.z);
setRotation(meshId, rx, ry, rz)

Sets the absolute rotation of a mesh (Euler angles in radians).

meshId number – Mesh ID
rx, ry, rz number – Rotation angles in radians
Example
setRotation(wheelId, 0, 0, Math.PI / 2);
rotateMesh(meshId, dx, dy, dz)

Adds to the current rotation of a mesh each frame — ideal for spin animations.

meshId number – Mesh ID
dx, dy, dz number – Rotation delta in radians (typically dt * speed)
Example
// In update(dt):
rotateMesh(orbId, 0, dt * 1.5, 0); // spin around Y axis
setScale(meshId, sx, sy, sz)

Scales a mesh along each axis.

meshId number – Mesh ID
sx, sy, sz number – Scale factors
Example
setScale(hitboxId, 2, 0.5, 2); // flatten and widen
getPosition(meshId)

Returns the current world position of a mesh.

Returns: [x, y, z]
Example
const [x, y, z] = getPosition(bulletMesh);

📦 Model Loading

loadModel(url, position, scale)

Loads a GLB/GLTF 3D model asynchronously.

url string - Path to .glb or .gltf file
position array [x, y, z] - Model position (default: [0,0,0])
scale number - Uniform scale multiplier (default: 1)
Returns: Promise - Promise resolving to mesh ID
Example:
const modelId = await loadModel("/models/character.glb", [0, 0, 0], 2);

💡 Lighting

setLightDirection(x, y, z)

Sets the direction of the scene's main directional light (like the sun). The vector points toward the light source.

x, y, z number – Light direction vector
Example
setLightDirection(-0.5, -1, -0.3); // angled overhead sun
setLightColor(color)

Sets the colour of the main directional light.

color hex number – Light colour
Example
setLightColor(0xffffdd); // warm daylight
setLightColor(0x4444aa); // cool moonlight
setAmbientLight(color, intensity?)

Sets the overall scene ambient lighting — fills in shadows and ensures dark areas are still visible.

color hex number – Ambient colour
intensity number – Strength (default: 1.0)
Example
setAmbientLight(0x404060, 0.8); // cool, slightly dim fill light
createPointLight(color, intensity, distance, x, y, z)

Creates a positional point light that casts light in all directions from a specific world position — flames, lamps, explosions.

color hex number – Light colour
intensity number – Brightness
distance number – Max range (0 = unlimited)
x, y, z number – World position
Returns: number – Light ID (pass to setPointLightPosition, removeLight)
Example
const torchLight = createPointLight(0xff8800, 2, 15, torchX, torchY, torchZ);
// Later, move it:
setPointLightPosition(torchLight, newX, newY, newZ);
// Remove:
removeLight(torchLight);
setFog(color, near, far)

Enables distance fog, fading objects to color between near and far world units.

color hex number – Fog colour (usually matches your skybox)
near number – Distance at which fog starts
far number – Distance at which objects are fully invisible
Example
setFog(0x202040, 30, 80);  // atmospheric night fog
clearFog();                // remove fog entirely

🔮 PBR Materials

Physically Based Rendering properties can be applied to any mesh after creation to achieve metallic, rough, or reflective looks.

setPBRProperties(meshId, options)

Applies PBR material properties to an existing mesh. Works best when an image skybox is set (provides IBL reflections).

meshId number – Target mesh ID
options.metalness number – 0 = dielectric, 1 = fully metallic
options.roughness number – 0 = mirror smooth, 1 = fully matte
options.envMapIntensity number – Strength of environment reflections (default: 1.0)
options.color hex number – Override material colour
Example — PBR material grid
// Mirror-like chrome ball
const chrome = createSphere(1, 0xffffff, [0, 1, 0]);
setPBRProperties(chrome, { metalness: 1.0, roughness: 0.0 });

// Brushed metal
const brushed = createSphere(1, 0xaaaaaa, [3, 1, 0]);
setPBRProperties(brushed, { metalness: 1.0, roughness: 0.5 });

// Matte rubber
const rubber = createSphere(1, 0x222222, [6, 1, 0]);
setPBRProperties(rubber, { metalness: 0.0, roughness: 1.0 });
💡 Getting the best results

Call createImageSkybox() in your init() before adding PBR meshes. The skybox is used as an environment map — metallic and smooth surfaces will reflect it realistically.