← 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
  • Primitive Shapes - Cubes, spheres, planes with N64-style materials
  • Material System - PBR materials with color, texture, and metalness
  • Model Loading - GLB/GLTF model support with async loading
  • Lighting - Directional, point, and ambient lights with shadows

🎨 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]);

🔧 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)

Removes a mesh and frees its resources.

meshId number - Mesh ID to destroy
Returns: void - No return value
Example:
destroyMesh(cubeId); // Clean up

📦 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

addDirectionalLight(color, intensity, position)

Adds a directional light (like the sun).

color hex number - Light color
intensity number - Light strength (0-1)
position array [x, y, z] - Light direction
Returns: THREE.Light - Light object
Example:
addDirectionalLight(0xffffff, 1.0, [10, 20, 5]);
addAmbientLight(color, intensity)

Adds ambient light (overall scene brightness).

color hex number - Light color
intensity number - Light strength
Returns: THREE.Light - Light object
Example:
addAmbientLight(0x404040, 0.5);