TweenService — Syntax, Example & Use Case

Function syntax

TweenService:Create(object, tweenInfo, goals)

Short summary

A host-provided interpolation service for changing supported properties over time. It is an engine service, not a core Lua API.

Safe code example

-- All dependencies are supplied by the host integration.
local function fadePanel(TweenService, TweenInfo, panel)
    if not panel then return nil end
    local info = TweenInfo.new(0.25)
    local tween = TweenService:Create(panel, info, {
        BackgroundTransparency = 1
    })
    tween:Play()
    return tween -- Retain to cancel when the panel is removed.
end

Practical game development scenario

Animate an optional UI transition while keeping the underlying action immediate. Respect reduced-motion preferences in your UI design and cancel the previous animation before starting a competing transition.

Compatibility and safety notes

The host determines supported value types, easing configuration, cancellation, and completion events. Inject the service rather than assuming it exists in every Lua runtime.

These examples demonstrate defensive patterns. They are not sandboxing mechanisms or substitutes for permission checks, server-side validation, and resource limits.

Read the official Lua 5.4 reference manual for language semantics. Engine methods require separate host documentation.

← Back to the dictionary

Decide which transition owns a property

Two animations attempting to change the same property can produce confusing results even when each transition is valid by itself. Give the interface component ownership of its active transition and decide how a new request replaces the old one. A panel that starts opening and is immediately asked to close should have a documented outcome. Use the host's cancellation mechanism where appropriate and retain the relevant transition reference until cleanup. Do not assume the most recently created animation automatically represents the user's final intent in every engine. The integration should make that intent explicit and avoid leaving several callbacks competing to finalize the same visual state.

Keep essential behavior independent from motion

A transition can improve clarity, but the underlying action should remain understandable if motion is disabled, interrupted, or reduced. Apply the actual state change through a clear owner and treat the animation as presentation around that state. A confirmation should not depend on a decorative movement finishing before the application knows the action succeeded. For users who prefer reduced motion, provide an immediate or gentler path where your interface supports that preference. Test the feature with animation skipped entirely. If the application becomes inconsistent, inspect whether a visual completion callback accidentally owns logic that belongs in the state transition itself.

Review completion callbacks after cancellation

A callback associated with an earlier transition can become stale when a panel is reused, removed, or assigned a new target. Check whether the callback still belongs to the active request before applying final changes. The host determines how cancellation and completion are reported, so verify that contract rather than assuming every completion signal means the same thing. Try rapid open and close requests, a scene change during motion, and removal of the target. Observe both the visible result and the references that remain. These small tests help keep a polished interface from acquiring difficult timing bugs that only appear when users interact faster than the original development walkthrough.