@convai/embody 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @convai/embody
 
+## 0.4.0
+
+### Minor Changes
+
+- 8bfb1ab: Drag to turn the character, scroll to move in and out — on by default.
+
+  A 3D character you cannot walk around is a picture of one, and
+  `<ConvaiCharacter />` exists to be the batteries-included view. Until now
+  every consumer that wanted to look at the side of a head had to drop to
+  `CharacterModel` and build its own `Canvas`, which is most of what the
+  component was there to spare them.
+
+  `orbit` accepts `false` for a fixed camera, or an object to tune the limits:
+  `minDistance`, `maxDistance`, `minPolarAngle`, `maxPolarAngle`, `enablePan`,
+  `enableZoom`, `autoRotate`, `autoRotateSpeed`.
+
+  The defaults are tuned for one subject — a standing human — rather than for a
+  general scene viewer. Panning is off, because it only ever slides the
+  character off screen, and the vertical sweep stops a few degrees below eye
+  level, because orbiting under the floor shows the inside of a head. It uses
+  three's own `OrbitControls` rather than `@react-three/drei`, so it costs no
+  new dependency: `three` is already a peer and the `dependencies` block stays
+  empty.
+
+  Minor rather than patch because a character that did not move now moves with
+  no code change on the consumer's side.
+
 ## 0.3.0
 
 ### Minor Changes

package/dist/react/ConvaiCharacter.d.ts

@@ -1,4 +1,5 @@
 import { type CharacterModelProps } from './CharacterModel.js';
+import { type OrbitOptions } from './OrbitRig.js';
 export interface ConvaiCharacterProps extends CharacterModelProps {
     /** Wrapper style. Defaults to filling the parent. */
     style?: React.CSSProperties;
@@ -14,8 +15,16 @@ export interface ConvaiCharacterProps extends CharacterModelProps {
         fov?: number;
         target?: [number, number, number];
     };
+    /**
+     * Drag to turn the character, scroll to move in and out. On by default: a
+     * 3D character you cannot walk around is a picture of one, and this
+     * component's whole job is the batteries-included view.
+     *
+     * Pass `false` for a fixed camera, or an object to tune the limits.
+     */
+    orbit?: boolean | OrbitOptions;
     /** Rendered while the body is still loading. */
     fallback?: React.ReactNode;
 }
-export declare function ConvaiCharacter({ style, className, background, camera, fallback, ...character }: ConvaiCharacterProps): import("react").JSX.Element;
+export declare function ConvaiCharacter({ style, className, background, camera, orbit, fallback, ...character }: ConvaiCharacterProps): import("react").JSX.Element;
 export default ConvaiCharacter;

package/dist/react/ConvaiCharacter.js

@@ -24,9 +24,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Suspense } from 'react';
 import { Canvas } from '@react-three/fiber';
 import { CharacterModel } from './CharacterModel.js';
+import { OrbitRig } from './OrbitRig.js';
 const DEFAULT_POSITION = [0, 1.45, 3.6];
 const DEFAULT_TARGET = [0, 0.92, 0];
-export function ConvaiCharacter({ style, className, background = '#17181c', camera, fallback = null, ...character }) {
+export function ConvaiCharacter({ style, className, background = '#17181c', camera, orbit = true, fallback = null, ...character }) {
     const position = camera?.position ?? DEFAULT_POSITION;
     const target = camera?.target ?? DEFAULT_TARGET;
     return (_jsxs("div", { className: className, style: { width: '100%', height: '100%', minHeight: '100vh', ...style }, children: [_jsxs(Canvas, { camera: { position, fov: camera?.fov ?? 35, near: 0.05, far: 100 }, 
@@ -34,7 +35,9 @@ export function ConvaiCharacter({ style, className, background = '#17181c', came
                 // existing page content rather than in a box of its own.
                 gl: { antialias: true, alpha: background === null }, 
                 // Aim at the character's head rather than the origin at its feet;
-                // r3f points the camera at [0,0,0] otherwise.
-                onCreated: ({ camera: cam }) => cam.lookAt(...target), children: [background !== null && _jsx("color", { attach: "background", args: [background] }), _jsx("hemisphereLight", { args: [0xffffff, 0x334455, 1.4] }), _jsx("directionalLight", { position: [2, 4, 3], intensity: 2.2 }), _jsx(Suspense, { fallback: null, children: _jsx(CharacterModel, { ...character }) })] }), fallback] }));
+                // r3f points the camera at [0,0,0] otherwise. Harmless when orbit is
+                // on — OrbitRig takes the same target and drives the camera from
+                // there — and load-bearing when it is off.
+                onCreated: ({ camera: cam }) => cam.lookAt(...target), children: [background !== null && _jsx("color", { attach: "background", args: [background] }), _jsx("hemisphereLight", { args: [0xffffff, 0x334455, 1.4] }), _jsx("directionalLight", { position: [2, 4, 3], intensity: 2.2 }), orbit !== false && (_jsx(OrbitRig, { target: target, options: orbit === true ? undefined : orbit })), _jsx(Suspense, { fallback: null, children: _jsx(CharacterModel, { ...character }) })] }), fallback] }));
 }
 export default ConvaiCharacter;

