ara3d 0.4.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.
@@ -6,17 +6,23 @@ export declare class AraCharacterElement extends HTMLElement {
6
6
  private view?;
7
7
  private status;
8
8
  private figure;
9
- private bar;
10
9
  private label;
11
10
  private building;
12
11
  private queued;
13
12
  private visible;
14
13
  private sequence?;
14
+ /** The clip playing on the character, for playClip()'s blends. */
15
+ private active?;
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;
15
21
  constructor();
16
22
  connectedCallback(): void;
17
23
  disconnectedCallback(): void;
18
24
  attributeChangedCallback(name: string, before: string | null, after: string | null): void;
19
- /** What plays: the animation attribute (one clip, or a sequence such as "walk 3s, wave"), a vehicle's riding clip, or idle. */
25
+ /** What plays: the animation attribute (one clip, or a sequence such as "walk 3s, look_around"), a vehicle's riding clip, or idle. */
20
26
  get animation(): string;
21
27
  /** The clips the animation uses, each once. */
22
28
  private clipIds;
@@ -25,9 +31,25 @@ export declare class AraCharacterElement extends HTMLElement {
25
31
  private applyExpression;
26
32
  private fit;
27
33
  /** Frames the character and any vehicle from the front-right. */
34
+ /**
35
+ * The space the character fills while its animations play: each clip is posed at its start, middle and end, so a
36
+ * swim or a crouch is framed as well as standing. Props count as they stand.
37
+ */
38
+ private extent;
28
39
  private frame;
40
+ /** The current frame as a 2D canvas, for thumbnails and transitions; transparent where there's no background. */
41
+ snapshot(): HTMLCanvasElement | undefined;
42
+ /** Starts the animation again from the beginning. */
43
+ restart(): void;
29
44
  private play;
45
+ /**
46
+ * Blends to a loaded clip (from animation or clips) without rebuilding or reframing, for games and controls:
47
+ * el.playClip('run'). Returns false if the clip isn't loaded.
48
+ */
49
+ playClip(id: string, fade?: number): boolean;
30
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;
31
53
  /** What to build, from the attributes. */
32
54
  private input;
33
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). */
@@ -90,12 +91,21 @@ export interface AraCharacter {
90
91
  /** Natural blinking, on by default; call update() every frame for it to run. */
91
92
  blinking: boolean;
92
93
  /**
93
- * Plays clips one after another on `mixer`, blending each into the next, such as "walk 3s, wave, cheer x2". A step
94
- * that loops (walk, idle) plays one cycle unless given a length; others (wave, jump) play once, or a number of times.
94
+ * Plays clips one after another on `mixer`, blending each into the next, such as "run 2s, vault_over, ledge_climb_up". A step
95
+ * that loops (walk, idle) plays one cycle unless given a length; others (vault_over, jump) play once, or a number of times.
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
+ };
@@ -1,4 +1,4 @@
1
- /** Animation sequences, such as "walk 3s, wave, cheer x2": the steps the library's playSequence() and the embed play. */
1
+ /** Animation sequences, such as "run 2s, vault_over, ledge_climb_up": the steps the library's playSequence() and the embed play. */
2
2
  /** One step: a clip ID, with an optional length in seconds or a number of times to play it. */
3
3
  export type SequenceStep = string | {
4
4
  clip: string;
@@ -10,5 +10,5 @@ export interface ParsedStep {
10
10
  seconds?: number;
11
11
  times?: number;
12
12
  }
13
- /** Reads "walk 3s, wave, cheer x2" (or an array of steps) into clip IDs with their lengths or counts. */
13
+ /** Reads "run 2s, vault_over, ledge_climb_up" (or an array of steps) into clip IDs with their lengths or counts. */
14
14
  export declare function parseSteps(steps: string | readonly SequenceStep[]): ParsedStep[];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ara3d",
3
- "version": "0.4.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/",