@apricot/core is the engine without React: the renderer, frame loop, materials, camera rig, physics and timelines. @apricot/react re-exports what apps need (Path, Trip, CAMERA_VIEWS, DAY, definePreset, defineEnvironment, createMaterial, PresetMaterial and the types), so most apps import from it alone. Import from @apricot/core for the utilities below.
import { disposeObject, mergeColoredParts, seededRandom, setShadow } from "@apricot/core";Utilities#
| Export | Signature | Description |
|---|---|---|
seededRandom |
(seed: number) => () => number |
Deterministic pseudo-random numbers in [0, 1). Same seed, same sequence: layouts that look the same every launch |
disposeObject |
(root: Object3D) => void |
Frees the geometries, materials and textures of root and everything under it. Call it on unmount for objects you built |
mergeColoredParts |
(parts: ColoredPart[]) => BufferGeometry |
Bakes several geometries, each with a colour, into one geometry with vertex colours: one draw call. UVs are dropped |
setShadow |
(object, { cast?, receive? } | undefined) => void |
Overrides whether a three.js object casts and receives shadows. On a directional light, cast: true makes it the one that casts |
visibleBox |
(camera, depth = 0, z = 0) => Bounds |
The box of world space the camera sees, depth deep on each side of the plane at z. For filling the screen |
fitDistance |
(camera, width, height, margin = 0.1) => number |
How far the camera must be for an area to fill the view |
fitCamera |
(camera, width, height, { margin, target }) |
Moves the camera along its line of sight so an area fits (what <FitCamera> calls) |
stepSpin |
(object, speed, axis, delta) => boolean |
One frame of <Spin> |
ColoredPart: { geometry, color, matrix? }, where color is a colour, a function of each vertex's position, or "vertex" to keep the geometry's own colours.
Bounds: { min: Vec3, max: Vec3 }.
Constants#
| Export | Description |
|---|---|
CAMERA_VIEWS |
The built-in camera views (see Cameras) |
DAY |
The default DaylightKey[] for <Daylight> |
LOOKS |
The soft, studio and flat look specs |
STUDIO |
The default studio environment |
Engine classes#
The components are thin wrappers around these. Use them for code outside React or for your own components.
| Class | Behind | Description |
|---|---|---|
ApricotScene |
<Scene> |
Renderer, camera, frame loop, taps, shadows, diagnostics |
PresetMaterial |
material props |
A preset material with live colour, roughness and metalness |
CameraRig (the core class) |
<CameraRig> |
Views, arcs, orbit, framing |
FollowRig |
<FollowCamera> |
Chase camera |
ArcadeVehicle |
<Vehicle> |
Toy-car physics: step(delta, { throttle, steer }), state |
SphereWorld |
<Pile> |
Sphere physics solver |
Pile |
<Pile> |
Dropping and piling copies |
Path |
usePath |
Smooth curve with distance queries |
Trip |
useTrip |
Stop-to-stop timeline: at(seconds) returns a TripState |
InstanceSet |
<Instances> |
Copies of a shape in instanced meshes |
BlurLayer |
<Blur> |
The out-of-focus layer |
ClipPlayer |
animations |
glTF clip playback |
SharedCache<T> |
caches | Loads each key once, counts users with acquire / release, disposes on the last release |
@apricot/core/models#
import { instance, ModelCache, parseModel } from "@apricot/core/models";The glTF loading layer, in a separate entry point so apps without models do not carry three's loader.
| Export | Description |
|---|---|
parseModel(bytes) |
Parses .glb bytes into a LoadedModel ({ scene, animations }). No Draco, meshopt or KTX2: Hermes has no WebAssembly. Prepare files with apricot-models |
instance(model) |
A copy of a loaded model to add to a scene. Copies share geometry, materials and textures; rigged models get their own skeleton |
ModelCache |
Loads each model once and shares it; the last release disposes it |
Apps normally use <Model> and useModel from @apricot/react/model instead.