package/dist/react/OrbitRig.d.ts

@@ -0,0 +1,30 @@
+export interface OrbitOptions {
+    /** Closest the camera may come, in metres. */
+    minDistance?: number;
+    /** Furthest the camera may retreat, in metres. */
+    maxDistance?: number;
+    /** Highest the camera may rise, in radians from straight up. */
+    minPolarAngle?: number;
+    /** Lowest the camera may sink. Past `PI/2` it starts looking up from below. */
+    maxPolarAngle?: number;
+    /** Drag the subject around the frame. Off by default — it loses the character. */
+    enablePan?: boolean;
+    /** Scroll to dolly in and out. */
+    enableZoom?: boolean;
+    /** Turn the character slowly on its own, for an idle showcase. */
+    autoRotate?: boolean;
+    /** Degrees per second when `autoRotate` is on. */
+    autoRotateSpeed?: number;
+}
+export interface OrbitRigProps {
+    /** The point orbited around — the character's head, not its feet. */
+    target: [number, number, number];
+    options?: OrbitOptions;
+}
+/**
+ * Renders nothing. Lives inside `<Canvas>` so it can reach the camera and the
+ * canvas element, which is also why it cannot simply be set up in `onCreated`
+ * — damping needs a per-frame `update()`.
+ */
+export declare function OrbitRig({ target, options }: OrbitRigProps): null;
+export default OrbitRig;

package/dist/react/OrbitRig.js

