Support Animation Layers for Skinned Meshes

Resources/Engine/Lua/Components/SkinnedMeshRenderer.lua

@@ -1,41 +1,79 @@
 ---@meta
 
 --- A component responsible for skeletal animation playback and skinning runtime control
+--- Any number of animations can play at once, each layer owning its own animation source model,
+--- animation, time, speed, loop mode and weight.
+--- Layer arguments default to 0 (the base layer), which always exists
 ---@class SkinnedMeshRenderer : Component
 SkinnedMeshRenderer = {}
 
 --- Returns the actor that owns this component
 ---@return Actor
 function SkinnedMeshRenderer:GetOwner() end
 
---- Starts/resumes animation playback
-function SkinnedMeshRenderer:Play() end
+--- Returns the number of active animation layers (always at least 1)
+---@return integer
+function SkinnedMeshRenderer:GetLayerCount() end
+
+--- Appends a new animation layer and returns its index
+---@return integer
+function SkinnedMeshRenderer:AddLayer() end
 
---- Pauses animation playback
-function SkinnedMeshRenderer:Pause() end
+--- Removes an animation layer, shifting the following layers down by one.
+--- Fails when the index is invalid or when only one layer remains
+---@param layer integer
+---@return boolean
+function SkinnedMeshRenderer:RemoveLayer(layer) end
 
---- Stops playback and resets time to start
-function SkinnedMeshRenderer:Stop() end
+--- Starts/resumes animation playback on a layer
+---@param layer? integer
+function SkinnedMeshRenderer:Play(layer) end
 
---- Returns whether playback is active
+--- Pauses animation playback on a layer
+---@param layer? integer
+function SkinnedMeshRenderer:Pause(layer) end
+
+--- Stops playback on a layer and resets its time to start
+---@param layer? integer
+function SkinnedMeshRenderer:Stop(layer) end
+
+--- Returns whether playback is active on a layer
+---@param layer? integer
 ---@return boolean
-function SkinnedMeshRenderer:IsPlaying() end
+function SkinnedMeshRenderer:IsPlaying(layer) end
 
---- Sets looping mode
+--- Sets looping mode on a layer
 ---@param loop boolean
-function SkinnedMeshRenderer:SetLooping(loop) end
+---@param layer? integer
+function SkinnedMeshRenderer:SetLooping(loop, layer) end
 
---- Returns whether looping is enabled
+--- Returns whether looping is enabled on a layer
+---@param layer? integer
 ---@return boolean
-function SkinnedMeshRenderer:IsLooping() end
+function SkinnedMeshRenderer:IsLooping(layer) end
 
---- Sets animation playback speed
+--- Sets animation playback speed on a layer
 ---@param speed number
-function SkinnedMeshRenderer:SetPlaybackSpeed(speed) end
+---@param layer? integer
+function SkinnedMeshRenderer:SetPlaybackSpeed(speed, layer) end
 
---- Returns current playback speed
+--- Returns the playback speed of a layer
+---@param layer? integer
+---@return number
+function SkinnedMeshRenderer:GetPlaybackSpeed(layer) end
+
+--- Sets the blend weight of a layer, clamped to the [0,1] range
+--- Weights are normalized per bone against the other layers animating that bone, so a layer
+--- animating a bone alone contributes fully until its weight reaches 0, where the bone falls
+--- back to its bind pose
+---@param weight number
+---@param layer? integer
+function SkinnedMeshRenderer:SetLayerWeight(weight, layer) end
+
+--- Returns the blend weight of a layer
+---@param layer? integer
 ---@return number
-function SkinnedMeshRenderer:GetPlaybackSpeed() end
+function SkinnedMeshRenderer:GetLayerWeight(layer) end
 
 --- Sets the bounds scale used during frustum culling for skinned meshes
 --- Values below 1.0 are clamped to 1.0
@@ -47,48 +85,57 @@ function SkinnedMeshRenderer:SetMeshBoundsScale(scale) end
 ---@return number
 function SkinnedMeshRenderer:GetMeshBoundsScale() end
 
---- Sets playback time in seconds
+--- Sets the playback time of a layer in seconds
 ---@param timeSeconds number
-function SkinnedMeshRenderer:SetTime(timeSeconds) end
+---@param layer? integer
+function SkinnedMeshRenderer:SetTime(timeSeconds, layer) end
 
---- Returns playback time in seconds
+--- Returns the playback time of a layer in seconds
+---@param layer? integer
 ---@return number
-function SkinnedMeshRenderer:GetTime() end
+function SkinnedMeshRenderer:GetTime(layer) end
 
---- Sets an external model used as animation source, or nil to use the rendered model
+--- Sets the external model used as animation source by a layer, or nil to use the rendered model
 ---@param model Model|nil
-function SkinnedMeshRenderer:SetAnimationSourceModel(model) end
+---@param layer? integer
+function SkinnedMeshRenderer:SetAnimationSourceModel(model, layer) end
 
---- Returns the external animation source model, or nil when the rendered model is used
+--- Returns the external animation source model of a layer, or nil when the rendered model is used
+---@param layer? integer
 ---@return Model|nil
-function SkinnedMeshRenderer:GetAnimationSourceModel() end
+function SkinnedMeshRenderer:GetAnimationSourceModel(layer) end
 
---- Returns whether the current animation source is compatible with the rendered model skeleton
+--- Returns whether the animation source of a layer is compatible with the rendered model skeleton
+---@param layer? integer
 ---@return boolean
-function SkinnedMeshRenderer:IsAnimationSourceCompatible() end
+function SkinnedMeshRenderer:IsAnimationSourceCompatible(layer) end
 
---- Returns the number of available animation clips
+--- Returns the number of animation clips available to a layer
+---@param layer? integer
 ---@return integer
-function SkinnedMeshRenderer:GetAnimationCount() end
+function SkinnedMeshRenderer:GetAnimationCount(layer) end
 
---- Returns clip name at index or nil
+--- Returns the clip name at index for a layer, or nil
 ---@param index integer
+---@param layer? integer
 ---@return string|nil
-function SkinnedMeshRenderer:GetAnimationName(index) end
+function SkinnedMeshRenderer:GetAnimationName(index, layer) end
 
---- Sets the active animation clip by index or name, returns true on success
----@overload fun(self: SkinnedMeshRenderer, index: integer|nil): boolean
----@overload fun(self: SkinnedMeshRenderer, name: string): boolean
+--- Sets the active animation clip of a layer by index or name, returns true on success
+---@overload fun(self: SkinnedMeshRenderer, name: string, layer?: integer): boolean
+---@overload fun(self: SkinnedMeshRenderer, index: integer|nil, layer?: integer): boolean
 ---@return boolean
 function SkinnedMeshRenderer:SetAnimation(...) end
 
---- Returns current clip index or nil
+--- Returns the current clip index of a layer, or nil
+---@param layer? integer
 ---@return integer|nil
-function SkinnedMeshRenderer:GetActiveAnimationIndex() end
+function SkinnedMeshRenderer:GetActiveAnimationIndex(layer) end
 
---- Returns current clip name or nil
+--- Returns the current clip name of a layer, or nil
+---@param layer? integer
 ---@return string|nil
-function SkinnedMeshRenderer:GetActiveAnimationName() end
+function SkinnedMeshRenderer:GetActiveAnimationName(layer) end
 
 --- Returns the number of available bones
 ---@return integer