Retiam

Retiam is a TypeScript animation engine built on WebGPU. Write scenes for mathematical explanations, data visualizations, and 2D or 3D animation, then preview them in a browser, render video, or export an interactive web embed.

Documentation · Getting started · Examples · API reference

Retiam is free for noncommercial use under the Retiam Noncommercial License. Commercial development, internal business use, paid client work, and products, services or content that earn revenue directly or indirectly require a separate paid written commercial license before use. This includes advertising, sponsorships, subscriptions, and monetized videos or courses, even when Retiam is only one part of a larger project. Contact [email protected] for commercial licensing.

The full terms are included in the npm package. After installation, read node_modules/retiam/LICENSE and node_modules/retiam/COMMERCIAL_LICENSE.md. The public links above show the terms for this release without requiring access to the private engine repository.

Your independently authored code and original outputs remain your own. Earlier ISC permissions and third-party licenses remain unaffected. Keep the third-party notices and license texts with redistributed Retiam code. These files are also installed in node_modules/retiam/. Source maintainers can find provenance review limits and notice-generation commands in docs/LICENSING.md in the engine checkout.

Features

• Scene authoring: compose entities, groups, layouts, cameras, and interaction with TypeScript.
• Animation and timing: choreograph transitions with asynchronous timelines, easing, tracks, and value trackers.
• Mathematical graphics: create coordinate systems, plots, vector geometry, LaTeX equations, text, and highlighted code.
• Rendering: combine 2D paths, 3D meshes, lighting, shadows, compute effects, and post-processing.
• Specialized libraries: add charts, graphs, physics, procedural shapes, sketch styling, and emphasis animations through separate imports.
• Audio and output: work with audio, narration, and subtitles; inspect snapshots, render video, or share scenes as web components.
• Retiam Studio: edit scenes alongside a live preview, tune supported values with inspectors, and control playback from your generated project.

Getting started

| Method | Use it for | Result | | --- | --- | --- | | npm project and Studio | Author and preview TypeScript scenes, then render video | Source project, MP4 and snapshots | | CDN modules | Add a live scene directly to a browser page | Interactive WebGPU canvas | | Embedded export | Share a finished animation on another website | Hosted web component and bundled assets |

Create a project with Studio

Use Node.js 20.19 or newer and a WebGPU-capable browser. The project generator creates a TypeScript application, installs its dependencies, and opens Retiam Studio with a Write animation of “Retiam”:

npx create-retiam@latest my-animation

The generated project declares "retiam": "latest". Its initial install uses npm's latest engine release; the package manager's lockfile records the resolved version for later installs.

The editor opens below the preview. Drag the divider to resize it, or use the layout control to dock it on the left or right. Studio remembers your choice. Single-scene projects show the preview and editor; scene navigation and search appear when more scenes are added and the page reloads.

Press Ctrl+C to stop the server. To reopen Studio:

cd my-animation
npm run dev

Edit src/scenes/Retiam.ts in your editor or Studio. The generated project also includes config.js for CLI rendering, studio/ for the local editor, and the Vite and TypeScript configuration. In Studio, Run or Ctrl/Command+Enter applies and saves edits. Add default-exported Scene classes under src/scenes/ to make them available in the scene browser after reloading.

| Generator option | Behavior | | --- | --- | | --no-start | Install dependencies without starting Studio | | --no-install | Generate files without installing or starting | | --no-open | Start the server without opening a browser | | --title "Hello" | Change the starter animation text | | --pm npm\|pnpm\|yarn\|bun | Choose the package manager |

The create-retiam package is released separately from the engine. Publish the engine version required by its starter before publishing the generator. Generator updates apply to new projects; existing projects keep their own Studio and configuration files.

Manual setup

Install Retiam in your own TypeScript application:

npm install retiam
npm install --save-dev typescript "vite@^6.1.1" @webgpu/types

