Conversation
ErikUggeldahl
requested review from
Copilot,
lancesnider,
tylernij and
umberto-sonnino
ErikUggeldahl
added
documentation
There was a problem hiding this comment.
Pull request overview
Adds a new documentation page to guide developers migrating from the legacy View-based Rive Android runtime to the new Compose-based runtime, covering API equivalents and runtime-specific feature differences.
Changes:
- Added a comprehensive “Migrating from Legacy” Android runtime guide with side-by-side legacy vs new runtime examples.
- Updated Android docs navigation to include the new migration guide page.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| runtimes/android/migrating-from-legacy.mdx | New migration guide content, including API mappings and feature differences between runtimes. |
| docs.json | Adds the new migration guide page to the Android navigation group. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
tylernij
left a comment
tylernij
left a comment
There was a problem hiding this comment.
Looks fantastic, good job Erik!
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
lancesnider
left a comment
lancesnider
left a comment
There was a problem hiding this comment.
Very thorough and very clear. If the user wants to use it as a reference as to why and how a specific thing has changed, this is perfect. The before/after examples are a delight. :)
The intro
Calling this a migration guide is good because calling it a you-have-to-start-from-scratch-heres-why guide doesn't really roll off the tongue. :D Is that a fair assessment? If so, I might make that more clear in the very into. Something so they don't expect a step-by-step guide. Let them know that this is a reference.
The sidebar nav structure
I really like having section that contain Exclusive New and Exclusive Old features. It made me wish that there was also a top-level Things that are the same andThings that are different. I think that'd make the sidebar easier to browse. I also see the problem that it creates - we don't have 3-layer deep sidebar links. Is there a way to make the structure Things that are different/Setting a Local Raw Resource without it being too confusing?
Exclusive New Features section
I wonder if this one could be simplified to a bullet list of new features that link to the relevant docs. For example Logging on this page and here feel potentially redundant.
Some of the content, like Rendering to Bitmap doesn't exist on the new runtime page, but maybe it should?
Legacy features
Pure gold. I wish every migration doc was this clear about why something went away.
|
|
||
| ## Overview | ||
|
|
||
| The new Rive Android runtime is nearly a complete rewrite of both the public API and the internal architecture. Conceptually most operations have an equivalent, even if the API is new. |
There was a problem hiding this comment.
Can you add a link to the new getting started docs right here? If they're intimidated by the length of this doc, it'll be nice to give them a start-from-scratch escape hatch in the first paragraph.
|
I was wrong, we can have more deeply nested hierarchy in the right sidebar. 🎉 How's this, @ErikUggeldahl 
|
| ## Overview | ||
|
|
||
| The [new Rive Android runtime](/runtimes/android/android) is nearly a complete rewrite of both the public API and the internal architecture. Conceptually most operations have an equivalent, even if the API is new. | ||
| The [new Rive Android runtime](/runtimes/android/android) is a **near-complete rewrite** of both the public API and the internal architecture. While conceptually most operations have an equivalent, **you should expect to rebuild your integration rather than incrementally migrate it**. |
There was a problem hiding this comment.
you should expect to rebuild your integration rather than incrementally migrate it
I think we need to be careful with wording here. Users can incrementally migrate their app because both legacy and new APIs can co-exist in a singular app. It's just that they can't use the two APIs together on a singular feature area. I think that precision will be key so that we don't cause undue confusion.
Maybe:
While conceptually most operations have an equivalent, the two APIs are incompatible. Any existing work in the legacy API that you would like to migrate must be rebuilt using the new API. This guide aims to demonstrate how to migrate each feature area.
| 3. [Legacy Exclusive Features](#legacy-exclusive-features) - Features no longer supported in the new runtime. Most have workarounds or alternatives; these removals simplify the API surface, reduce maintenance overhead, and eliminate anti-patterns. | ||
|
|
||
| <Note> | ||
| This guide is not meant to be exhaustive as it would be redundant with existing general documentation. Please refer to the relevant sections of the documentation for more details on specific topics. |
There was a problem hiding this comment.
Nit: Indent within the <Note> block.
|
|
||
| ## Asynchronous APIs | ||
|
|
||
| ### Asynchronous APIs |
There was a problem hiding this comment.
If we're adding a new section header for shared features, I think it then makes sense to lift this section and the next (lifecycles) out of this category. They aren't shared features but rather meant to highlight new differences, which also don't fall under the category of a "new exclusive feature".
ErikUggeldahl
left a comment
ErikUggeldahl
left a comment
There was a problem hiding this comment.
Some things to address, but thanks for getting it going.
|
|
||
| Rendering to bitmap at runtime is useful for scenarios such as snapshot testing and rendering video encoded from data-bound files. | ||
|
|
||
| Currently only the Android runtime provides built-in support for rendering. |
There was a problem hiding this comment.
We may want to verify with @dskuza that iOS doesn't have some pretty convenient APIs for rendering to bitmap. I believe he has an example that demonstrate how.
There was a problem hiding this comment.
Also, we want to be precise with language. "built-in support for rendering" -> "built-in support for rendering for rendering to a bitmap".
| description: 'Render screenshots and video at runtime.' | ||
| --- | ||
|
|
||
| Rendering to bitmap at runtime is useful for scenarios such as snapshot testing and rendering video encoded from data-bound files. |
There was a problem hiding this comment.
Nit: "Rendering to a bitmap
| Currently only the Android runtime provides built-in support for rendering. | ||
|
|
||
| <Note> | ||
| For rendering to bit map from the Rive Editor, see [Exporting for Video or Static Design](/editor/exporting/exporting-for-video-and-static-design). |
There was a problem hiding this comment.
Fix: "bit map" -> "bitmap"
| <Tabs> | ||
| <Tab title="React"> | ||
| Rendering to bitmap is not supported directly in the React runtime. For offline or server-side rendering, you can use external tools like | ||
| [ReVideo](https://x.com/matternjustus/status/1816439475783815643?s=46&t=jqRQ1ggfUR6vYiNQ8wOU3A) and |
There was a problem hiding this comment.
May want to link directly to the project rather than to the tweet: https://github.com/redotvideo/examples/tree/main/rive-explanation-video
| <Callout icon="ban"> | ||
| Rendering to a Bitmap was technically possible in the legacy runtime by rendering to a Canvas backed by a Bitmap or by sub-classing the renderer, but it was not a built-in feature and required more effort to implement. There are no plans to retrofit this feature into the legacy runtime. | ||
| </Callout> |
There was a problem hiding this comment.
Rather than this being a call out, we should use the two sub-tabs for Compose and Legacy as we do elsewhere in the docs.
While we're changing this, the language can be transformed to be more present tense: "it is not a built-in feature", "requires more effort".
| <Callout icon="question"> | ||
| We may consider retrofitting this behavior into the legacy runtime in the future as it is a common source of confusion. However, doing so would be a breaking change, and it may not be worth the disruption for existing users. | ||
| </Callout> |
There was a problem hiding this comment.
Note that we're losing information here as this wasn't migrated. May be worth preserving.
There was a problem hiding this comment.
Good call. I was working too hard to simplify, but there's a lot here. I brought them back, but simplified logging a bit and added links.
| <Callout icon="ban"> | ||
| There are no plans to retrofit this feature into the legacy runtime. | ||
| </Callout> |
There was a problem hiding this comment.
Same note about losing information.
| <Callout icon="ban"> | ||
| There are no plans to retrofit this feature into the legacy runtime. | ||
| </Callout> | ||
| - [Logging](/runtimes/android/android#enabling-logging) - The new runtime includes a fine-grained, flexible logging system that allows you to capture logs at various levels (debug, info, warning, error) and redirect them to your preferred logging framework or sink. |
There was a problem hiding this comment.
This migration links to logging in the getting started, but ideally it links to the logging page, which hasn't yet been updated. I've got the work to add it in a commit which I haven't yet posted. I might as well merge it into this PR so that we can link to the correct spot right away.
ErikUggeldahl
left a comment
ErikUggeldahl
left a comment
There was a problem hiding this comment.
A few more to address.
| </Tab> | ||
| <Tab title="Android"> | ||
| <Tabs> | ||
| <Tab title="Compose (Recommended)"> |
There was a problem hiding this comment.
We can drop the "(Recommended)" to keep parity with other pages that have this sub-tab.
| Rendering to a bitmap is not supported directly in the React runtime. For offline or server-side rendering, you can use external tools like | ||
| [ReVideo](https://github.com/redotvideo/examples/tree/main/rive-explanation-video) and | ||
| [Remotion](https://www.remotion.dev/docs/rive/), both of which support Rive. |
There was a problem hiding this comment.
Nit: extra newlines can be collapsed.
| See the `RiveSnapshotActivity` example for a demonstration of this feature. | ||
| </Card> | ||
|
|
||
| Rendering to a bitmap is done using the `RenderBuffer` class or the `onBitmapAvailable` callback in the `Rive` Composable. |
There was a problem hiding this comment.
I guess we can leave this as a bit of a WIP, since ideally we explain more of the API here, but I can go back and add that later since it's not the focus of this PR.
| - [Logging](/runtimes/logging#android) - The new runtime includes a fine-grained, flexible logging system that allows you to capture logs at various levels (debug, info, warning, error) and redirect them to your preferred logging framework or sink. | ||
| - [Rendering to a Bitmap](/runtimes/advanced-topic/rendering-to-a-bitmap) - Useful for snapshot testing or rendering video encoded from data-bound Rive files. | ||
| - Updating a Data Bind Unsettles the State Machine - In the new runtime, updating a data-bound property automatically "unsettles" the state machine, causing it to advance and draw based on the new data. By comparison, the legacy runtime required you to call `RiveAnimationView.play()` after updating data-bound properties on a settled state machine to achieve the same effect. | ||
| - [Tracking the Loading State](/runtimes/android/android#adding-rive-to-your-composition) - The new runtime provides a `Result` wrapper around Rive file loading operations, allowing you to track the state (loading, success, error) of a Rive file. This is useful for providing user feedback during loading or handling errors gracefully. |
There was a problem hiding this comment.
Looks like we lost this section when migrating back to the old format.
| We may consider retrofitting more logging capabilities to the legacy runtime in the future, especially if doing so would illuminate a potential source for bugs. | ||
| </Callout> | ||
|
|
||
| ### Rendering to Bitmap |
There was a problem hiding this comment.
We could make this "Rendering to a Bitmap" now just to keep it consistent.
| </Card> | ||
|
|
||
| The legacy runtime includes a Canvas renderer that allows rendering Rive animations directly into an Android `Canvas`. This was useful as a fallback for scenarios where the Rive Renderer wasn't yet feature compatible. As we have improved the Rive Renderer, this use case has diminished. | ||
| The legacy runtime includes a Canvas renderer that allows rendering Rive animations directly into an Android `Canvas`. This is useful as a fallback for scenarios where the Rive Renderer isn't yet feature compatible. As we have improved the Rive Renderer, this use case has diminished. |
There was a problem hiding this comment.
I think this one makes sense to keep as past tense. We don't want to encourage it as a fallback anymore nor imply that the Rive Renderer isn't yet feature complete.
| <Tabs> | ||
| <Tab title="React"> | ||
| Rendering to a bitmap is not supported directly in the React runtime. For offline or server-side rendering, you can use external tools like | ||
| [ReVideo](https://github.com/redotvideo/examples/tree/main/rive-explanation-video) and |
There was a problem hiding this comment.
Minor: Looks like their official casing is lower v: Revideo
|
Good catches, thanks @ErikUggeldahl. Done. |
3 participants
Adds a migration guide for legacy to Compose ("new"). It's as exhaustive as I could come up with, but we may need to add sections as users ask questions in the future.