@ripl/3d

3D rendering for Ripl: shapes, lights, materials and textures, drawn onto a 2D canvas with a depth-sorted painter's algorithm, or on the GPU through @ripl/webgpu.

Features

• Nine shapes — cube, sphere, cylinder, cone, plane, torus, mesh (raw faces), parametric (a tessellated surface function) and bezier surface (bicubic patches).
• Five light types — createAmbientLight, createHemisphereLight, createDirectionalLight, createPointLight and createSpotLight, each with colour, intensity and an enabled flag; directed lights are fixed in world space or locked to the camera. Point and spot lights add distance falloff (distance, decay) and spot lights a cone (angle, penumbra).
• Materials — color, opacity, emissive, emissiveIntensity, specular, shininess, side ('front' | 'back' | 'double'), wireframe, flatShading, vertexColors and map. Every property is optional; an element with only a fill shades as it always did.
• Textures — createTexture from an ImageBitmap, <img>, <canvas>, <video>, OffscreenCanvas or ImageData, or loadTexture from a URL. Per-axis wrapping ('clamp' | 'repeat' | 'mirror'), separate magnification and minification filters ('nearest' | 'linear'), and a UV transform of repeat, offset and flipY. Every built-in shape emits the coordinates, and both backends sample them the same way.
• Perspective and orthographic camera — createCamera drives the context's view and projection, batches changes through a microtask, and handles orbit, pan and pinch/wheel zoom with per-interaction sensitivity.
• Fog — 'linear' or 'exponential' haze blending distant geometry towards a colour, computed identically on both backends.
• Triangle raycasting — context.raycast(x, y) builds a world-space ray and context.raycastAll(scene, x, y) returns every shape it meets, nearest first, with the hit point, face, interpolated normal and UV.
• Group3D — a group whose transform composes into the model matrix of every shape beneath it, so a subtree orbits, tilts and scales as a unit.
• Animation and events — shapes are Ripl elements, so renderer.transition, pointer events and scene querying all apply. interpolateVector3 tweens 3D positions — declare it in a custom element's interpolators to animate a vector-valued property.

Installation

# npm
npm install @ripl/3d @ripl/web

# yarn
yarn add @ripl/3d @ripl/web

# pnpm
pnpm add @ripl/3d @ripl/web

The scene and renderer come from @ripl/web; this package supplies the 3D context, camera, lights and shapes. For GPU rasterization, add @ripl/webgpu and import createContext from there instead.

Quick start

import {
    createCamera,
    createContext,
    createDirectionalLight,
    createTorus,
} from '@ripl/3d';

import {
    createRenderer,
    createScene,
} from '@ripl/web';

const context = createContext('.mount-element');
const scene = createScene(context);

createCamera(context, {
    position: [0, 2, 5],
    target: [0, 0, 0],
    interactions: true,
});

context.lights.add(createDirectionalLight({
    direction: [-1, -1, -0.5],
    intensity: 0.8,
}));

scene.add(createTorus({
    radius: 1.2,
    tube: 0.4,
    material: {
        color: '#4488ff',
        specular: '#ffffff',
        shininess: 48,
    },
}));

createRenderer(scene, {
    autoStop: false,
});

Key API

| Export | What it does | | --- | --- | | createContext | Canvas-backed Context3D that projects and depth-sorts faces | | createCamera | Perspective or orthographic camera with orbit, pan and zoom | | createAmbientLight … createSpotLight | The five light constructors, added via context.lights | | createMaterial | How a surface responds to light | | createTexture / loadTexture | Images mapped across a surface | | createCube … createBezierSurface | The nine built-in shapes | | createGroup3D | A group carrying a 3D transform for its subtree | | Context3D.raycastAll | Every shape under a point, nearest first | | computeFaceNormal / shadeFaceColor | Shading helpers for custom geometry |

Related packages

• @ripl/web — the browser entry point supplying the scene, renderer and animation
• @ripl/webgpu — GPU backend for the same Shape3D elements
• @ripl/core — the element, scene and animation model these shapes build on

Documentation

Guides, live demos and the full API reference are at ripl.run/docs/3d.

License

MIT