Follow the installation guide for the complete project structure, TypeScript configuration, and browser entry point. To use an unpublished checkout, run npm pack in this repository and install the generated .tgz file in your application.

For Vite applications, preserve Retiam's packaged asset URLs and include its license and third-party notices in production output with vite.config.ts:

import { defineConfig } from "vite";
import { retiamNoticesPlugin } from "retiam/license-notices";

export default defineConfig({
  plugins: [retiamNoticesPlugin()],
  esbuild: { legalComments: "inline" },
  optimizeDeps: { exclude: ["retiam"] },
});

Retiam requires a WebGPU-capable browser and compatible GPU. Serve browser applications over HTTPS or localhost.

Your first scene

Save this as scenes/FirstScene.ts. Scenes define their animation in an asynchronous run() method; durations are in milliseconds.

import { Scene, Circle, Create, FadeOut, CameraModel, hex } from "retiam";

export default class FirstScene extends Scene {
  async run() {
    this.clearColor(hex("#090E1B"));
    this.camera.model = CameraModel.ORTHOGRAPHIC;
    this.camera.orthoScale = 12;
    this.camera.position.set([0, 0, 20]);
    this.camera.lookAt([0, 0, 0]);

    const circle = new Circle(1, { fill: hex("#38BDF8") });
    circle.move([-2, 0, 0]);
    this.add(circle);

    await this.play(new Create(circle, { duration: 1200 }));
    await this.play(circle.animate.move([2, 0, 0]), { duration: 1000 });
    await this.wait(800);
    await this.play(new FadeOut(circle, { duration: 600 }));
    await this.wait(400);
  }
}

Start the scene from your application's browser entry point, src/main.ts:

import FirstScene from "../scenes/FirstScene";

const canvas = document.querySelector<HTMLCanvasElement>("#canvas");
if (!canvas) throw new Error("Missing scene canvas.");

const scene = new FirstScene();
await scene.start(canvas);
window.addEventListener("pagehide", () => scene.destroy(), { once: true });

The host page needs a <canvas id="canvas"></canvas> with an explicit CSS display size. Continue with your first scene for animation, camera, and lifecycle guidance.

Use Retiam from a CDN

Import Retiam directly in a browser page. The published module is available at jsDelivr. This example loads the core and charts entries through the latest release tag:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Retiam CDN animation</title>
    <style>
      html, body { margin: 0; width: 100%; height: 100%; }
      canvas { display: block; width: 100%; height: 100%; }
    </style>
    <script type="importmap">
      {
        "imports": {
          "retiam": "https://cdn.jsdelivr.net/npm/retiam@latest/dist/retiam.es.min.js",
          "retiam/charts": "https://cdn.jsdelivr.net/npm/retiam@latest/dist/libs/charts/index.js"
        }
      }
    </script>
  </head>
  <body>
    <canvas id="canvas"></canvas>
    <script type="module">
      import { Scene, Circle, Create, CameraModel, hex } from 'retiam';

      class BrowserScene extends Scene {
        async run() {
          this.clearColor(hex('#080C14'));
          this.camera.model = CameraModel.ORTHOGRAPHIC;
          this.camera.orthoScale = 12;
          this.camera.position.set([0, 0, 20]);
          this.camera.lookAt([0, 0, 0]);
          const circle = new Circle(1, { fill: hex('#38BDF8') });
          this.add(circle);
          await this.play(new Create(circle, { duration: 1200 }));
          await this.wait(1000);
        }
      }

      const scene = new BrowserScene();
      scene.start(document.querySelector('#canvas')).catch(console.error);
      window.addEventListener('pagehide', () => scene.destroy(), { once: true });
    </script>
  </body>
</html>

Serve the page over HTTPS or localhost, with a WebGPU-capable browser. No Retiam npm installation is needed for this page. Add import-map entries for any other sublibraries you use, such as retiam/shapes, with the same release tag. jsDelivr serves the module's related chunks, fonts, workers and WASM assets. A CDN page runs the animation live; the npm CLI workflow produces video and snapshots.

