@vosjs/core

@vosjs/core

The Vos engine — a declarative, resolution-independent API for compiling mixed-media animations (Three.js 3D scenes, 2D overlays, HTML, video) into executable templates.

Part of Vos — the open-source engine behind vos.so.

@vosjs/core takes a JSON description of an animation — scenes, cameras, post-processing, GSAP timelines, and overlay elements — and compiles it into a self-contained template that runs anywhere a browser can. The core is pure (no DOM dependencies), so it runs in the browser, in Node, or in a Cloudflare Worker for server-side rendering.

Install

pnpm add @vosjs/core three gsap

three and gsap are optional peer dependencies — you bring your own versions, and the engine never bundles them.

Quick start

import { compileVosConfig, vosConfigJsonSchema } from '@vosjs/core'

const config = {
  version: 2,
  duration: 3,
  camera: { preset: 'perspective' },
  // functions are authored as strings, compiled into executable code
  createContent:
    '(ctx) => { const { THREE, scene } = ctx; const m = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshBasicMaterial()); scene.add(m); return { m } }',
  createTimeline:
    '(ctx, content, duration) => ctx.gsap.timeline().to(content.m.rotation, { y: Math.PI, duration })',
}

vosConfigJsonSchema.parse(config) // validate
const template = compileVosConfig(config) // → runnable template string

The compiled template is an HTML/JS document you can render in an iframe, capture to video, or snapshot to an image.

Subpath exports

License

MIT Hongbin Li