Class AnimatorControllerBuilder<TStates, TParams>

A fluent builder for creating AnimatorController instances from code.

Use AnimatorControllerBuilder.create or AnimatorController.build to create a new builder.

The builder tracks state names and parameter types through the fluent chain, providing autocomplete for state names in .transition() and type-aware .condition() calls (e.g., trigger parameters don't require a mode argument).

Example: With pre-built AnimationClips

const controller = AnimatorControllerBuilder.create("CharacterController")
    .floatParameter("Speed", 0)
    .triggerParameter("Jump")
    .state("Idle", { clip: idleClip, loop: true })
    .state("Walk", { clip: walkClip, loop: true })
    .state("Jump", { clip: jumpClip })
    .transition("Idle", "Walk", { duration: 0.25 })
        .condition("Speed", "greater", 0.1)
    .transition("Walk", "Idle", { duration: 0.25 })
        .condition("Speed", "less", 0.1)
    .transition("*", "Jump", { duration: 0.1 })
        .condition("Jump")
    .transition("Jump", "Idle", { hasExitTime: true, exitTime: 0.9, duration: 0.25 })
    .build();

Example: With inline tracks (no pre-built clips needed)

const controller = AnimatorControllerBuilder.create("Door")
    .boolParameter("Open", false)
    .state("Closed", { loop: true })
        .track(door, "position", { from: [0, 0, 0], to: [0, 0, 0], duration: 1 })
    .state("Open", { loop: true })
        .track(door, "position", { from: [0, 0, 0], to: [2, 0, 0], duration: 1 })
        .track(light, "intensity", { from: 0, to: 5, duration: 1 })
    .transition("Closed", "Open", { duration: 0.25 })
        .condition("Open", "if")
    .transition("Open", "Closed", { duration: 0.25 })
        .condition("Open", "ifNot")
    .build(room);

Type Parameters

TStates extends string = never
Union of state names added via .state(). Used for autocomplete and validation in .transition() and .defaultState().
TParams extends Record<string, "trigger" | "bool" | "float" | "int"> = {}
Record mapping parameter names to their types ("trigger", "bool", "float", "int"). Used for type-aware .condition() overloads.

Index

Constructors

constructor

Methods

boolParameter build condition defaultState floatParameter intParameter state track transition triggerParameter create

Constructors

constructor

new AnimatorControllerBuilder<
    TStates extends string = never,
    TParams extends Record<string, "trigger" | "bool" | "float" | "int"> = {},
>(
    name?: string,
): AnimatorControllerBuilder<TStates, TParams>
Type Parameters
- TStates extends string = never
- TParams extends Record<string, "trigger" | "bool" | "float" | "int"> = {}
Parameters
- Optionalname: string
Returns AnimatorControllerBuilder<TStates, TParams>

Methods

boolParameter

boolParameter<N extends string>(
name: N,
defaultValue?: boolean,
): AnimatorControllerBuilder<TStates, TParams & Record<N, "bool">>
Adds a boolean parameter
Type Parameters
- N extends string
Parameters
- name: N
- defaultValue: boolean = false
Returns AnimatorControllerBuilder<TStates, TParams & Record<N, "bool">>

build

build(root?: Object3D<Object3DEventMap>): AnimatorController
Builds and returns the AnimatorController. Resolves all state name references to indices.
Parameters
- Optionalroot: Object3D<Object3DEventMap>
  Optional root Object3D for resolving TrackDescriptor track paths. When provided, tracks targeting a different object use target.name for named resolution.
Returns AnimatorController

condition

condition(
parameter: ParamNamesOfType<TParams, "trigger">,
mode?: "if" | "ifNot",
): AnimatorControllerBuilder<TStates, TParams>
Adds a condition to the most recently added transition. Multiple conditions on the same transition are AND-ed together.

The required arguments depend on the parameter type:
- Trigger: .condition("Jump") — mode defaults to "if", no threshold needed
- Bool: .condition("Open", "if") or .condition("Open", "ifNot")
- Float/Int: .condition("Speed", "greater", 0.1)
Parameters
- parameter: ParamNamesOfType<TParams, "trigger">
  Name of the parameter to evaluate
- Optionalmode: "if" | "ifNot"
Returns AnimatorControllerBuilder<TStates, TParams>
condition(
parameter: ParamNamesOfType<TParams, "bool">,
mode: "if" | "ifNot",
): AnimatorControllerBuilder<TStates, TParams>
Adds a condition to the most recently added transition. Multiple conditions on the same transition are AND-ed together.

The required arguments depend on the parameter type:
- Trigger: .condition("Jump") — mode defaults to "if", no threshold needed
- Bool: .condition("Open", "if") or .condition("Open", "ifNot")
- Float/Int: .condition("Speed", "greater", 0.1)
Parameters
- parameter: ParamNamesOfType<TParams, "bool">
  Name of the parameter to evaluate
- mode: "if" | "ifNot"
Returns AnimatorControllerBuilder<TStates, TParams>
condition(
    parameter: ParamNamesOfType<TParams, "float" | "int">,
    mode: "greater" | "less" | "equals" | "notEqual",
    threshold?: number,
): AnimatorControllerBuilder<TStates, TParams>
Adds a condition to the most recently added transition. Multiple conditions on the same transition are AND-ed together.

The required arguments depend on the parameter type:
- Trigger: .condition("Jump") — mode defaults to "if", no threshold needed
- Bool: .condition("Open", "if") or .condition("Open", "ifNot")
- Float/Int: .condition("Speed", "greater", 0.1)
Parameters
- parameter: ParamNamesOfType<TParams, "float" | "int">
  Name of the parameter to evaluate
- mode: "greater" | "less" | "equals" | "notEqual"
- Optionalthreshold: number
Returns AnimatorControllerBuilder<TStates, TParams>

defaultState

defaultState(name: TStates): AnimatorControllerBuilder<TStates, TParams>
Sets which state is the default/entry state. If not called, the first added state is used.
Parameters
- name: TStates
  Name of the state
Returns AnimatorControllerBuilder<TStates, TParams>

floatParameter

floatParameter<N extends string>(
name: N,
defaultValue?: number,
): AnimatorControllerBuilder<TStates, TParams & Record<N, "float">>
Adds a float parameter
Type Parameters
- N extends string
Parameters
- name: N
- defaultValue: number = 0
Returns AnimatorControllerBuilder<TStates, TParams & Record<N, "float">>

intParameter

intParameter<N extends string>(
name: N,
defaultValue?: number,
): AnimatorControllerBuilder<TStates, TParams & Record<N, "int">>
Adds an integer parameter
Type Parameters
- N extends string
Parameters
- name: N
- defaultValue: number = 0
Returns AnimatorControllerBuilder<TStates, TParams & Record<N, "int">>

state

state<N extends string>(
name: N,
options?: StateOptions,
): AnimatorControllerBuilder<TStates | N, TParams>
Adds a state to the controller. The first state added becomes the default state.

When options.clip is provided, the state uses that clip directly. When omitted, chain .track() calls to define animation tracks inline:
```
.state("Open", { loop: true })
    .track(door, "position", { from: [0,0,0], to: [2,0,0], duration: 1 })
    .track(light, "intensity", { from: 0, to: 5, duration: 1 })
```
Type Parameters
- N extends string
Parameters
- name: N
  Unique name for the state
- Optionaloptions: StateOptions
  State configuration including clip, loop, speed. When omitted, use .track() to add animation data.
Returns AnimatorControllerBuilder<TStates | N, TParams>

track

track(
    target: Object3D,
    property: "position" | "scale",
    keyframes: KF<Vec3Value>,
    options?: TrackOptions,
): this
Adds an animation track for an Object3D's position or scale to the current state
Parameters
- target: Object3D
- property: "position" | "scale"
- keyframes: KF<Vec3Value>
- Optionaloptions: TrackOptions
Returns this
track(
    target: Object3D,
    property: "quaternion",
    keyframes: KF<QuatValue>,
    options?: TrackOptions,
): this
Adds an animation track for an Object3D's quaternion to the current state
Parameters
- target: Object3D
- property: "quaternion"
- keyframes: KF<QuatValue>
- Optionaloptions: TrackOptions
Returns this
track(
    target: Object3D,
    property: "rotation",
    keyframes: KF<EulerValue>,
    options?: TrackOptions,
): this
Adds an animation track for an Object3D's rotation (Euler, converted to quaternion) to the current state
Parameters
- target: Object3D
- property: "rotation"
- keyframes: KF<EulerValue>
- Optionaloptions: TrackOptions
Returns this
track(
    target: Object3D,
    property: "visible",
    keyframes: KF<boolean>,
    options?: TrackOptions,
): this
Adds an animation track for an Object3D's visibility to the current state
Parameters
- target: Object3D
- property: "visible"
- keyframes: KF<boolean>
- Optionaloptions: TrackOptions
Returns this
track(
    target: Material,
    property:
        | "opacity"
        | "roughness"
        | "metalness"
        | "alphaTest"
        | "emissiveIntensity"
        | "envMapIntensity"
        | "bumpScale"
        | "displacementScale"
        | "displacementBias",
    keyframes: KF<number>,
    options?: TrackOptions,
): this
Adds an animation track for a material's numeric property to the current state
Parameters
- target: Material
- property:
      | "opacity"
      | "roughness"
      | "metalness"
      | "alphaTest"
      | "emissiveIntensity"
      | "envMapIntensity"
      | "bumpScale"
      | "displacementScale"
      | "displacementBias"
- keyframes: KF<number>
- Optionaloptions: TrackOptions
Returns this
track(
    target: Material,
    property: "color" | "emissive",
    keyframes: KF<ColorValue>,
    options?: TrackOptions,
): this
Adds an animation track for a material's color property to the current state
Parameters
- target: Material
- property: "color" | "emissive"
- keyframes: KF<ColorValue>
- Optionaloptions: TrackOptions
Returns this
track(
    target: Light,
    property: "intensity" | "distance" | "angle" | "penumbra" | "decay",
    keyframes: KF<number>,
    options?: TrackOptions,
): this
Adds an animation track for a light's numeric property to the current state
Parameters
- target: Light
- property: "intensity" | "distance" | "angle" | "penumbra" | "decay"
- keyframes: KF<number>
- Optionaloptions: TrackOptions
Returns this
track(
    target: Light,
    property: "color",
    keyframes: KF<ColorValue>,
    options?: TrackOptions,
): this
Adds an animation track for a light's color to the current state
Parameters
- target: Light
- property: "color"
- keyframes: KF<ColorValue>
- Optionaloptions: TrackOptions
Returns this
track(
    target: PerspectiveCamera,
    property: "zoom" | "fov" | "near" | "far",
    keyframes: KF<number>,
    options?: TrackOptions,
): this
Adds an animation track for a camera's numeric property to the current state
Parameters
- target: PerspectiveCamera
- property: "zoom" | "fov" | "near" | "far"
- keyframes: KF<number>
- Optionaloptions: TrackOptions
Returns this

transition

transition(
    from: TStates | "*",
    to: TStates,
    options?: TransitionOptions,
): AnimatorControllerBuilder<TStates, TParams>
Adds a transition between two states. Use "*" as the source to create a transition from any state. Chain .condition() calls after this to add conditions.
Parameters
- from: TStates | "*"
  Source state name, or "*" for any-state transition
- to: TStates
  Destination state name
- Optionaloptions: TransitionOptions
  Transition configuration
Returns AnimatorControllerBuilder<TStates, TParams>

triggerParameter

triggerParameter<N extends string>(
name: N,
): AnimatorControllerBuilder<TStates, TParams & Record<N, "trigger">>
Adds a trigger parameter
Type Parameters
- N extends string
Parameters
- name: N
Returns AnimatorControllerBuilder<TStates, TParams & Record<N, "trigger">>

`Static`create

create(name?: string): AnimatorControllerBuilder
Creates a new AnimatorControllerBuilder instance.
Parameters
- Optionalname: string
  Optional name for the controller
Returns AnimatorControllerBuilder

Class AnimatorControllerBuilder<TStates, TParams>

Example: With pre-built AnimationClips

Example: With inline tracks (no pre-built clips needed)

Type Parameters

Index

Constructors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns AnimatorControllerBuilder<TStates, TParams>

Methods

boolParameter

Type Parameters

Parameters

Returns AnimatorControllerBuilder<TStates, TParams & Record<N, "bool">>

build

Parameters

Returns AnimatorController

condition

Parameters

Returns AnimatorControllerBuilder<TStates, TParams>

Parameters

Returns AnimatorControllerBuilder<TStates, TParams>

Parameters

Returns AnimatorControllerBuilder<TStates, TParams>

defaultState

Parameters

Returns AnimatorControllerBuilder<TStates, TParams>

floatParameter

Type Parameters

Parameters

Returns AnimatorControllerBuilder<TStates, TParams & Record<N, "float">>

intParameter

Type Parameters

Parameters

Returns AnimatorControllerBuilder<TStates, TParams & Record<N, "int">>

state

Type Parameters

Parameters

Returns AnimatorControllerBuilder<TStates | N, TParams>

track

Parameters

Returns this

Parameters

Returns this

Parameters

Returns this

Parameters

Returns this

Parameters

Returns this

Parameters

Returns this

Parameters

Returns this

Parameters

Returns this

Parameters

Returns this

transition

Parameters

Returns AnimatorControllerBuilder<TStates, TParams>

triggerParameter

Type Parameters

Parameters

Returns AnimatorControllerBuilder<TStates, TParams & Record<N, "trigger">>

Staticcreate

Parameters

Returns AnimatorControllerBuilder

Settings

On This Page

`Static`create