@@ -0,0 +1,92 @@
+/**
+ * Drag-to-orbit for the character view.
+ *
+ * Uses three's own `OrbitControls` rather than `@react-three/drei` so this
+ * costs no new dependency: `three` is already a peer, and embody ships with
+ * an empty `dependencies` block that is worth keeping empty.
+ *
+ * The defaults are tuned for one subject — a standing human — rather than for
+ * a general scene viewer. Panning is off and the vertical sweep stops just
+ * below eye level, because in a character viewer both of those only ever lose
+ * the character: pan slides it off screen, and orbiting under the floor shows
+ * the inside of a head.
+ */
+import { useFrame, useThree } from '@react-three/fiber';
+import { useEffect, useRef, useState } from 'react';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+/**
+ * Roughly 20 degrees above the head down to a few degrees below eye level.
+ * `PI/2` is dead level with the orbit target, so the small overshoot buys a
+ * slight up-angle without ever reaching the floor.
+ */
+const DEFAULTS = {
+    minDistance: 0.6,
+    maxDistance: 8,
+    minPolarAngle: Math.PI * 0.12,
+    maxPolarAngle: Math.PI * 0.52,
+    enablePan: false,
+    enableZoom: true,
+    autoRotate: false,
+    autoRotateSpeed: 1.2,
+};
+/**
+ * Renders nothing. Lives inside `<Canvas>` so it can reach the camera and the
+ * canvas element, which is also why it cannot simply be set up in `onCreated`
+ * — damping needs a per-frame `update()`.
+ */
+export function OrbitRig({ target, options }) {
+    const camera = useThree((s) => s.camera);
+    const domElement = useThree((s) => s.gl.domElement);
+    // Created and disposed in the SAME effect, never in useMemo. Disposal
+    // removes the listeners OrbitControls put on the canvas — without it a
+    // remounted character leaves a live controller behind and two fight over
+    // every drag. But a memoised instance disposed in a cleanup is a trap:
+    // React StrictMode runs mount → cleanup → mount in dev, and the second
+    // mount reused the same, already-disposed instance. The rig then rendered
+    // fine and did nothing until something recreated the controls — a resize,
+    // an HMR reload — which is exactly "orbit comes and goes". Pairing
+    // construction with disposal means the remount gets a live instance.
+    const [controls, setControls] = useState(null);
+    const controlsRef = useRef(null);
+    useEffect(() => {
+        const next = new OrbitControls(camera, domElement);
+        controlsRef.current = next;
+        setControls(next);
+        return () => {
+            next.dispose();
+            if (controlsRef.current === next)
+                controlsRef.current = null;
+        };
+    }, [camera, domElement]);
+    const [tx, ty, tz] = target;
+    const { minDistance, maxDistance, minPolarAngle, maxPolarAngle, enablePan, enableZoom, autoRotate, autoRotateSpeed, } = { ...DEFAULTS, ...options };
+    useEffect(() => {
+        if (!controls)
+            return;
+        controls.target.set(tx, ty, tz);
+        controls.minDistance = minDistance;
+        controls.maxDistance = maxDistance;
+        controls.minPolarAngle = minPolarAngle;
+        controls.maxPolarAngle = maxPolarAngle;
+        controls.enablePan = enablePan;
+        controls.enableZoom = enableZoom;
+        controls.autoRotate = autoRotate;
+        controls.autoRotateSpeed = autoRotateSpeed;
+        // Damping is what makes a drag feel like weight rather than a jump cut.
+        controls.enableDamping = true;
+        controls.dampingFactor = 0.08;
+        controls.update();
+    }, [
+        controls, tx, ty, tz,
+        minDistance, maxDistance, minPolarAngle, maxPolarAngle,
+        enablePan, enableZoom, autoRotate, autoRotateSpeed,
+    ]);
+    useFrame(() => {
+        // The ref, not the state: a frame can run between dispose and the
+        // re-render that clears the state, and updating a disposed controller
+        // is harmless but pointless.
+        controlsRef.current?.update();
+    });
+    return null;
+}
+export default OrbitRig;

package/dist/react/index.d.ts

@@ -31,6 +31,8 @@ export { ConvaiCharacter, default } from './ConvaiCharacter.js';
 export type { ConvaiCharacterProps } from './ConvaiCharacter.js';
 export { CharacterModel } from './CharacterModel.js';
 export type { CharacterModelProps } from './CharacterModel.js';
+export { OrbitRig } from './OrbitRig.js';
+export type { OrbitOptions, OrbitRigProps } from './OrbitRig.js';
 export { useWidgetClient } from './useWidgetClient.js';
 export type { WidgetClient } from './useWidgetClient.js';
 export { ConvaiWidget, useConvaiClient, AudioRenderer, AudioContext } from '@convai/web-sdk/react';

package/dist/react/index.js

@@ -28,6 +28,9 @@
 export { useCharacter } from './useCharacter.js';
 export { ConvaiCharacter, default } from './ConvaiCharacter.js';
 export { CharacterModel } from './CharacterModel.js';
+// Exported for apps that build their own <Canvas> around CharacterModel and
+// still want the orbit behaviour ConvaiCharacter gives for free.
+export { OrbitRig } from './OrbitRig.js';
 export { useWidgetClient } from './useWidgetClient.js';
 // ── Chat / conversation surface, re-exported from @convai/web-sdk/react ────
 export { ConvaiWidget, useConvaiClient, AudioRenderer, AudioContext } from '@convai/web-sdk/react';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convai/embody",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Give a Convai character a body: resolve 3D characters by characterId and drive them with lipsync and animation. Layered on @convai/web-sdk.",
   "license": "Apache-2.0",
   "author": "Convai <support@convai.com>",
@@ -79,6 +79,7 @@
     "@types/react-dom": "^19.2.7",
     "@types/react-test-renderer": "18.3.1",
     "@types/three": "^0.182.0",
+    "jsdom": "^25.0.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-test-renderer": "18.3.1",