Export an independent web embed

Bundle a finished scene into a custom element for a blog, documentation page or another application. The exported files include the engine code and emitted assets needed by that scene. The receiving site needs WebGPU and those files.

This recipe uses Vite 6, matching the generated project's toolchain. For a generated npm project, save the following as src/embed.ts. Each element owns its canvas and Scene, handles resizing, and cleans up when removed.

import MyScene from './scenes/Retiam';

// A separate name lets this bundle coexist with other scene components.
class MyRetiamSceneElement extends HTMLElement {
  private cleanup?: () => void;

  connectedCallback() {
    this.cleanup?.();
    const canvas = document.createElement('canvas');
    canvas.style.cssText = 'display:block;width:100%;height:100%';
    this.replaceChildren(canvas);
    const scene = new MyScene();
    let cancelled = false, started = false, resizeFrame = 0;
    let observer: ResizeObserver | undefined;

    this.cleanup = () => {
      cancelled = true;
      observer?.disconnect();
      cancelAnimationFrame(resizeFrame);
      if (started) scene.destroy();
      // A pending initialization cleans up in its continuation below.
    };
    void scene.start(canvas).then(() => {
      started = true;
      if (cancelled) { scene.destroy(); return; }
      observer = new ResizeObserver(() => {
        cancelAnimationFrame(resizeFrame);
        resizeFrame = requestAnimationFrame(() => {
          // Current composer resizing listens to the window resize event.
          window.dispatchEvent(new Event('resize'));
        });
      });
      observer.observe(this);
      this.dispatchEvent(new CustomEvent('scene-ready', { bubbles: true }));
    }).catch(error => {
      scene.destroy();
      if (!cancelled) {
        const message = document.createElement('p');
        message.setAttribute('role', 'alert');
        message.textContent = String(error);
        this.replaceChildren(message);
      }
    });
  }

  disconnectedCallback() {
    this.cleanup?.();
    this.cleanup = undefined;
  }
}

if (!customElements.get('my-retiam-scene')) {
  customElements.define('my-retiam-scene', MyRetiamSceneElement);
}

For a manual project, change the scene import to your scene module. The npm embed recipe explains lifecycle handling, multiple instances and hosting.

Save this as vite.embed.config.ts:

import { defineConfig } from 'vite';
import { retiamNoticesPlugin } from 'retiam/license-notices';

export default defineConfig({
  base: './',
  plugins: [retiamNoticesPlugin()],
  esbuild: { legalComments: 'inline' },
  build: {
    target: 'es2022',
    outDir: 'outputs/embed',
    lib: {
      entry: 'src/embed.ts',
      formats: ['es'],
      fileName: 'my-scene',
    },
  },
});

Build the component:

npx vite build --config vite.embed.config.ts

Copy the whole outputs/embed folder to your website, for example under /embeds/my-scene/, then mount the custom element:

<script type="module" src="/embeds/my-scene/my-scene.js"></script>
<my-retiam-scene style="display:block;width:100%;height:540px"></my-retiam-scene>

The receiving site needs no npm installation or separate Retiam CDN import. Preserve emitted files and their relative paths. Assets or services explicitly referenced by remote URLs still need hosting. Use a distinct custom-element name for each different scene bundle. An MP4 is the alternative when the receiving page only needs video playback.

The engine repository also provides an export CLI:

npx retiam export scenes/MyScene.ts outputs/embed

Its current implementation expects the engine repository's src/engine layout. Use the package-based Vite recipe above for generated and other external npm projects. See repository export for the CLI's script and <retiam-scene> usage.

CLI and video rendering

Run these commands from the generated project folder containing package.json and config.js:

npx retiam lint src/scenes/Retiam.ts --json
npx retiam snapshot src/scenes/Retiam.ts --times 1.0,2.5,4.0 --json
npx retiam render src/scenes/Retiam.ts

