Back to Details

roblox-animation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

roblox-animation

roblox-animation

Choose animation tracks for authored rig motion, TweenService for property changes, and IKControl for procedural poses. Validate gameplay outcomes on the server even when a client animation triggers the visual effect.
Key official sources:
Cross-skill usage:
  • Combine with roblox-user-interfaces for UI motion details and "particles in UI".
  • Combine with roblox-vfx when animations should trigger emitters, beams, or trails via markers.
  • Combine with roblox-core for Animator acquisition, RunService timing, and preloading via ContentProvider.
  • Use roblox-networking to decide where to play/ control animations (server replication vs client-only cosmetics).
为已编排的 rig 动作选择 animation tracks，使用 TweenService 完成属性变化，并使用 IKControl 创建程序化姿势。即使客户端动画触发视觉特效，也应在服务器端验证游戏玩法结果。
关键官方来源：
跨 skill 用法：
  • 与 roblox-user-interfaces 结合使用，以了解 UI 动作详情和“particles in UI”。
  • 当动画需要通过 markers 触发 emitters、beams 或 trails 时，与 roblox-vfx 结合使用。
  • 与 roblox-core 结合使用，以获取 Animator、使用 RunService 计时以及通过 ContentProvider 预加载。
  • 使用 roblox-networking 决定应在哪里播放或控制动画（服务器复制与仅客户端的装饰效果）。

Choose a motion system

选择动作系统

3D rig/character motion that needs to look authored and blendable?
→ Animation system (Animator + AnimationTrack). Pre-authored in Editor or from catalog, played with priority/weight/fade/speed. Drive gameplay from markers.
Simple property changes, UI transitions, or one-off object motion?
→ TweenService. Use for GuiObjects (scale + AnchorPoint + UDim2), CFrame, Color3, Transparency, NumberSequence, etc.
Need procedural interaction with environment (hand reaching, head tracking, foot placement on uneven ground)?
→ IKControl (procedural) + optional AnimationTracks or constraints for limits. Often combined with animation events.
Combining systems: Play a locomotion track on low priority while using IKControl or tweens for upper-body or UI overlays. Use markers in the track to start/stop IK or fire tweens/effects.
See references/3d-animations.md and references/ui-tweens-and-sequences.md for details.
需要呈现自然编排效果并支持混合的 3D rig/character motion？
→ 动画系统（Animator + AnimationTrack）。在 Editor 中预制或从 catalog 获取，并通过 priority/weight/fade/speed 播放。通过 markers 驱动 gameplay。
简单的属性变化、UI 转场或一次性对象运动？
→ TweenService。适用于 GuiObjects（scale + AnchorPoint + UDim2）、CFrame、Color3、Transparency、NumberSequence 等。
需要与环境进行程序化交互（伸手、头部追踪、在不平坦地面上放置双脚）？
→ IKControl（程序化）+ 可选的 AnimationTracks 或 constraints（用于限制）。通常与 animation events 结合使用。
组合系统： 以 low priority 播放 locomotion track，同时使用 IKControl 或 tweens 处理上半身动作或 UI overlay。通过 track 中的 markers 启动或停止 IK，或触发 tweens/effects。
有关详细信息，请参阅 references/3d-animations.md 和 references/ui-tweens-and-sequences.md。

Rig animations and IK

Rig 动画与 IK

Read 3d-animations.md when authoring, loading, or blending rig animations, or configuring IK.
  • Load tracks through 
    Animator
    . Choose priority, weight, fade time, and speed for the action.
  • Use named markers for footsteps, effects, and other timed events. Keep names stable when republishing assets.
  • Decide where playback runs and check asset ownership. Validate gameplay effects on the server.
  • Preload Animation assets and reuse loaded tracks. Stop tracks and disconnect their signals when the rig is removed.
  • For IK, define the chain root, end effector, and target. Tune responsiveness and joint limits in Play mode.
在编排、加载或混合 rig animations 以及配置 IK 时，请阅读 3d-animations.md。
  • 通过 
    Animator
    加载 tracks。为动作选择 priority、weight、fade time 和 speed。
  • 使用命名 markers 表示脚步声、特效和其他 timed events。重新发布 assets 时保持名称稳定。
  • 决定 playback 的运行位置并检查 asset ownership。在服务器端验证 gameplay effects。
  • 预加载 Animation assets 并复用已加载的 tracks。当 rig 被移除时，停止 tracks 并断开其 signals。
  • 对于 IK，定义 chain root、end effector 和 target。在 Play mode 中调节响应性和 joint limits。

UI animation with TweenService

使用 TweenService 实现 UI 动画

Read ui-tweens-and-sequences.md for property examples, easing, chained transitions, and typewriter text.
Use scale and AnchorPoint for responsive motion, and add an aspect-ratio constraint when the design requires fixed proportions. Use CanvasGroup for whole-panel fades. Cancel conflicting tweens and disconnect completion handlers when a sequence ends or its GUI is destroyed.
For text reveal, use 
TextLabel.MaxVisibleGraphemes
and account for localization and Unicode character boundaries.
在配置 property examples、easing、chained transitions 和 typewriter text 时，请阅读 ui-tweens-and-sequences.md。
使用 scale 和 AnchorPoint 实现响应式动作；当设计需要固定比例时，添加 aspect-ratio constraint。使用 CanvasGroup 实现整个 panel 的淡入淡出。序列结束或 GUI 被销毁时，取消冲突的 tweens，并断开 completion handlers。
对于文本显现，使用 
TextLabel.MaxVisibleGraphemes
，并考虑本地化和 Unicode 字符边界。

Combine motion with other systems

