Get the duration of an animation clip.

The duration is in seconds.

Example

let clip = animation.new_animation(walk_clip)
let duration_seconds = animation.clip_duration(walk_clip)
// Use this to sync game events with animation timing

Get the name of an animation clip.

Useful for finding specific animations by name when loading from GLTF files.

Example

import gleam/list
import tiramisu/asset

let model = asset.get_model(assets, "character")
let clips = asset.model_animations(model)

let walk_clip = list.find(clips, fn(clip) {
  animation.clip_name(clip) == "Walk"
})

Apply an easing function to a normalized value.

The value t is automatically clamped to the range [0, 1].

Example

// Linear progression
animation.ease(animation.Linear, 0.5)  // => 0.5

// Ease in quad - slow start, fast end
animation.ease(animation.EaseInQuad, 0.5)  // => 0.25

// Ease out quad - fast start, slow end
animation.ease(animation.EaseOutQuad, 0.5)  // => 0.75

Get the current interpolated value of a tween.

Applies the easing function and returns the value at the current elapsed time. Once the tween completes, this returns the end value.

Example

let tween = animation.tween_float(0.0, 100.0, 1000.0, animation.Linear)
  |> animation.update_tween(500.0)  // Halfway through

let value = animation.get_tween_value(tween)  // => 50.0

Check if a tween has finished playing.

Example

fn update(model: Model, msg: Msg, ctx: Context) {
  let updated_tween = animation.update_tween(model.tween, ctx.delta_time)

  case animation.is_tween_complete(updated_tween) {
    True -> {
      // Tween finished, trigger next animation or event
      #(Model(..model, tween: animation.reset_tween(updated_tween)), effect.none())
    }
    False -> #(Model(..model, tween: updated_tween), effect.none())
  }
}

Create an animation from a clip with default settings.

Defaults: loop repeat, normal speed (1.0x), full weight (1.0).

Example

import tiramisu/animation
import tiramisu/asset

let model = asset.get_model(assets, "character")
let clips = asset.model_animations(model)
let walk_clip = list.find(clips, fn(clip) { animation.clip_name(clip) == "Walk" })

let walk_animation = animation.new_animation(walk_clip)

Reset a tween back to the beginning (elapsed time = 0).

Example

// Play the tween again from the start
let reset = animation.reset_tween(completed_tween)

Reverse a tween by swapping its start and end values.

The elapsed time is preserved, so the tween continues from where it was but in the opposite direction.

Example

// Create a bouncing animation
fn update(model: Model, msg: Msg, ctx: Context) {
  let updated_tween = animation.update_tween(model.tween, ctx.delta_time)

  case animation.is_tween_complete(updated_tween) {
    True -> {
      // Bounce back by reversing the tween
      let reversed = animation.reverse_tween(updated_tween)
        |> animation.reset_tween()
      Model(..model, tween: reversed)
    }
    False -> Model(..model, tween: updated_tween)
  }
}

Set the loop mode for an animation.

Example

let jump_animation = animation.new_animation(jump_clip)
  |> animation.set_loop(animation.LoopOnce)  // Play once, don't loop

Set the playback speed multiplier.

The speed multiplier affects how fast the animation plays:

• 1.0 = normal speed
• 2.0 = double speed (twice as fast)
• 0.5 = half speed (slow motion)
• Negative values play the animation in reverse

Example

let run_animation = animation.new_animation(run_clip)
  |> animation.set_speed(1.5)  // 50% faster running

Set the animation weight for blending.

The weight value ranges from 0.0 to 1.0:

• 1.0 = full influence (default)
• 0.5 = half influence (useful for blending)
• 0.0 = no influence (animation has no effect)

Example

// Blend two animations manually
let walk = animation.new_animation(walk_clip) |> animation.set_weight(0.7)
let idle = animation.new_animation(idle_clip) |> animation.set_weight(0.3)

// Or use BlendedAnimations with a blend factor
animation.BlendedAnimations(from: walk, to: idle, blend_factor: 0.5)

Create a new tween with a custom interpolation function.

For most use cases, prefer tween_float(), tween_vec3(), or tween_transform().

Example

// Custom tween for a color value
type Color {
  Color(r: Float, g: Float, b: Float)
}

let color_tween = animation.tween(
  start: Color(1.0, 0.0, 0.0),  // Red
  end: Color(0.0, 0.0, 1.0),    // Blue
  duration: 1000.0,  // milliseconds
  easing: animation.EaseInOutQuad,
  lerp_fn: fn(a, b, t) {
    Color(
      r: a.r +. { b.r -. a.r } *. t,
      g: a.g +. { b.g -. a.g } *. t,
      b: a.b +. { b.b -. a.b } *. t,
    )
  },
)

Create a tween that interpolates a Float value.

The duration is in milliseconds.

Example

// Fade from 0.0 to 1.0 over 2 seconds
let fade_tween = animation.tween_float(
  start: 0.0,
  end: 1.0,
  duration: 2000.0,  // milliseconds
  easing: animation.EaseInOutQuad,
)

Create a tween that interpolates a Transform (position, rotation, and scale).

The duration is in milliseconds.

Example

import tiramisu/transform
import vec/vec3

let start_transform = transform.at(position: vec3.Vec3(0.0, 0.0, 0.0))
  |> transform.scale(1.0)

let end_transform = transform.at(position: vec3.Vec3(5.0, 0.0, 0.0))
  |> transform.scale(2.0)
  |> transform.rotate_y(3.14159)

let transform_tween = animation.tween_transform(
  start: start_transform,
  end: end_transform,
  duration: 1500.0,  // milliseconds
  easing: animation.EaseInOutCubic,
)

Create a tween that interpolates a Vec3 value (useful for positions).

The duration is in milliseconds.

Example

import vec/vec3

// Move from origin to (10, 5, 0) over 3 seconds
let position_tween = animation.tween_vec3(
  start: vec3.Vec3(0.0, 0.0, 0.0),
  end: vec3.Vec3(10.0, 5.0, 0.0),
  duration: 3000.0,  // milliseconds
  easing: animation.EaseOutQuad,
)

Update a tween by advancing its elapsed time.

The delta parameter is in milliseconds (typically from ctx.delta_time).

Example

fn update(model: Model, msg: Msg, ctx: Context) {
  // Advance the tween by the frame delta
  let updated_tween = animation.update_tween(model.tween, ctx.delta_time)
  Model(..model, tween: updated_tween)
}