scene3d
Build a CSS 3D world, step the camera along a path or fly a keyed look-at camera through it, and bind it to a GSAP timeline.
import { createScene3D, Transform3D, Vec3 } from "@av/hyperbits/helpers";
const scene = createScene3D(root, { perspective: 1200, stepDuration: 2, transitionDuration: 1, easing: "power2.inOut", steps: [ { x: 0, y: 0, z: 0, rotateY: 0, duration: 2 }, { x: 200, y: -40, z: -400, rotateY: 25, duration: 2 }, ], elements: [{ element: card, z: -200, rotateY: -15 }],});
scene.bind(timeline);createScene3D(root, config)
Section titled “createScene3D(root, config)”Creates canvas/world nodes inside root. Returns { canvas, world, stateAt, apply, bind }.
stateAt(time) is the time-state binding (seek-safe, same idea as createParticles().stateAt). It yields activeStepIndex, activeStepId, transitionProgress, camera, cameraTransform, and resolved steps. bind(timeline) applies state on onUpdate. Scene3D owns its DOM, so bind only takes the timeline; particles pass the canvas because they do not own it.
Step and element fields: x y z, rotateX/Y/Z, rotateOrder, scale / scaleX/Y/Z. Elements also accept fixed and centered.
createCamera(stage, world, config)
Section titled “createCamera(stage, world, config)”A keyed look-at camera for CSS 3D. Each key says where the camera is, what it looks at, how far it rolls and which lens it uses. The camera moves between keys with the ease of the key the segment starts from, and the orientation is slerped between look-at quaternions, so a turn never flips or spins the long way round.
import { createCamera } from "@av/hyperbits/helpers/scene3d";
const view = hyperbits.viewport(root);const unit = view.vmin;const camera = createCamera(stage, world, { ease: "power2.inOut", keys: [ { time: 0, position: [0, 0, 620 * unit], target: [0, 0, -160 * unit], lens: 468 * unit, ease: "power2.inOut" }, { time: 2.5, position: [0, 0, -20 * unit], target: [0, 0, -160 * unit], lens: 84 * unit, ease: "sine.inOut" }, { time: 6, position: [400 * unit, -60 * unit, -300 * unit], target: [0, 0, -400 * unit], roll: 6 }, { time: 9, position: [300 * unit, -40 * unit, -250 * unit], target: [0, 0, -400 * unit], roll: 0, lens: 160 * unit }, ],});
camera.bind(timeline);Returns { stage, world, stateAt, apply, bind }. stage gets perspective and world gets one matrix3d. createCamera places world as a zero-size, preserve-3d box at the stage centre, so the world origin projects to the middle of the frame. Position children with translate3d(x, y, z) rotateY(...) translate(-50%, -50%) and transform-origin: 0 0. Coordinates follow CSS: +x right, +y down, +z toward the viewer.
Key fields:
timein seconds. Keys are sorted by time. Two keys at the same time make a hard cut.positionandtargetas[x, y, z]or{ x, y, z }in pixels. Omittingtargetreuses the previous key’s target. A first key without one looks down-z.rollin degrees around the view axis.lensis the CSSperspectivein pixels: a pointlenspixels in front of the camera renders at scale 1. Both carry over from the previous key when omitted.config.lens(default 1000) seeds the first key.easeshapes the segment that starts at this key. Accepts GSAP names,Easingnames or a function.config.easeis the default (power2.inOut).
stateAt(time) is a pure function of time and returns { time, segment, progress, position, target, forward, orientation, roll, lens }. orientation is the camera-to-world quaternion [x, y, z, w]. forward is the actual view direction. target is the interpolated key target, so it can drift slightly off-centre during a slerped segment. Slerp takes the shorter arc, so split turns of 180° or more into several keys.
Each segment eases from rest to rest under an inOut ease. For a continuous flight, sample a path into many keys with ease: "none" and put the easing into the key times or positions. camera-flight does this.
Pure camera functions
Section titled “Pure camera functions”cameraStateAt(time, config): the same state asstateAt, without DOM.cameraToCSS(state):{ perspective, transform }strings for your own stage and world.cameraProject(state, point):{ x, y, depth, scale }.xandyare pixel offsets from the stage centre.depthis the distance along the view axis and is negative behind the camera. Use it for fog, culling, labels that track 3D points, or highlights.lookAtOrientation(position, target, roll?): the look-at quaternion. Pitch isasin(forward.y)and yaw isatan2(-forward.x, -forward.z). Looking straight up or down leaves yaw undefined, so keep targets off the vertical axis.applyCamera(stage, world, state): writes a state to the DOM.
Transforms
Section titled “Transforms”Transform3D stores position, quaternion rotation, and scale. Transform3D.fromEuler(x, y, z, position?, scale?, order?), identity(), interpolateTransform(from, to, progress), transformToCSS(transform).
Vec3, Quat, and Mat4 (aliases Vector3, Quaternion, Matrix4) cover the linear algebra.