t3d-fundamentals

name	t3d-fundamentals
description	Explain and build the core t3d.js rendering loop and first-scene setup. Use when working on t3d basics such as renderer initialization, Scene/Camera/Mesh relationships, starter Geometry and Material choices, basic lighting, the required scene update sequence before rendering, or beginner migration questions from three.js to t3d.

T3D Fundamentals

Focus on the smallest end-to-end path that gets a t3d scene rendering correctly.

Use this skill to help users:

• start a new t3d scene from scratch
• understand the minimal render loop
• choose the first Geometry, Material, Camera, and Light setup
• debug a blank canvas or a scene that does not render
• port basic three.js code without assuming full compatibility

Keep the first pass small. Prefer core exports from t3d before reaching for addons, with OrbitControls as the main default addon exception for interactive scenes.

Read These References

• Treat SKILL.md and references/threejs-migration-pitfalls.md as the highest-priority guardrails for this skill.
• Use references/renderer-flow.md, references/geometry-guide.md, references/material-guide.md, references/shader-guide.md, references/lights-shadows-guide.md, references/lines-curves-guide.md, references/instancing-points-guide.md, references/loaders-guide.md, references/helpers-guide.md, and references/performance-guide.md as the detailed references for explanation, examples, and deeper implementation guidance.
• Always read references/threejs-migration-pitfalls.md before answering any migration question from three.js to t3d, any bug report that sounds like "this API should exist", or whenever the user shows three.js-shaped assumptions.
• Read references/renderer-flow.md when explaining the frame lifecycle, debugging blank or stale renders, or justifying the required scene update sequence.
• Read references/geometry-guide.md when choosing built-in geometry, explaining geometry attributes, introducing custom geometry structure, or using geometry-related addons and builders.
• Read references/material-guide.md when choosing starter materials, mapping material properties, or explaining diffuse, diffuseMap, lighting-sensitive materials, and ShaderMaterial.
• Read references/shader-guide.md when the user needs custom GLSL, built-in uniforms and attributes, shader chunk usage, or a minimal ShaderMaterial example that matches t3d conventions.
• Read references/lights-shadows-guide.md when the user is choosing light types, enabling shadows, tuning shadow quality, or debugging a scene that is too dark or has broken shadows.
• Read references/lines-curves-guide.md when the user needs TubeBuilder, RouteBuilder, curve paths, Bezier curves, line strips, or path-following geometry.
• Read references/instancing-points-guide.md when the user needs GPU instancing, repeated meshes driven by instanceMatrix, point-cloud style rendering, or custom point-based particles.
• Read references/loaders-guide.md when loading glTF, textures, or environment maps, or when wiring Draco / KTX2 support.
• Read references/helpers-guide.md when adding scene-debug helpers such as grids or axes.
• Read references/performance-guide.md when the user asks about memory leaks, disposal, too many draw calls, too many dynamic lights, batching, clustered lighting, or optimization tradeoffs.

Follow This Workflow

1. Identify the runtime shape: plain browser script, npm app, or existing framework app.
2. Build or inspect the pipeline in this order: canvas, WebGL2 context, renderer, render target, scene, mesh, light, camera, frame loop.
3. Verify the t3d-specific update sequence before rendering each frame:
   • scene.updateMatrix()
   • scene.updateRenderStates(camera)
   • scene.updateRenderQueue(camera)
   • renderer.renderScene(scene, camera, renderTarget)
4. If the user is porting from three.js, call out API similarities but do not assume code is drop-in compatible.
5. If the task moves into advanced loaders, animation systems, post-processing, or shader internals, switch to the most specific reference or skill. In particular, move to t3d-effect-composer when the task becomes about composer-managed post-processing or screen-space effects.

Quick Start

Use this as the default first-scene shape for most interactive examples. It keeps the required t3d render flow, but also includes OrbitControls, because camera interaction is part of a practical quick start for most users.

import * as t3d from 't3d';
import { OrbitControls } from 't3d/addons/controls/OrbitControls.js';

let width = window.innerWidth || 2;
let height = window.innerHeight || 2;

const canvas = document.createElement('canvas');
canvas.width = width;
canvas.height = height;
document.body.appendChild(canvas);

const gl = canvas.getContext('webgl2', {
  antialias: true,
  alpha: false
});

const renderer = new t3d.WebGLRenderer(gl);
const renderTarget = new t3d.ScreenRenderTarget(canvas);
renderTarget.setColorClearValue(0.1, 0.1, 0.1, 1);

const scene = new t3d.Scene();

const geometry = new t3d.BoxGeometry(8, 8, );
 material =  t3d.();
 mesh =  t3d.(geometry, material);
scene.(mesh);

 ambientLight =  t3d.();
scene.(ambientLight);

 directionalLight =  t3d.();
directionalLight..(-, , );
directionalLight.( t3d.(),  t3d.(, , ));
scene.(directionalLight);

 camera =  t3d.();
camera..(, , );
camera.( t3d.(, , ),  t3d.(, , ));
camera.( /  * ., width / height, , );
scene.(camera);

 controls =  (camera, canvas);
controls..(, , );

 () {
  (loop);

  mesh.. = count /  * ;
  controls.();

  scene.();
  scene.(camera);
  scene.(camera);

  renderer.(scene, camera, renderTarget);
}
(loop);

 () {
  width = . || ;
  height = . || ;

  camera.( /  * ., width / height, , );

  renderTarget.(width, height);
}
.(, onWindowResize, );

Quick Start Notes

• Prefer installing t3d from npm so code imports, addon resolution, and the local package source all stay aligned.
• In a plain browser example that uses t3d/addons/..., define an importmap in the page head for both t3d and t3d/addons/ before the module script.
• Treat OrbitControls as the default camera-control choice for most interactive examples unless the user explicitly wants a static camera or a different control model.
• Create the WebGLRenderer from a real WebGL2 context.
• Use ScreenRenderTarget for the first visible render path.
• Add at least one visible mesh, one camera, and basic light when using lit materials such as PBRMaterial.
• Set the camera projection explicitly with camera.setPerspective(...).
• Run the three scene update calls before renderer.renderScene(...).
• If the screen is blank, check the render order first before changing materials or geometry.

Important T3D-Specific Guardrails

• Treat scene.updateMatrix(), scene.updateRenderStates(camera), and scene.updateRenderQueue(camera) as required baseline steps for the standard scene render path.
• Do not assume a three.js render loop can be copied into t3d unchanged.
• Prefer npm-style imports such as import * as t3d from 't3d' and import { Something } from 't3d/addons/...' whenever the runtime supports package resolution.
• If the runtime is a plain HTML example without a bundler, define an importmap for t3d and t3d/addons/ rather than mixing direct relative imports with addon files that internally import t3d.
• Prefer small examples using Scene, Camera, Mesh, BoxGeometry, BasicMaterial or PBRMaterial, AmbientLight, DirectionalLight, ScreenRenderTarget, and WebGLRenderer.
• When the user only needs an unlit first render, consider BasicMaterial to reduce lighting variables.
• When the user reports "nothing renders", inspect context creation, camera placement, update order, and whether the object is inside the camera frustum before exploring advanced causes.