KeyframeSequence.yaml

name: KeyframeSequence
type: class
category: Animations
memory_category: Animation
summary: |
  This object stores all of the `Class.Keyframe|Keyframes` and other data for
  the animation.
description: |
  This object stores all the `Class.Keyframe|Keyframes` for an animation,
  determines if the animation is looped, and determines its priority against
  other animations.

  ## What is a KeyframeSequence?

  Roblox constructs the animation data it uses in the playback of an animation,
  referenced by the `Class.Animation.AnimationId` property from a
  KeyframeSequence. Every animation refers to a KeyframeSequence or to a
  CurveAnimation internally. Although, usually created by the Roblox Animation
  Editor, KeyframeSequence can also be created by other plugins or even
  manually. Once uploaded to Roblox, Roblox assigns a Content ID that
  `Class.Animation|Animations` use for the `Class.Animation.AnimationId`
  property to refer to the uploaded KeyframeSequence.

  Note, in most cases, you do not need to manipulate KeyframeSequences, as the
  animation editor covers most animation functionality. However, in some cases
  you may wish to generate an animation from a `Class.Script` or build your own
  plugin. However, only Roblox Studio can use a KeyframeSequence created in such
  a way. If you wish to use such a KeyframeSequence, you will need to upload it
  to Roblox as described below.

  ## KeyframeSequence Properties

  `Class.KeyframeSequence.Priority` and `Class.KeyframeSequence.Loop` save the
  priority and looped animation settings for the sequence. Note that
  `Class.AnimationTrack` properties can eventually overwrite these properties at
  playback time.

  The last `Class.Keyframe` in the sequence, meaning the `Class.Keyframe` with
  the highest `Class.Keyframe.Time` property, determines the length of an
  animation.

  ## KeyframeSequence Structure

  KeyframeSequences act as a container that hold `Class.Keyframe|Keyframes`.
  Keyframes represent a 'key' frame in the animation, that are interpolated
  between during playback.

  Keyframes contain `Class.Pose|Poses`. `Class.Pose|Poses`, specific to each
  `Class.BasePart` being animated, contain the `Datatype.CFrame` applied to the
  `Class.Motor6D` connecting two parts. Poses match the `Class.BasePart` they
  correspond with by name and apply their data to the `Class.Motor6D` with this
  same-named part identified as `Class.Motor6D.P1` . For this reason, animations
  require distinct part names to play correctly.

  Poses follow a structure based on joint hierarchy. The parent of each
  `Class.Pose` corresponds to the `Class.Pose` of the part it is attached to. In
  practice, this means the poses branch out from the root part. See below for a
  visual example.

  ## Using KeyframeSequences when making animations

  You must first upload KeyframeSequences to Roblox before they can be played in
  an experience. In Studio, right click on the KeyframeSequence and click 'Save
  to Roblox'. Alternatively, you can use the
  `Class.Plugin:SaveSelectedToRoblox()` function. Either method will bring up
  the animation upload window and allow you to upload your KeyframeSequence as
  an animation.

  In some cases, you may want to preview an Animation before uploading it to the
  Roblox site. You can generate a temporary id using
  `Class.KeyframeSequenceProvider:RegisterKeyframeSequence()`. This will
  generate a hash id that can be used for localized animation testing.

  ## Obtaining KeyframeSequences

  In some cases you may wish to download the KeyframeSequence corresponding to
  an existing uploaded Animation. You can use
  `Class.AnimationClipProvider:GetAnimationClipAsync()` to download an
  animation.
code_samples:
  - Get-KeyframeSequence-Length
  - KeyframeSequenceProvider-RegisterKeyframeSequence
  - KeyframeSequence-Instantiation
inherits:
  - AnimationClip
tags: []
deprecation_message: ''
properties:
  - name: KeyframeSequence.AuthoredHipHeight
    summary: |
      Contains the hip height of the `Class.Humanoid` of the model that was used
      to author this `Class.KeyframeSequence`.
    description: |
      Contains the hip height of the `Class.Humanoid` of the model that was used
      to author this `Class.KeyframeSequence`. Default value is 1.35 since that
      is the hip height set for a standard R15 `Character|character`.
    code_samples:
    type: float
    tags:
      - Hidden
    deprecation_message: ''
    security:
      read: PluginSecurity
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: true
      can_save: true
methods:
  - name: KeyframeSequence:AddKeyframe
    summary: |
      Adds a `Class.Keyframe` to the `Class.KeyframeSequence` by parenting it to
      the `Class.KeyframeSequence`.
    description: |
      This function adds a `Class.Keyframe` to the `Class.KeyframeSequence` by
      parenting it to the `Class.KeyframeSequence`. It is functionally identical
      to setting the keyframe's `Class.Instance.Parent` to the
      `Class.KeyframeSequence`.

      Note, this function will not error when called with an instance other than
      a `Class.Keyframe` as the keyframe parameter and will parent it
      successfully.
    code_samples:
      - KeyframeSequence-Instantiation
    parameters:
      - name: keyframe
        type: Instance
        default:
        summary: |
          The `Class.Keyframe` to be added.
    returns:
      - type: void
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
  - name: KeyframeSequence:GetKeyframes
    summary: |
      Returns an array that contains all `Class.Keyframe|Keyframes` contained in
      a `Class.KeyframeSequence`.
    description: |
      **GetKeyframes** returns an array that contains all
      `Class.Keyframe|Keyframes` that have been added to a
      `Class.KeyframeSequence`.
    code_samples:
      - Get-KeyframeSequence-Length
    parameters: []
    returns:
      - type: Objects
        summary: |
          An array of `Class.Keyframe|Keyframe`.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
  - name: KeyframeSequence:RemoveKeyframe
    summary: |
      This function removes a `Class.Keyframe` from the `Class.KeyframeSequence`
      by setting its parent to nil.
    description: |
      This function removes a `Class.Keyframe` from the `Class.KeyframeSequence`
      by setting its parent to nil. It is functionally identical to setting the
      keyframe's parent to nil.

      This sets the keyframe's parent to `nil`, but does not destroy it. This
      means, provided another reference to the keyframe remains, it can be
      re-parented later.

      Note, this function will not error when called with an `Class.Instance`
      other than a `Class.Keyframe` as the keyframe parameter.
    code_samples:
      - KeyframeSequence-RemoveKeyframe
    parameters:
      - name: keyframe
        type: Instance
        default:
        summary: |
          The `Class.Keyframe` to be removed.
    returns:
      - type: void
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
events: []
callbacks: []