@laplace.live/three-live2d

Live2D Cubism renderer for the three.js WebGPURenderer, built on TSL node materials. Extracted from LAPLACE Persona, where it renders the desktop avatar stage inside a worker.

• Loads .model3.json models — motions, expressions, physics, pose, and hit-area picking
• Clipping masks and Cubism blend modes ported to render targets + TSL node materials
• DOM-free: runs on a page or in a worker with OffscreenCanvas (fetch + createImageBitmap)
• Ships the official CubismWebFramework compiled in; Cubism Core is loaded by you at runtime

Install

npm i @laplace.live/three-live2d three

three is a peer dependency supporting 0.185.x and 0.186.x — the renderer reaches into TSL internals, which move between three minors.

Cubism Core

Live2D Cubism Core (live2dcubismcore.js) is Live2D's proprietary runtime and is not bundled. Download it with the Cubism SDK for Web, serve it yourself, and evaluate it before this package is imported — the framework reads the Live2DCubismCore global while its module graph evaluates. A <script> tag ahead of your bundle works on a page, importScripts in a classic worker; in a module worker, fetch + indirect-eval Core first, then pull the renderer in with a dynamic import().

The SDK download also carries live2dcubismcore.d.ts; add it to your project for full typing — the published types reference the Live2DCubismCore global namespace it declares (without it, those few spots fall back to any under skipLibCheck).

Usage

import { Live2DModel } from "@laplace.live/three-live2d";
import { OrthographicCamera, Scene, WebGPURenderer } from "three/webgpu";

const renderer = new WebGPURenderer({ canvas });
await renderer.init();

// The model is a Group laid out in y-down pixel space: pair it with an
// orthographic camera whose units are canvas pixels.
const scene = new Scene();
const camera = new OrthographicCamera(0, width, 0, height, -1, 1);

const model = await Live2DModel.from(
  "https://example.com/hiyori/hiyori.model3.json",
);
model.position.set(width / 2, height / 2, 0); // centre-anchored
scene.add(model);

let last = performance.now();
renderer.setAnimationLoop((now) => {
  const dt = now - last;
  last = now;

  model.update(dt); // advance motions/physics
  model.renderPasses(renderer, camera, width, height); // masks + offscreens, before the main pass
  renderer.render(scene, camera);
});

model.focus(x, y); // look toward a canvas-space point

configureCubismSDK({ memorySizeMB }) tunes Cubism's heap before the first load, and model.destroy() releases GPU resources (textures are ref-counted and shared across instances of the same model).

model.setPostProcess(process) enables a per-model texture pass before whole-model opacity is applied. The callback receives (renderer, source, width, height) and returns a texture with the same dimensions and premultiplied RGBA encoding; dimensions are physical pixels. The model owns source, and the caller owns the returned texture and any intermediate targets. Pass null to disable processing. Cubism offscreens finish before this pass; crossfades multiply its result.

License

The renderer itself (src/) is MIT. It compiles in a pristine mirror of Live2D/CubismWebFramework, which is covered by the Live2D Open Software License — its license text ships in this package at vendor/cubism/LICENSE.md. Live2D Cubism Core is not included; it is distributed by Live2D under the Live2D Proprietary Software License, and businesses above the revenue threshold also need a Cubism SDK Release License. Review Live2D's terms before shipping a product.