TweenService.yaml

name: TweenService
type: class
category: Animations
memory_category: Instances
summary: |
  Used to create `Class.Tween|Tweens` which interpolate, or tween, the
  properties of instances.
description: |
  `Class.TweenService` is used to create `Class.Tween|Tweens` which interpolate,
  or tween, the properties of instances. `Class.Tween|Tweens` can be used on any
  object with compatible property types, including:

  - [number](../../../luau/numbers.md)
  - [boolean](../../../luau/booleans.md)
  - `Datatype.CFrame`
  - `Datatype.Rect`
  - `Datatype.Color3`
  - `Datatype.UDim`
  - `Datatype.UDim2`
  - `Datatype.Vector2`
  - `Datatype.Vector2int16`
  - `Datatype.Vector3`
  - `Datatype.EnumItem`

  `Class.TweenService:Create()`, the primary constructor function, takes
  `Datatype.TweenInfo` specifications about the tween and generates the
  `Class.Tween` object which can then be used to play the tween.

  Note that `Class.Tween|Tweens` can interpolate multiple properties at the same
  time, but they must not be interpolating the same property. If two tweens
  attempt to modify the same property, the initial tween will be cancelled and
  overwritten by the most recent tween.
code_samples:
  - Tween-Creation
  - Looped-Tween
  - Tween-Pausing
inherits:
  - Instance
tags:
  - NotCreatable
  - Service
deprecation_message: ''
properties: []
methods:
  - name: TweenService:Create
    summary: |
      Creates a new `Class.Tween` given the object whose properties are to be
      tweened, a `Datatype.TweenInfo`, and a dictionary of goal property values.
    description: |
      This constructor creates a new `Class.Tween` from three arguments: the
      object to tween, the `Datatype.TweenInfo` specifications, and a table
      containing the properties to tween and values to tween to.

      The `propertyTable` parameter needs to be a dictionary where the keys are
      the string names of the property (for example `Position`, `Transparency`,
      or `Color`), and the values are the property targets at the end of the
      tween.

      The `Class.Tween` created using this function is unique to the object
      given as the `instance` parameter. To apply the same tween to another
      object, call this function again with the new object.
    code_samples:
      - Tween-Creation
      - Looped-Tween
    parameters:
      - name: instance
        type: Instance
        default:
        summary: |
          The `Class.Instance` whose properties are to be tweened.
      - name: tweenInfo
        type: TweenInfo
        default:
        summary: |
          The `Datatype.TweenInfo` to be used.
      - name: propertyTable
        type: Dictionary
        default:
        summary: |
          A dictionary of properties, and their target values, to be tweened.
    returns:
      - type: Tween
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities: []
    writeCapabilities: []
  - name: TweenService:GetValue
    summary: |
      Calculates a new alpha given an `Enum.EasingStyle` and
      `Enum.EasingDirection`.
    description: |
      Returns a new alpha value for interpolating using the given alpha value,
      `Enum.EasingStyle`, and `Enum.EasingDirection`. The provided `alpha` value
      will be clamped between `0` and `1`.
    code_samples:
    parameters:
      - name: alpha
        type: float
        default:
        summary: |
          An interpolation value between `0` and `1`.
      - name: easingStyle
        type: EasingStyle
        default:
        summary: |
          The easing style to use.
      - name: easingDirection
        type: EasingDirection
        default:
        summary: |
          The easing direction to use.
    returns:
      - type: float
        summary: |
          A new alpha value generated from the given easing style and direction.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities: []
    writeCapabilities: []
  - name: TweenService:SmoothDamp
    summary: |
      Calculates a value simulating a critically damped spring.
    description: |
      Returns a tuple that allows smoothing a value towards a target, simulating
      a critically damped spring. Supports `Datatype.Vector2`,
      `Datatype.Vector3`, `Datatype.CFrame`, and number.
    code_samples: []
    parameters:
      - name: current
        type: Variant
        default:
        summary:
          The current position.
      - name: target
        type: Variant
        default:
        summary:
          The target position.
      - name: velocity
        type: Variant
        default:
        summary:
          The initial velocity at which the current position should approach the target position.
      - name: smoothTime
        type: float
        default:
        summary:
          The duration in which the total smoothing operation should take place.
      - name: maxSpeed
        type: float?
        default:
        summary:
          The maximum speed at which the current position should approach the target position.
      - name: dt
        type: float?
        default:
        summary:
          The rate at which the smoothing operation should be applied.
    returns:
      - type: Tuple
        summary:
          The new position and velocity calculated from the smoothing operation.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Safe
    capabilities: []
    writeCapabilities: []
events: []
callbacks: []