Puppeteer is a required production dependency of Retiam and is installed automatically with the package. Render and snapshot commands need a working Chrome/WebGPU setup. Video rendering also requires FFmpeg on your PATH.

Render configuration

The generated config.js contains CLI output and renderer quality settings with their defaults and comments. The default output is 1920×1080 at 60 fps, MP4 at 20M, in outputs/video. maxDuration: 0 renders until the scene finishes; set a limit for scenes that loop indefinitely.

For a smaller draft, edit the output fields in config.js:

export default {
  width: 1280,
  height: 720,
  fps: 30,
  videoBitrate: '8M',
  outputFormat: 'mp4',
  outputDir: './outputs/video',
  maxDuration: 4000, // milliseconds
};

The renderer starts with built-in defaults, loads config.js from the calling project, then applies CLI flags. If retiam.config.js exists, it is used instead of config.js. For example, this renders at 60 fps while retaining the other file settings:

npx retiam render src/scenes/Retiam.ts -f 60

The complete file also covers anti-aliasing, transparency layers, shadows, culling, raytracing, denoising, local server ports, and input replay. See the configuration reference.

Choose surface appearance in scene code and materials:

import { CelShading, GoochShading } from 'retiam';

this.shading = new CelShading({ bands: 3 }); // Scene default
sphere.material.shading = new GoochShading({ warm: 0.6, cool: 0.4 });

Each shading model supplies its own WGSL. Numeric parameters update through the material buffer without recompiling shaders. These styles apply to rasterized 3D models; raytracing uses its own physically based lighting.

For the manual setup above, use scenes/FirstScene.ts as the scene path. Rendering and snapshots serve the project's index.html; a host that supports selecting different scenes must load the CLI's file query parameter. The manual installation guide includes that bootstrap. Render duration (-d) is in milliseconds, snapshot times are in seconds, and output (-o) is a directory. Render filenames include a timestamp.

See rendering and export for project setup and encoding options, or follow package-based embeds to bundle a scene for another website. Run npx retiam help for the command reference.

Libraries

Import shared scene primitives from retiam and specialized functionality from its own entry point.

| Import | Purpose | | --- | --- | | retiam | Scenes, entities, animations, cameras, geometry, text, and core math | | retiam/shapes | Procedural 2D paths and 3D meshes | | retiam/charts | Cartesian and polar charts, scales, themes, and tooltips | | retiam/graphs | Graphs, layouts, automata, and tapes | | retiam/highlights | Emphasis and attention animations | | retiam/physics | 2D and 3D physics integrations | | retiam/rough | RoughJS styling integration | | retiam/tts | Microsoft Edge speech synthesis, narration, and subtitles |

See the library guide for import boundaries and examples. roughjs is a required production dependency and is installed automatically.

Built-in fonts and imported engine assets are included in the library package. Application media is managed separately. Edge speech synthesis in the browser requires a compatible service. See asset workflows and speech and subtitles for setup.

MSDF font generation runs in a browser worker using the WASM supplied by @zappar/msdf-generator, a production dependency. The repository's font-baking tools, including msdf-bmfont-xml and msdf-atlas-gen, remain development tools.

Repository development

Use Node.js 24, matching the documentation CI configuration.

git clone https://github.com/abhilasbiswas/Retiam.git
cd Retiam
npm ci
npm run dev

Open the URL printed by Vite. Retiam Studio is available at /studio/ on the same server. See the tooling guide for the editor, inspector, and playback controls.

Documentation development

The viewer, authored guides, examples, assets, API reference data, and Pages workflow are maintained in the separate retiam-docs repository. It installs, builds, and deploys independently of this engine checkout. See that repository's README and deployment guide for local development and publishing.

Documentation and source

• Handbook: guides, tutorials, examples, and API references.
• Compatibility notes: current implementation boundaries and known differences from historical examples.
• Architecture notes: detailed subsystem documentation.
• Example sources: repository scenes and integrations.
• Agent skill: scene-authoring guidance for coding assistants.