ara3d 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -14,6 +14,10 @@ export declare class AraCharacterElement extends HTMLElement {
14
14
  /** The clip playing on the character, for playClip()'s blends. */
15
15
  private active?;
16
16
  private extentFor?;
17
+ /** The pointer's last place on the page, for look-at="pointer". */
18
+ private pointer?;
19
+ private readonly follow;
20
+ private readonly gaze;
17
21
  constructor();
18
22
  connectedCallback(): void;
19
23
  disconnectedCallback(): void;
@@ -44,6 +48,8 @@ export declare class AraCharacterElement extends HTMLElement {
44
48
  */
45
49
  playClip(id: string, fade?: number): boolean;
46
50
  private draw;
51
+ /** Where the head looks: the viewer (look-at="camera"), the pointer anywhere on the page (look-at="pointer"), or ahead. */
52
+ private gazeTarget;
47
53
  /** What to build, from the attributes. */
48
54
  private input;
49
55
  private options;
@@ -10,12 +10,13 @@
10
10
  * Characters are built in a background worker, so the page stays responsive, and exported with the same exporter as
11
11
  * the Ara builder and the ara3d CLI. The character data loads from a free CDN by default.
12
12
  */
13
- import { type AnimationClip, type AnimationMixer, type Group } from 'three';
13
+ import { type AnimationClip, type AnimationMixer, type Group, type Object3D, type Vector3 } from 'three';
14
14
  import type { CharacterInput, GenerateOptions } from './library/generate';
15
15
  import type { CharacterColors } from './library/colors';
16
16
  import { type SequenceStep } from './library/sequence';
17
+ import { type LipSync, type LipSyncSource, type Locomotion, type LocomotionOptions, type LookOptions } from './library/motion';
17
18
  import type { HumanParams } from '../../../src/core/params';
18
- export type { CharacterColors, CharacterInput, GenerateOptions, SequenceStep };
19
+ export type { CharacterColors, CharacterInput, GenerateOptions, SequenceStep, LipSync, LipSyncSource, Locomotion, LocomotionOptions, LookOptions };
19
20
  /** Options for playSequence(). */
20
21
  export interface SequenceOptions {
21
22
  /** Seconds each clip blends into the next (default 0.35). */
@@ -95,7 +96,16 @@ export interface AraCharacter {
95
96
  * It moves on as you call mixer.update(), and takes over the mixer's other actions.
96
97
  */
97
98
  playSequence(mixer: AnimationMixer, steps: string | readonly SequenceStep[], options?: SequenceOptions): Sequence;
98
- /** Runs blinking. Call it every frame, after mixer.update(), with the seconds since the last frame. */
99
+ /**
100
+ * Blends idle, walk and run on `mixer` by speed. Set the returned `speed` (metres per second) from your own movement
101
+ * every frame, and the steps keep pace with the ground. Load the clips first: animations: ['idle', 'walk', 'run'].
102
+ */
103
+ locomotion(mixer: AnimationMixer, options?: LocomotionOptions): Locomotion;
104
+ /** Turns the head and neck towards a point or an object (followed as it moves), within natural limits; null looks ahead. */
105
+ lookAt(target: Vector3 | Object3D | null, options?: LookOptions): void;
106
+ /** Moves the mouth with the sound of an <audio> or <video> element, a MediaStream (a microphone) or a Web Audio node. */
107
+ lipSync(source: LipSyncSource): LipSync;
108
+ /** Runs blinking, looking and lip-sync. Call it every frame, after mixer.update(), with the seconds since the last frame. */
99
109
  update(delta: number): void;
100
110
  /** Frees the GPU memory held by the character and its props. */
101
111
  dispose(): void;
@@ -43,4 +43,6 @@ export declare function clipIds(choice: GenerateOptions['animations']): string[]
43
43
  * "ara-character" object or character settings. Used by the library and the ara3d MCP server.
44
44
  */
45
45
  export declare function characterParams(lib: AssetLibrary, input: CharacterInput): HumanParams;
46
+ /** Texting and phone calls need the phone in hand: clips asked for by name bring it, unless a carried item was chosen. */
47
+ export declare const needsPhone: (clips: readonly string[], carry?: string) => boolean;
46
48
  export declare function generate(lib: AssetLibrary, input: CharacterInput, options?: GenerateOptions, onProgress?: (label: string, fraction: number) => void): Promise<Generated>;
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Movement helpers for a character: locomotion (idle, walk and run blended by speed), a head that looks at things,
3
+ * and lip-sync from audio. Each runs as the page calls mixer.update() and the character's update().
4
+ */
5
+ import { Vector3, type AnimationClip, type AnimationMixer, type Object3D } from 'three';
6
+ export interface LocomotionOptions {
7
+ /** The clips to blend, by Ara clip ID (defaults: idle, walk, run). Load them with the animations option. */
8
+ idle?: string;
9
+ walk?: string;
10
+ run?: string;
11
+ /** How quickly the gait follows a change of speed, in seconds (default 0.25). */
12
+ smoothing?: number;
13
+ }
14
+ export interface Locomotion {
15
+ /** Metres per second. Set it from your own movement every frame; 0 stands still. */
16
+ speed: number;
17
+ /** The speed at which the walk plays at its natural pace, for this character's size. */
18
+ readonly walkSpeed: number;
19
+ /** The speed at which the run plays at its natural pace. */
20
+ readonly runSpeed: number;
21
+ /** Stops blending and leaves the mixer to you. */
22
+ stop(): void;
23
+ }
24
+ export declare function locomotion(clip: (id: string) => AnimationClip | undefined, mixer: AnimationMixer, height: number, options?: LocomotionOptions): Locomotion;
25
+ export interface LookOptions {
26
+ /** How far the head turns, from 0 to 1 (default 1). */
27
+ amount?: number;
28
+ /** How quickly the head turns, in seconds (default 0.2). */
29
+ smoothing?: number;
30
+ }
31
+ export declare function lookControls(root: Object3D): {
32
+ lookAt(next: Vector3 | Object3D | null, options?: LookOptions): void;
33
+ /** After the mixer has posed the body: turns the neck and head towards the target. */
34
+ update(delta: number): void;
35
+ };
36
+ export interface LipSync {
37
+ /** Stops moving the mouth and closes it. The audio keeps playing. */
38
+ stop(): void;
39
+ }
40
+ export type LipSyncSource = HTMLMediaElement | MediaStream | AudioNode;
41
+ /**
42
+ * Reads the sound as it plays and picks a mouth shape for it: closed in silence, rounded for low vowels, open for
43
+ * mid ones, wide for bright ones, and teeth together for hissing sounds. Loudness sets how far the mouth opens.
44
+ */
45
+ export declare function lipSync(source: LipSyncSource, setMouth: (shape: string | null, weight?: number) => void): {
46
+ stop(): void;
47
+ update(delta: number): void;
48
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ara3d",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "Realistic, rigged and animated 3D characters: a three.js library, an <ara-character> embed for any web page, and a command-line tool (GLB, FBX, OBJ). Free and open source.",
5
5
  "keywords": ["web-component", "embed", "3d", "character", "avatar", "glb", "gltf", "fbx", "three", "threejs", "rigged", "animation", "makehuman", "cli", "gamedev"],
6
6
  "homepage": "https://ara3dgen.com/docs/library/",