Base Animations - macOS

import Foundation
import IMGLYEngine

@MainActor
func usingAnimations(engine: Engine) async throws {
  let scene = try engine.scene.createVideo()

  let page = try engine.block.create(.page)
  try engine.block.setWidth(page, value: 800)
  try engine.block.setHeight(page, value: 600)
  try engine.block.appendChild(to: scene, child: page)

  try await engine.scene.zoom(to: page, paddingLeft: 40, paddingTop: 40, paddingRight: 40, paddingBottom: 40)

  let block = try engine.block.create(.graphic)
  try engine.block.setShape(block, shape: engine.block.createShape(.rect))
  try engine.block.setPositionX(block, value: 100)
  try engine.block.setPositionY(block, value: 50)
  try engine.block.setWidth(block, value: 300)
  try engine.block.setHeight(block, value: 300)
  try engine.block.appendChild(to: page, child: block)
  let fill = try engine.block.createFill(.image)
  try engine.block.setString(
    fill,
    property: "fill/image/imageFileURI",
    value: "https://img.ly/static/ubq_samples/sample_1.jpg",
  )
  try engine.block.setFill(block, fill: fill)

  guard try engine.block.supportsAnimation(block) else {
    return
  }

  let slideInAnimation = try engine.block.createAnimation(.slide)
  let breathingLoopAnimation = try engine.block.createAnimation(.breathingLoop)
  let fadeOutAnimation = try engine.block.createAnimation(.fade)
  try engine.block.setInAnimation(block, animation: slideInAnimation)
  try engine.block.setLoopAnimation(block, animation: breathingLoopAnimation)
  try engine.block.setOutAnimation(block, animation: fadeOutAnimation)
  let animation = try engine.block.getLoopAnimation(block)
  let animationType = try engine.block.getType(animation)

  let squeezeLoopAnimation = try engine.block.createAnimation(.squeezeLoop)
  try engine.block.destroy(engine.block.getLoopAnimation(block))
  try engine.block.setLoopAnimation(block, animation: squeezeLoopAnimation)
  // The following line would also destroy all currently attached animations
  // try engine.block.destroy(block)

  let allAnimationProperties = try engine.block.findAllProperties(slideInAnimation)
  try engine.block.setFloat(slideInAnimation, property: "animation/slide/direction", value: 0.5 * .pi)
  try engine.block.setDuration(slideInAnimation, duration: 0.6)
  try engine.block.setEnum(slideInAnimation, property: "animationEasing", value: "EaseOut")
  let easingOptions = try engine.block.getEnumValues(ofProperty: "animationEasing")
}

Add motion to design blocks with entrance, exit, and loop animations using CE.SDK’s animation system.

5 mins

estimated time

GitHub

Base animations in CE.SDK add motion to design blocks through entrance (In), exit (Out), and loop animations. Animations are created as separate objects and attached to blocks, enabling reusable configurations across multiple elements.

This guide covers creating animations, attaching them to blocks, configuring properties like duration and easing, and managing animation lifecycle.

Animation Fundamentals#

Before applying animations to a block, verify it supports them using supportsAnimation. Once confirmed, create an animation instance and attach it to the block.

guard try engine.block.supportsAnimation(block) else {
  return
}

We use createAnimation with an AnimationType like .slide, .fade, or .zoom. The animation is then attached using setInAnimation for entrance animations. Duration is set with setDuration in seconds.

For a full catalog of available animation types and their properties, see Supported Animation Types.

Entrance Animations#

Entrance animations (In animations) define how a block appears on screen. Create the animation, attach it with setInAnimation, and configure its properties.

let slideInAnimation = try engine.block.createAnimation(.slide)
let breathingLoopAnimation = try engine.block.createAnimation(.breathingLoop)
let fadeOutAnimation = try engine.block.createAnimation(.fade)

try engine.block.setInAnimation(block, animation: slideInAnimation)

Exit Animations#

Exit animations (Out animations) define how a block leaves the screen. Use setOutAnimation to attach them.

try engine.block.setOutAnimation(block, animation: fadeOutAnimation)

When using both entrance and exit animations, CE.SDK automatically manages their timing to prevent overlap. Changing the duration of an In animation may adjust the Out animation’s duration to maintain valid timing.

Loop Animations#

Loop animations run continuously while the block is visible. Use setLoopAnimation to attach them.

try engine.block.setLoopAnimation(block, animation: breathingLoopAnimation)

The duration for loop animations defines the length of each cycle. A 2-second breathing loop completes one full pulse every 2 seconds.

Animation Properties#

Each animation type has specific configurable properties. Use findAllProperties to discover available properties for an animation.

let allAnimationProperties = try engine.block.findAllProperties(slideInAnimation)

For slide animations, the animation/slide/direction property controls the entry direction in radians:

0 — From the right
Float.pi / 2 — From the bottom
Float.pi — From the left
3 * Float.pi / 2 — From the top

try engine.block.setFloat(slideInAnimation, property: "animation/slide/direction", value: 0.5 * .pi)

Managing Animation Lifecycle#

Animation objects must be properly managed to avoid memory leaks. When replacing an animation, destroy the old one before setting the new one. Retrieve current animations using getInAnimation, getOutAnimation, and getLoopAnimation.

let animation = try engine.block.getLoopAnimation(block)
let animationType = try engine.block.getType(animation)

let squeezeLoopAnimation = try engine.block.createAnimation(.squeezeLoop)
try engine.block.destroy(engine.block.getLoopAnimation(block))
try engine.block.setLoopAnimation(block, animation: squeezeLoopAnimation)
// The following line would also destroy all currently attached animations
// try engine.block.destroy(block)

Destroying a design block also destroys all its attached animations, but detached animations must be destroyed manually.

Easing Functions#

We can query available easing options using getEnumValues(ofProperty:).

try engine.block.setEnum(slideInAnimation, property: "animationEasing", value: "EaseOut")
let easingOptions = try engine.block.getEnumValues(ofProperty: "animationEasing")

Easing functions control animation acceleration:

Easing	Description
`Linear`	Constant speed throughout
`EaseIn`	Starts slow, accelerates toward the end
`EaseOut`	Starts fast, decelerates toward the end
`EaseInOut`	Starts slow, speeds up, then slows down again

Duration#

All animations have a configurable duration. For In and Out animations, it defines the total animation length. For Loop animations, it defines each cycle’s length.

try engine.block.setDuration(slideInAnimation, duration: 0.6)

API Reference#

Method	Description
`engine.block.createAnimation(type)`	Create a new animation instance
`engine.block.supportsAnimation(block)`	Check if block supports animations
`engine.block.setInAnimation(block, animation:)`	Apply entrance animation to block
`engine.block.setOutAnimation(block, animation:)`	Apply exit animation to block
`engine.block.setLoopAnimation(block, animation:)`	Apply loop animation to block
`engine.block.getInAnimation(block)`	Get entrance animation ID
`engine.block.getOutAnimation(block)`	Get exit animation ID
`engine.block.getLoopAnimation(block)`	Get loop animation ID
`engine.block.setDuration(anim, duration:)`	Set animation duration in seconds
`engine.block.setEnum(anim, property:, value:)`	Set enum property (easing, etc.)
`engine.block.setFloat(anim, property:, value:)`	Set float property (direction, etc.)
`engine.block.findAllProperties(anim)`	Get all configurable properties
`engine.block.getEnumValues(ofProperty:)`	Get available values for enum property
`engine.block.destroy(anim)`	Destroy animation instance

Next Steps#

Text Animations — Animate text with writing styles and character-level control
Animation Overview — Understand animation concepts and capabilities
Edit Animations — Modify existing animations on blocks