From the editor
to your website.

Create and export

1. Open the Chibi homepage and start a blank scene or choose a template. Prompt generation requires your own Mistral API key.
2. Add objects, adjust their materials, and try your interactions in Preview.
3. Export a .chibi.zip file. It includes the scene and its assets. Place it in your app's public directory, for example public/scenes/hero.chibi.zip.

Editor scenes are saved locally in your browser. Export a copy to keep a portable backup.

Install the runtime

The runtime uses React 19, React Three Fiber 9, and Three.js. In an existing React 19 app, install the runtime and its rendering peers:

pnpm add @chibi3d/runtime @react-three/fiber@^9.6.1 three@^0.185.1

The examples below use the core runtime API. The playground in this repository also includes development features that may be newer than the published package.

Embed a scene

Give the scene a height. The canvas fills its container. In Next.js, put the component in a client file.

"use client";

import { ChibiScene } from "@chibi3d/runtime";

export default function HeroScene() {
  return (
    <ChibiScene
      src="/scenes/hero.chibi.zip"
      style={{ width: "100%", height: 480 }}
      fallback={<p>Loading scene…</p>}
      onError={(error) => console.error(error)}
    />
  );
}

Use src for a zip or JSON URL. Use document when you already have the parsed scene object. A standalone JSON file with external assets also needs an asset resolver.

States and animation

Hover and click actions authored in the editor work in the embed. You can also control the scene from ordinary buttons through an API ref.

"use client";

import { useRef } from "react";
import { ChibiScene, type ChibiSceneApi } from "@chibi3d/runtime";

export default function InteractiveScene() {
  const api = useRef<ChibiSceneApi>(null);

  return (
    <>
      <ChibiScene
        src="/scenes/hero.chibi.zip"
        api={api}
        onEvent={(event) => console.log(event)}
        style={{ height: 480 }}
      />
      <button onClick={() => api.current?.transitionTo("base")}>
        Reset states
      </button>
      <button onClick={() => api.current?.setPaused(true)}>
        Pause motion
      </button>
      <button onClick={() => api.current?.setPaused(false)}>
        Resume motion
      </button>
    </>
  );
}

Call transitionTo(stateId) to enter an authored state, or play(animationId) and stop(animationId) to control a clip. Use IDs from your scene file. Resetting states does not stop animation clips.

onEvent reports interactions, state changes, and readiness. getState() returns the current state ID for each stateful node.

Change materials from your app

Use a material's ID or name to change its color, roughness, or texture. These changes affect the mounted scene; they do not rewrite the exported file.

// With the API ref from the previous example,
// replace "Keycap" with a material name in your scene.
api.current?.setMaterial("Keycap", {
  color: "#8eb8a2",
  roughness: 0.65,
});

A shared material updates every object that uses it. Animated color or opacity may override a host change while an animation or transition runs.

Common props

If the scene does not appear

• Check that the container has a nonzero height.
• Open the scene URL directly to check the file is served. A path in your public folder starts with /scenes/, not /public/scenes/.
• Check onError and the browser console for invalid documents, missing assets, or WebGL errors.
• For remotely hosted scenes and textures, the host must allow cross-origin requests.