Rive Android

Rive's core logic resides in C++. While many objects are automatically garbage collected, certain key classes require manual memory management to prevent leaks.

Objects that require manual deletion:

• File
• Artboard
• LinearAnimationInstance
• StateMachineInstance

If you are managing these objects manually (e.g., outside of RiveAnimationView), you must ensure they are properly released to avoid memory leaks.

When building from source, you can use specific flags to customize the output AAR:

Filter ABIs

By default, the build produces four ABIs: armeabi-v7a, arm64-v8a, x86, and x86_64. To reduce size, you can filter for specific architectures using -PabiFilters.

Exclude Audio Engine

To minimize binary size by approximately 600kb, you can exclude the miniaudio engine (used for Rive file audio assets) using the -PnoAudio flag.

# Build for a single architecture
./gradlew :kotlin:assembleRelease -PabiFilters=arm64-v8a

# Build for multiple architectures (comma-separated)
./gradlew :kotlin:assembleRelease -PabiFilters="arm64-v8a,armeabi-v7a"

# Build without the audio engine
./gradlew :kotlin:assembleRelease -PnoAudio

The app/ folder contains an example application demonstrating various Rive features (State Machines, Layout, Events, etc.).

To run the example:

1. In Android Studio, go to Build > Select Build Variant.
2. Select the preview build variant. This variant uses the hosted Rive dependency from Maven.

Note: If you are contributing to the library, use the debug build variant instead, which requires additional local setup.

The build system uses Gradle, CMake, and Premake. To generate an Android Archive (AAR) file equivalent to the one published on Maven, use the Gradle CLI.

Output location: kotlin/build/outputs/aar/kotlin-release.aar

./gradlew :kotlin:assembleRelease

If you are not using RiveAnimationView and need to implement a custom render loop, you must manage the lifecycle of File objects manually.

To ensure proper cleanup, add the File to the Renderer's dependencies. This ensures that the File (and its dependents) will be cleaned up at the appropriate time, such as within your own onDetachedFromWindow() implementation.

The RiveAnimationView is the recommended way to use Rive in Android because it abstracts memory management. It automatically allocates and de-allocates Native objects using Android's lifecycle hooks (onAttachedToWindow() and onDetachedFromWindow()).

Key behaviors:

• When the View is detached from the window, it automatically deletes the corresponding Rive File object and all derived objects (like Artboard or StateMachineInstance).
• Warning: Do not use Native Rive objects outside the lifecycle of the View that created them. Accessing objects after RiveAnimationView.onDetachedFromWindow() will result in a RiveException because the underlying C++ objects have been deleted.

If you encounter a RiveException when accessing C++ properties, it indicates the object is stale and must be replaced.

The RiveFileController is the primary interface for managing a Rive file's lifecycle, including its artboards, animations, and state machines. It handles playback control, input queuing, and layout configuration (fit and alignment).

Key responsibilities:

• File & Artboard Management: Loading a File and selecting an Artboard.
• Playback Control: Playing, pausing, and stopping specific animations or state machines.
• State Interaction: Triggering state machine inputs (Booleans, Numbers, Triggers) and updating text runs.
• Layout: Configuring how the artboard fits within its container using Fit and Alignment.

// Basic initialization (constructor usage)
val controller = RiveFileController(
    loop = Loop.LOOP,
    autoplay = true,
    file = myRiveFile,
    activeArtboard = myArtboard
)

RenderSurfaceVulkan is a polymorphic surface that can operate in one of two exclusive modes, managed via a std::variant:

1. Window Backend (VulkanWindowSurface): Used for rendering to an Android ANativeWindow. It manages a VkSurfaceKHR and a VulkanSwapchain. It can transition between a VulkanPendingWindowSurface state (lazy swapchain creation) and a VulkanPreparedWindowSurface state.
2. Image Backend (VulkanImageSurface): Used for off-screen rendering. It manages either a VulkanPendingImageSurface (fixed-size creation data) or a VulkanPreparedImageSurface (containing a VulkanHeadlessFrameSynchronizer).

The RenderSurface class acts as a backend-specific wrapper that manages a lazy Rive render target. In the Android integration, Kotlin stores concrete subclasses of RenderSurface as opaque surface pointers.

Key behaviors:

• Lazy Initialization: The concrete render target is not created immediately upon instantiation; instead, it is created on the first draw through an active RenderContext via getOrCreateRenderTarget.
• Lifecycle: The render target is dropped and recreated whenever a resize occurs.
• Threading: The resize method must be called on the command server thread.