将动作与其他系统结合

  • Animation markers → everything else: Footstep marker → play sound + emit particle at foot Attachment. Attack marker → enable hitbox or IK reach + spawn muzzle flash. "AbilityStart" marker → start a Tween on a UI cooldown ring or BillboardGui.
  • Priorities + weight for layering: Idle (low) + Walk (medium) + Action (high, weight 1.0 with fade). Use AdjustWeight and AdjustSpeed at runtime.
  • Client vs Server playback: For a player's own character, animations played on the client replicate to the server via the Animator (subject to ownership/permissions); for NPCs and other characters, the server is the authority. Cosmetic or prediction-friendly animations can be client-only. Gameplay-affecting timing (damage windows, movement locks) should be validated server-side; do not treat client markers as authoritative proof of a hit.
  • Preload + cache tracks: Load once per rig type, reuse the AnimationTrack objects. Use 
    AnimationClipProvider
    for async animation loading when you need previews or streaming behavior.
  • UI + 3D harmony: Tween a 3D part or Attachment while a BillboardGui or SurfaceGui on it also tweens (or uses ViewportFrame for embedded 3D previews with parts/meshes/cameras; note that ParticleEmitters/Beams/Trails/Lights do not render inside ViewportFrame).
  • Testing: Different devices have different frame rates and input latency. Test easing feels on mobile + desktop. Use MicroProfiler for heavy simultaneous tweens.
  • Animation markers → 其他所有系统：Footstep marker → 播放 sound + 在 foot Attachment 处 emit particle。Attack marker → 启用 hitbox 或 IK reach + 生成 muzzle flash。“AbilityStart” marker → 在 UI cooldown ring 或 BillboardGui 上启动 Tween。
  • 使用 Priorities + weight 实现分层：Idle（low）+ Walk（medium）+ Action（high，weight 1.0，带 fade）。运行时使用 AdjustWeight 和 AdjustSpeed。
  • 客户端与服务器端播放：对于玩家自己的角色，客户端播放的 animations 会通过 Animator 复制到服务器端（受 ownership/permissions 限制）；对于 NPC 和其他角色，服务器端是权威端。Cosmetic 或适合 prediction 的 animations 可以仅在客户端运行。影响 gameplay 的 timing（damage windows、movement locks）应在服务器端验证；不要将客户端 markers 当作命中成功的权威证据。
  • 预加载 + 缓存 tracks：每种 rig type 加载一次，复用 AnimationTrack objects。需要 previews 或 streaming behavior 时，使用 AnimationClipProvider 进行异步 animation loading。
  • UI + 3D 协调：对 3D part 或 Attachment 执行 tween，同时让附着其上的 BillboardGui 或 SurfaceGui 也执行 tween（或者使用 ViewportFrame 嵌入 3D previews，并配置 parts/meshes/cameras；注意 ParticleEmitters/Beams/Trails/Lights 不会在 ViewportFrame 内渲染）。
  • 测试：不同设备具有不同 frame rates 和 input latency。在 mobile + desktop 上测试 easing 手感。大量 tweens 同时运行时，使用 MicroProfiler。

Common mistakes

常见错误

  • Humanoid:LoadAnimation(anim)
    (deprecated; use Animator).
  • Polling 
    track.TimePosition
    every frame instead of markers.
  • Tweening raw pixel offsets instead of scale + AnchorPoint (breaks on resolution/aspect changes).
  • Playing high-priority actions without fade time (jarring).
  • Never preloading (first play hitch).
  • Using the same low AnimationPriority for everything (idles fighting actions).
  • Ignoring IK constraints (elbows/knees bending backwards, wrists at impossible angles).
  • Tweening dozens of individual UI elements instead of using CanvasGroup or layouts.
  • Humanoid:LoadAnimation(anim)
    （已弃用；请使用 Animator）。
  • 每帧轮询 
    track.TimePosition
    ，而不是使用 markers。
  • 对原始像素偏移执行 tween，而不是使用 scale + AnchorPoint（会在分辨率或宽高比变化时失效）。
  • 播放 high-priority actions 时未设置 fade time（会造成突兀）。
  • 从不预加载（首次播放会卡顿）。
  • 所有内容都使用相同的 low AnimationPriority（idle 与 actions 会互相争抢）。
  • 忽略 IK constraints（elbows/knees 向后弯曲，wrists 出现不可能的角度）。
  • 对数十个 individual UI elements 分别执行 tween，而不是使用 CanvasGroup 或 layouts。

Examples and verification

示例与验证

Adapt AnimationLoader.lua, TweenHelper.lua, or IKSetup.lua when the helper fits the task.
For a changed animation, verify that it plays at the intended priority, fires its markers, and cleans up when the rig is removed. For UI motion, check the target screen sizes and cancellation path. Use integration-and-events.md when motion drives another system.
<!-- catalog:references:start -->
如果这些 helper 符合任务需求，可适配 AnimationLoader.lua、TweenHelper.lua 或 IKSetup.lua。
对于发生更改的 animation，验证其以预期 priority 播放、触发 markers，并在 rig 被移除时完成清理。对于 UI motion，检查目标 screen sizes 和 cancellation path。当 motion 驱动另一个系统时，使用 integration-and-events.md。
<!-- catalog:references:start -->

Reference index

Reference index

  • 3d-animations.md: Author or load rig animations, blend tracks, or configure IK.
  • integration-and-events.md: Synchronize animation markers with gameplay, effects, audio, or UI.
  • ui-tweens-and-sequences.md: Tween UI properties, chain transitions, or reveal text.
<!-- catalog:references:end -->
  • 3d-animations.md：编排或加载 rig animations、混合 tracks，或配置 IK。
  • integration-and-events.md：同步 animation markers 与 gameplay、effects、audio 或 UI。
  • ui-tweens-and-sequences.md：对 UI properties 执行 tween、链式 transitions，或显现文本。
<!-- catalog:references:end -->