Taos Engine — API Documentation

This folder is the practical reference for using the Taos engine: the calls you make to wire up a renderer, drive a scene, and reach into the engine's specialized subsystems. It is the API counterpart to the companion book, which covers the theory behind how the engine is built.

Book (book/) — why the engine is shaped the way it is.
Docs (this folder) — how to call it.

Start here#

Features Overview #

A visual, categorized tour of everything the engine can do — in the spirit of a product features page. Every feature card links to a runnable in-browser demo. Open docs/features.html directly in a browser (or via the docs site).

API Quick-Start Guide #

The core guide. It walks the three API layers (engine + preset, engine + features, manual render graph), a complete runnable "Hello, Cube" project, the GameObject / Component / Scene / Camera / Mesh / Material model, the render presets, the per-frame hooks, and cleanup. Read it before the module guides — they all build on it.

Module guides#

Each guide below documents one subsystem: its public API surface, the typical setup sequence, real code pulled from the samples, and the gotchas worth knowing before you start. They are independent — read whichever you need.

Guide	Module	What it covers
Core	`src/index.ts`	The top-level `taos` barrel: math primitives (Vec/Mat/Quaternion, noise, random), assets (`Mesh`, `Texture`, `GltfLoader`), input controllers (mouse/touch/gamepad), glTF animation, the full render-feature catalog, and the renderer core (`RenderContext`, `PbrMaterial`). The reference map for everything in `import … from 'taos/index.js'`.
Audio	`src/audio/`	Mixing buses, one-shot and spatial SFX, looping music with crossfade, an insertable effects rack (reverb/filter/delay/distortion/compressor), microphone capture, and FFT/level analysis. Plus the `AudioSource` / `AudioListener` scene components.
SDF	`src/sdf/`	Baking a signed distance field from a mesh into a 3D texture (`SdfVolume`), the CPU math helpers, and binding an SDF to a particle system for surface spawning, attraction, collision, and sticking.
Terrain	`src/terrain/`	The `TerrainSystem` CDLOD heightmap renderer: procedural or image-driven heights, virtual-texture page streaming, PBR layer splatting, quality presets, and the render-graph feature wiring.
Geo	`src/geo/`	Floating-origin (f64) geospatial rendering: `GeoFrame` / `GeoScene` / `GeoFeature`, Cesium ion + Google + MapTiler data sources, 3D Tiles and quantized-mesh terrain streaming, anchors, water, and attribution.
Physics	`src/physics/`	The Jolt WASM rigid-body backend: `PhysicsWorld` body factories (box/sphere/mesh/heightfield/convex-hull), constraints, raycasts, the `PhysicsScene` GameObject coupling layer, and the per-frame step/sync loop.

Import conventions#

Taos publishes its source directly; the package.json "exports" map ("./*": "./src/*") means you import from taos/<subdir>/index.js, not taos/src/...:

import { Engine, GameObject } from 'taos/engine/index.js';
import { AudioEngine } from 'taos/audio/index.js';
import { GeoScene, GeoFrame } from 'taos/geo/index.js';
import { PhysicsWorld } from 'taos/physics/index.js';

Inside this repo (samples, crafty), the same modules are imported by relative path, e.g. import { GeoScene } from '../src/geo/index.js'. The code snippets in these guides use the taos/<subdir>/index.js form an external consumer would write; adjust to relative paths when working inside the repo.

.js extensions are required. Taos's TypeScript sources import with .js extensions (import { Foo } from './foo.js' resolves ./foo.ts). Your tsconfig.json needs "moduleResolution": "bundler". See the Quick-Start Guide for a complete consumer tsconfig.

Building a static site#

These pages render to a browsable HTML site (sidebar, search, light/dark themes — the same chrome as the book) under docs/site/:

npm run build-docs-site     # → docs/site/  (preview: npx serve docs/site)

Generated API reference#

Alongside these hand-written guides, TypeDoc generates a full symbol-level API reference from the source's TSDoc/JSDoc comments — the Doxygen equivalent for TypeScript. It documents every exported class, function, and type across the public barrels (src/index.ts plus the audio, sdf, terrain, geo, and physics subpaths), with type cross-linking and search:

npm run build-api-ref       # → docs/site/api/  (configured in typedoc.json)

It's reachable from the docs-site sidebar ("API Reference ↗"). Run it after build-docs-site (which clears docs/site/); the top-level npm run build chains book site → docs site → API reference in that order.