Search Docs
Loading...
Skip to content

Programmatic Animations

Create, assign, inspect, and replace CE.SDK animations from Android code by using CreativeEngine block APIs.

7 mins
estimated time
GitHub

Programmatic animation control is useful for automation, templates, and custom mobile controls. Animations belong to video scenes and attach to design blocks through separate In, Loop, and Out slots.

Check Animation Support#

Check a target block before you create and attach animation objects. Not every block type supports animation, so the sample fails early when the selected block is not animatable.

check(engine.block.supportsAnimation(block)) {
    "This block does not support animations."
}

Create Typed Animations#

Create animation objects with Android’s typed AnimationType values instead of raw animation type strings. In and Out slots can use block animation types such as Slide, Pan, Fade, Blur, Grow, Zoom, Pop, Wipe, Baseline, CropZoom, Spin, and KenBurns; Loop slots use loop types such as SpinLoop, FadeLoop, BlurLoop, PulsatingLoop, BreathingLoop, JumpLoop, SqueezeLoop, SwayLoop, and ScaleLoop. See the Base Animations catalog for the full list of supported block animation types.

val slideInAnimation = engine.block.createAnimation(AnimationType.Slide)
val breathingLoopAnimation = engine.block.createAnimation(AnimationType.BreathingLoop)
val fadeOutAnimation = engine.block.createAnimation(AnimationType.Fade)

Attach Animations to Slots#

Each design block has one In animation slot, one Loop animation slot, and one Out animation slot. Assign the animation object to the matching slot with setInAnimation, setLoopAnimation, or setOutAnimation.

engine.block.setInAnimation(block = block, animation = slideInAnimation)
engine.block.setLoopAnimation(block = block, animation = breathingLoopAnimation)
engine.block.setOutAnimation(block = block, animation = fadeOutAnimation)

Setting a different animation for the same slot replaces that slot’s association. Keep the previous animation handle if you plan to destroy or reuse it later.

Configure Timing and Properties#

Use setDuration for animation timing, setEnum for easing values, and type-specific property keys for properties such as slide direction. The sample also asks the engine which properties and easing values are available before relying on them.

val slideProperties = engine.block.findAllProperties(slideInAnimation)
val easingValues = engine.block.getEnumValues("animationEasing")


check(slideProperties.contains("animation/slide/direction")) {
    "Slide animations do not expose animation/slide/direction."
}
check(easingValues.contains(AnimationEasingType.EASE_OUT.key)) {
    "The animationEasing enum does not expose ${AnimationEasingType.EASE_OUT.key}."
}


engine.block.setDuration(block = slideInAnimation, duration = 0.6)
engine.block.setEnum(
    block = slideInAnimation,
    property = "animationEasing",
    value = AnimationEasingType.EASE_OUT.key,
)
// No type-safe Android helper exists for this animation-specific property yet.
engine.block.setFloat(
    block = slideInAnimation,
    property = "animation/slide/direction",
    value = 0.5F * Math.PI.toFloat(),
)

The slide direction is stored in radians. In this example, 0.5F * Math.PI.toFloat() makes the block slide along the vertical direction.

Read and Replace Animations#

Read the current slot handles when you need to inspect or replace animations. The returned handle can be passed to other block APIs, including getType and isValid.

val currentInAnimation = engine.block.getInAnimation(block)
val currentLoopAnimation = engine.block.getLoopAnimation(block)
val currentOutAnimation = engine.block.getOutAnimation(block)


check(engine.block.isValid(currentInAnimation))
val currentLoopType = engine.block.getType(currentLoopAnimation)

Destroy detached animation objects when you replace them and no longer need them. Destroying a design block also destroys its attached animations, but standalone animation objects should be cleaned up explicitly.

val previousLoopAnimation = engine.block.getLoopAnimation(block)
val squeezeLoopAnimation = engine.block.createAnimation(AnimationType.SqueezeLoop)


engine.block.destroy(previousLoopAnimation)
engine.block.setLoopAnimation(block = block, animation = squeezeLoopAnimation)

Configure Text Animation Properties#

Text animations use the same property APIs. The sample attaches AnimationType.Baseline to a text block; dedicated text animation presets also include TypewriterText, BlockSwipeText, SpreadText, and MergeText. textAnimationWritingStyle controls whether text animates as a block, by line, by word, or by character, and textAnimationOverlap controls the timing overlap between those segments.

val textAnimation = engine.block.createAnimation(AnimationType.Baseline)
engine.block.setInAnimation(block = textBlock, animation = textAnimation)
engine.block.setEnum(block = textAnimation, property = "textAnimationWritingStyle", value = "Word")
engine.block.setFloat(block = textAnimation, property = "textAnimationOverlap", value = 0.4F)

For detailed text animation behavior and type coverage, continue with Text Animations.

API Reference#

APIPurpose
engine.block.supportsAnimation(block=_)Check whether a block supports animation slots.
engine.block.createAnimation(type=_)Create an animation object from an AnimationType.
engine.block.setInAnimation(block=_, animation=_)Attach an entrance animation.
engine.block.setLoopAnimation(block=_, animation=_)Attach a looping animation.
engine.block.setOutAnimation(block=_, animation=_)Attach an exit animation.
engine.block.getInAnimation(block=_)Read the entrance animation handle.
engine.block.getLoopAnimation(block=_)Read the looping animation handle.
engine.block.getOutAnimation(block=_)Read the exit animation handle.
engine.block.isValid(block=_)Check that a returned animation handle is still valid.
engine.block.getType(block=_)Inspect an animation object’s concrete type.
engine.block.setDuration(block=_, duration=_)Set animation duration in seconds.
engine.block.setEnum(block=_, property=_, value=_)Set enum properties such as easing or text writing style.
engine.block.setFloat(block=_, property=_, value=_)Set numeric animation properties.
engine.block.findAllProperties(block=_)Discover properties supported by an animation object.
engine.block.getEnumValues(enumProperty=_)Discover enum values for a property.
engine.block.destroy(block=_)Destroy an animation object when replacing or removing it.

Next Steps#