Out of band assets #285

HayesGordon · 2025-01-09T14:29:27Z

This PR adds out of band asset support to Rive React Native.

Please take a look at the video below for an overview of the implementation and an exploration of the provided example.
Feedback is appreciated while this is a work in progress

rev file used in the video:
out_of_band.rev.zip

Video:
https://drive.google.com/file/d/1jDZY2MRLhLfV8EOpRz3rVcCRbTdkv6sI/view?usp=sharing

Edit:

Added android

HayesGordon · 2025-01-10T16:18:14Z

android/src/main/java/com/rivereactnative/RiveReactNativeView.kt

+
+    val source = assetData?.getMap("source") ?: return false // Do not handle the asset.
+
+    CoroutineScope(Dispatchers.IO).launch {


@ErikUggeldahl, your input here would be great on the best way to implement coroutine scope management (canceling it if the view is destroyed).

HayesGordon · 2025-01-10T16:20:33Z

android/src/main/java/com/rivereactnative/RiveReactNativeView.kt

+
+    // Handle release mode (URL instead of asset id)
+    // Resource needs to be loaded in release mode
+    // https://github.com/facebook/react-native/issues/24963#issuecomment-532168307


@lancesnider would be great if we can give extra testing on this. It's handled differently between a dev and release build.

HayesGordon · 2025-01-10T16:22:13Z

src/Rive.tsx

@@ -104,6 +108,10 @@ type Props = {
  testID?: string;
  alignment?: Alignment;
  artboardName?: string;
+  /**
+   * @experimental This is an experimental feature and may change without a major version update (breaking change).


Opinions on marking this as experimental?

I think it's probably a good idea, especially since we're likely to have a major overhaul of the runtime relatively soon.

lancesnider

This is looking great!

I really like the assetsHandled object. I think it'll be easier for users to grasp than assetLoader which requires some extra steps. If I'm understanding correctly the downside is that you can only define a referenced asset at load time, but not at runtime. I'm assuming that has to do with the limitation you mentioned in the video where we can't have a callback?

I love that you don't need to add assets to Bundled Assets in iOS, but I'm not sure I understand why.

lancesnider · 2025-01-10T19:43:57Z

example/src/OutOfBandAssets.tsx

+              //   path: 'fonts', // only needed for Android assets
+              // },
+            },
+            'referenced-image-2929282': {


Though I'd prefer not to need the ID, I think using it by default is probably necessary, given the fact that it's possible to have multiple assets with the same name. I could see users being very confused when both fonts named Tomorrow display the same even though one of them is actually supposed to be a different weight.

I really like the idea of being able to override the default behavior with includeId. Do you have thoughts on that being a global attribute, rather than on a per-asset basis?

lancesnider · 2025-01-10T19:48:52Z

example/src/OutOfBandAssets.tsx

+          //
+          // The key of the map is the unique asset identifier (as exported in the Editor),
+          // which is a combination of the asset name and its unique identifier.
+          assetsHandled={{


What's your thinking on the name assetsHandled? My first thought would be to call this referencedAssets to align it with the naming in the editor, but maybe that's too restricting.

I've also been toying with thinking of a different name for this.

lancesnider · 2025-01-10T19:55:55Z

src/Rive.tsx

@@ -104,6 +108,10 @@ type Props = {
  testID?: string;
  alignment?: Alignment;
  artboardName?: string;
+  /**
+   * @experimental This is an experimental feature and may change without a major version update (breaking change).


I think it's probably a good idea, especially since we're likely to have a major overhaul of the runtime relatively soon.

lancesnider · 2025-01-10T20:15:43Z

src/types.ts

+  sourceAsset?: string;
+  sourceAssetId?: string;
+  path?: string;
+}


Is it worth being explicit that exactly one of sourceUrl, sourceAsset and path is required?

type FileAssetSource = | { sourceUrl: string sourceAsset?: never path?: never sourceAssetId: string } | { sourceAsset: string sourceUrl?: never path?: never sourceAssetId: string } | { path: string sourceUrl?: never sourceAsset?: never sourceAssetId: string } ```

lancesnider · 2025-01-10T20:26:10Z

example/src/OutOfBandAssets.tsx

+              //   path: 'images', // only needed for Android assets
+              // },
+            },
+            'referenced_audio-2929340': {


There's no scenario where the asset IDs might change, is there? For example, if the Rive file gets copied or if you reimport a PSD? That could be painful if you have a giant object with ID's included.

Adds clarity and formatting.

Couple more quick formatting changes.

dan-phantom · 2025-01-13T11:44:59Z

Great work and thank you so much for doing this ❤️

I'm not sure what is the "ID" tbh, how would we obtain it so we know what to set the key to, but if it it depends on the riv animation file I see an issue where some assets (fonts probably more common) is shared between multiple animation files. (we actually have this case #271 (comment))

Thank you

dskuza

There may be some more RN-specific comments left, but generally from the Swift side of things, things look great! I left some comments about things we previously discussed during a live walkthrough.

dskuza · 2025-01-09T15:45:03Z

ios/RNRiveError.swift

@@ -64,6 +64,10 @@ func createMalformedFileError() -> NSError {
    return NSError(domain: RiveErrorDomain, code: RiveErrorCode.malformedFile.rawValue, userInfo: [NSLocalizedDescriptionKey: "Malformed Rive File", "name": "Malformed"])
 }

+func createAssetFileError(_ assetName: String) -> NSError {
+    return NSError(domain: RiveErrorDomain, code: RiveErrorCode.malformedFile.rawValue, userInfo: [NSLocalizedDescriptionKey: "Could not load Rive asset: \(assetName)", "name": "Malformed"])


Nitpicky, but I would maybe use .fileNotFound rather than malformed as the error code.

dskuza · 2025-01-13T15:36:30Z

example/src/OutOfBandAssets.tsx

+          //
+          // The key of the map is the unique asset identifier (as exported in the Editor),
+          // which is a combination of the asset name and its unique identifier.
+          assetsHandled={{


I've also been toying with thinking of a different name for this.

dskuza · 2025-01-13T15:40:33Z

ios/RiveReactNativeView.swift

+        }
+    }
+
+    private func processAssetBytes(_ data: Data, asset: RiveFileAsset, factory: RiveFactory) {


It might be worth having another check here to validate that data.isEmpty == false.

dskuza · 2025-01-13T15:41:24Z

ios/RiveReactNativeView.swift

+    }
+
+    private func splitFileNameAndExtension(fileName: String) -> (name: String?, ext: String?)? {
+        let components = fileName.split(separator: ".")


Do we have any documentation surrounding naming? This might not work as intended, for example, if a user has an asset name with a . in it.

dskuza · 2025-01-13T15:43:20Z

ios/RiveReactNativeView.swift

+        return (name: String(components[0]), ext: String(components[1]))
+    }
+
+    private func loadResourceAsset(sourceAsset: String, path: String?, listener: @escaping (Data) -> Void) {


Discussed live, but path is currently ignored. This is understandable as a first-pass, with the expectation being that the file is already in the bundle's Resources directory. There may be a time where we wish to expand this API to support further paths.

tslater · 2025-01-15T16:19:11Z

Love the ability to load assets different ways. As mentioned by others, we still really need the ability to replace an asset at run time. For our use case, we have an image that represents a topic. The user can shuffle this topic, so the current image gets replaced with another image. These images are dynamic (UGC). So we only know them at run time. In our case we'd want have two referenced images that we toggle between, allowing a the theoretically infinite number or images to be displayed as there is no hard limit to the number of shuffles.

If that was too long to follow: we have a need for the API to also allow us to replace an image after the animation loads any number of times, like the JS web rumtime supports (though I do think this API is simpler/cleaner so if there's a way to combine the ideas that would be awesome).

HayesGordon added 5 commits January 9, 2025 15:55

docs: improve instructions

5f78cfc

feat: add out of band assets

b93e18c

feat: add out of band assets ios

38809f8

chore: add out of band asset example

ae0dcc2

chore: cleanup oob example

5499e4f

HayesGordon requested review from dskuza, ErikUggeldahl and lancesnider January 9, 2025 14:29

HayesGordon mentioned this pull request Jan 9, 2025

OOB Asset Support #278

Closed

HayesGordon added 3 commits January 10, 2025 10:16

docs: formatting

a622e39

feat: out of band assets android

385d8da

chore: android example out of band assets

d90b1ad

HayesGordon commented Jan 10, 2025

View reviewed changes

chore: fix comment

de4e684

HayesGordon commented Jan 10, 2025

View reviewed changes

This was referenced Jan 10, 2025

Asset Handler API Compatibility with React Native #236

Open

assetLoader for RN ? #271

Open

chore: remove logs and empty lines

cc84f03

lancesnider reviewed Jan 10, 2025

View reviewed changes

ErikUggeldahl added 2 commits January 10, 2025 18:49

Update CONTRIBUTING.md

5772ea2

Adds clarity and formatting.

Further updating CONTRIBUTING.md

68bd17e

Couple more quick formatting changes.

dskuza approved these changes Jan 13, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Out of band assets #285

Out of band assets #285

HayesGordon commented Jan 9, 2025 •

edited

Loading

HayesGordon Jan 10, 2025

HayesGordon Jan 10, 2025

HayesGordon Jan 10, 2025

lancesnider Jan 10, 2025

lancesnider left a comment

lancesnider Jan 10, 2025

lancesnider Jan 10, 2025

dskuza Jan 13, 2025

lancesnider Jan 10, 2025

lancesnider Jan 10, 2025

lancesnider Jan 10, 2025

dan-phantom commented Jan 13, 2025

dskuza left a comment

dskuza Jan 9, 2025

dskuza Jan 13, 2025

dskuza Jan 13, 2025

dskuza Jan 13, 2025

dskuza Jan 13, 2025

tslater commented Jan 15, 2025


		val source = assetData?.getMap("source") ?: return false // Do not handle the asset.

		CoroutineScope(Dispatchers.IO).launch {

Out of band assets #285

Are you sure you want to change the base?

Out of band assets #285

Conversation

HayesGordon commented Jan 9, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lancesnider left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dan-phantom commented Jan 13, 2025

dskuza left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tslater commented Jan 15, 2025

HayesGordon commented Jan 9, 2025 •

edited

Loading