From 5fd2145a9d1ac62d48f294c48912dafc71ab46fb Mon Sep 17 00:00:00 2001 From: zplata Date: Tue, 2 Aug 2022 15:05:40 +0000 Subject: [PATCH] Docs: Update docs for the iOS runtime README and CONTRIBUTING md files to the simplified format Getting this format to match the other runtimes new README format. Diffs= 671b8172f Docs: Update docs for the iOS runtime README and CONTRIBUTING md files to the simplified format --- .rive_head | 2 +- CONTRIBUTING.md | 19 ++-- README.md | 278 +++++++----------------------------------------- 3 files changed, 48 insertions(+), 251 deletions(-) diff --git a/.rive_head b/.rive_head index dd1eebd6..be88d6c6 100644 --- a/.rive_head +++ b/.rive_head @@ -1 +1 @@ -f39fd75e1a07ec84f29c711f1dba934bef9a00e8 +671b8172f2e962543c60d8e9dfcc50224b00ca10 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94e3ea7e..0a668654 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,30 +4,33 @@ We want this community to be friendly and respectful to each other. Please follo ## Development workflow -To get started with the project, please install a few pre-requisites: `ninja` & [premake5](https://premake.github.io/)). Brew will install both git-lfs and ninja, for premake5 you will need to download the binary, and make sure its available on your path. Moving the executable to `/usr/local/bin/` will work. +To get started with the project, please install a few pre-requisites: [ninja](https://formulae.brew.sh/formula/ninja) & [premake5](https://premake.github.io/). [Homebrew](https://formulae.brew.sh/) will install both [git-lfs](https://formulae.brew.sh/formula/git-lfs) and ninja, for premake5 you will need to download the binary, and make sure its available on your path. Moving the executable to `/usr/local/bin/` will work. -Check out the repository, making sure to include the submodules. It is important to use ssh to checkout this repo, as the submodules are linked via ssh. +Check out this repository, making sure to include the submodules. It is important to use ssh to checkout this repo, as the submodules are linked via ssh. `git clone --recurse-submodules git@github.com:rive-app/rive-ios.git` -The package relies on skia, as well as rive-cpp in order to be built. To shorten the build cycle, we rely on compiled libraries for skia, rive & rive-skia-renderer. -The `./scripts/build.sh all` script will download or build appropriate libraries, be sure to run configure when making changes to our rive-cpp submodule. +The package relies on [Skia](https://skia.org/), as well as [rive-cpp](https://github.com/rive-app/rive-cpp) in order to be built. To shorten the build cycle, we rely on compiled libraries for skia, rive & rive-skia-renderer. +The `./scripts/build.sh all` script will download or build appropriate libraries, be sure to run configure when making changes to our rive-cpp submodule. ### Uploading caches -If you are contributing and you have access to Rives' aws environment, make you sure install `aws-cli` and configure it with your credentials. If you run into permission issues here `aws sts get-caller-identity` can help make sure that your local developer environment is setup to talk to AWS correctly. +If you are contributing and you have access to Rives' AWS environment, make you sure install `aws-cli` and configure it with your credentials. If you run into permission issues here `aws sts get-caller-identity` can help make sure that your local developer environment is setup to talk to AWS correctly. See https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html Note: on a Mac with brew, you can simply run 'brew install awscli' -Note: the 'dependencies' directory is just a cache of what the configure.sh script downloads. It can be removed if you suspect is is out of date, and then just rerun the script (./scripts/configure.sh) +Note: the 'dependencies' directory is just a cache of what the configure.sh script downloads. It can be removed if you suspect it is out of date, and then just rerun the script (./scripts/configure.sh) -## Changing rive-cpp/skia +### Changing rive-cpp/skia Changes within the rive-ios should just be reflected when you make builds. If you make changes within the `rive-cpp` submodule you will need to compile the prebuilt libraries, this can take a reasonably long time, but as long as you are working on rive-cpp with no uncommitted changes, it will fall back to using the cache, so you will only need to build once. -## Linting and tests +### Testing changes +In addition to tests in the project, you may want to visually test out any changes by running the `Example-iOS` app at the top-level. Open the `RiveExample.xcodeproj` project in XCode. Make sure you have the local build of iOS run before testing out this application. Feel free to bring in additional Rives to the `assets/` folder. Ensure you add the Rive to the targets by checking the checkbox "Add to targets: RiveExample" when dragging assets into the folder so it can be properly included in the assets bundle and referenced accordingly in the example app. + +### Linting and tests * We currently do not have any automatic linting set up. * Tests are run on pull request, and you should be able to run tests via xcode in the `RiveRuntime` project diff --git a/README.md b/README.md index e67075cc..87b5c551 100644 --- a/README.md +++ b/README.md @@ -1,270 +1,64 @@ ![Build Status](https://github.com/rive-app/rive-ios/actions/workflows/build_frameworks.yml/badge.svg) ![Discord badge](https://img.shields.io/discord/532365473602600965) ![Twitter handle](https://img.shields.io/twitter/follow/rive_app.svg?style=social&label=Follow) -# rive-ios +# Rive iOS -iOS runtime for [Rive](https://rive.app/) +![Rive hero image](https://rive-app.notion.site/image/https%3A%2F%2Fs3-us-west-2.amazonaws.com%2Fsecure.notion-static.com%2Fff44ed5f-1eea-4154-81ef-84547e61c3fd%2Frive_notion.png?table=block&id=f198cab2-c0bc-4ce8-970c-42220379bcf3&spaceId=9c949665-9ad9-445f-b9c4-5ee204f8b60c&width=2000&userId=&cache=v2) -Further runtime documentation can be found in [Rive's help center](https://help.rive.app/runtimes). +An iOS runtime library for [Rive](https://rive.app) that supports both UIKit and SwiftUI. -## Create and ship interactive animations to any platform -[Rive](https://rive.app/) is a real-time interactive design and animation tool. Use our collaborative -editor to create motion graphics that respond to different states and user inputs. Then load your animations -into apps, games, and websites with our lightweight open-source runtimes. +The library is distributed both through Swift Package Manager and Cocoapods. -## Beta Release -This is the iOS runtime for [Rive](https://rive.app), currently in beta. The api is subject to change -as we continue to improve it. Please file issues and PRs for anything busted, missing, or just wrong. +## Table of contents -# Installing rive-ios -## Via Swift Package Manager -To install via Swift Package Manager, in the package finder in xcode, search with the Github repository name: `https://github.com/rive-app/rive-ios` +- :star: [Rive Overview](#rive-overview) +- 🚀 [Getting Started & API docs](#getting-started) +- :mag: [Supported Devices](#supported-devices) +- :books: [Examples](#examples) +- :runner: [Migration Guides](#migration-guides) +- 👨‍💻 [Contributing](#contributing) +- :question: [Issues](#issues) -Once you have installed the package, you can run +## Rive Overview -```swift -import RiveRuntime -``` +[Rive](https://rive.app) is a real-time interactive design and animation tool that helps teams create and run interactive animations anywhere. Designers and developers use our collaborative editor to create motion graphics that respond to different states and user inputs. Our lightweight open-source runtime libraries allow them to load their animations into apps, games, and websites. -## Via Cocoapods -To install our pod, simply add the following to [cocoapods](https://cocoapods.org/) and run `pod install`. +:house_with_garden: [Homepage](https://rive.app/) -```ruby -pod 'RiveRuntime' -``` +:blue_book: [General help docs](https://help.rive.app/) -Once you have installed the pod, you can run +🛠 [Resources for building in Rive](https://rive.app/resources/) -```swift -import RiveRuntime -``` +## Getting Started -to have access to our higher level views or build on top of our bindings to control your own animation loop. +Follow along with the link below for a quick start in getting Rive React Native integrated into your multi-platform applications. -# Examples -There is an demo project in a folder called Demo-App that shows how simple it is to display beautiful animations with very few lines of code. +[Getting Started with Rive in iOS](https://github.com/rive-app/rive-ios) -There is also a more in-depth example project that show many ways of adding animated views into your app, how to add buttons & slider controls, how -to use state machines & how to navigate the contents of a rive file programatically. +## Supported Devices -To run the example, open the `Rive.xcworkspace` in Xcode and run the `RiveExample` project. Check out the -Contributing docs to get set up. +Currently, this runtime library supports a minimum iOS version of **14.0+**. Devices supported include iPhone, iPad, and Mac catalyst. -# Overview -We have provided high level Swift controller and a UIkit view to easily add Rive into your application. All of -this is built ontop of an objective c layer that allows for fine grained granular animation control. +## Examples -## SwiftUI +Check out the `Demo-App/` folder and `Example-iOS/` folder for example applications using the Rive iOS runtime. It showcases a number of ways to use the Rive component and `useRef` hook pattern: -In both SwiftUI and UIKit/Storyboard usage, you import the `RiveRuntime` into your appropriate files and interface with the `RiveViewModel` to instantiate and control Rive files. +- Setting a Rive file via a URL, or asset in the Android/iOS projects +- Setting layout and loop mode options +- Displaying single or multiple animations / artboards on one component +- Setting up and maniuplating a state machine via inputs +- ...and more! -### RiveViewModel -The simplest way of adding Rive to a View is the following: +## Migration Guides -```swift -struct AnimationView: View { - var body: some View { - RiveViewModel(fileName: "truck").view() - } -} -``` +Using an older version of the runtime and need to learn how to upgrade to the latest version? Check out the migration guides below in our help center that help guide you through version bumps; breaking changes and all! -Don't forget to call the `.view()` method in the View body! See additional usage below for more configuration options. +[Migration guides](https://help.rive.app/runtimes/overview/ios/migrating-from-2.x.x-to-3.x.x) -## UIKit -### RiveViewModel -The simplest way of adding Rive to a controller is to make a RiveViewModel and set its view as -the `RiveView` when it is loaded. +## Contributing -```swift -class AnimationViewController: UIViewController { - @IBOutlet weak var riveView: RiveView! - - // Load the truck_v7 resource assets - var viewModel = RiveViewModel(fileName: "truck_v7") +We love contributions! Check out our [contributing docs](./CONTRIBUTING.md) to get more details into how to run this project, the examples, and more all locally. - override public func viewDidLoad() { - viewModel.setView(riveView) - } -} -``` +## Issues -Rive will autoplay the first animation found in the Rive file passed in. You can also set the Rive file via a -URL like so: - -```swift -class AnimationViewController: UIViewController { - @IBOutlet weak var riveView: RiveView! - var viewModel = RiveViewModel(webURL: "https://cdn.rive.app/animations/vehicles.riv") - - override public func viewDidLoad() { - viewModel.setView(riveView) - } -} -``` - -The `RiveViewModel` can be further customized to select which animation to play, or how to fit the animation -into the view space. - -### Layout -The Rive view can be further customized as part of specifying layout attributes. - -`fit` can be specified to determine how the animation should be resized to fit its container. The available -choices are: -- `.fill` -- `.contain` -- `.cover` -- `.fitWidth` -- `.fitHeight` -- `.scaleDown` -- `.noFit` - -`alignment` informs how it should be aligned within the container. The available choices are: -- `topLeft` -- `topCenter` -- `topRight` -- `centerLeft` -- `center` -- `centerRight` -- `bottomLeft` -- `bottomCenter` -- `bottomRight` - -By default, if no `fit` or `alignment` properties are set on the `RiveViewModel`, the view will be set -with `.contain` and `.center`. - -To understand more on these options, check out the help docs [here](https://help.rive.app/runtimes/layout#fit). - -To add layout options, you can set it below like: - -```swift -let viewModel = RiveViewModel( - fileName: "truck_v7", - fit: .fill, - alignment: .bottomLeft -) -``` - -or anytime afterwards. - -```swift -viewModel.fit = .cover -viewModel.alignment = .center -``` - -### Playback Controls -Animations can be controlled in many ways. Again by default, loading a RiveViewModel will autoplay the first -animation on the first artboard. The artboard and animation can be specified by name however if there -are multiple artboards and/or animations defined in the Rive file. - -```swift -let viewModel = RiveViewModel( - riveFile: "artboard_animations", - animationName: "rollaround", - fit: .contain, - alignment: .center, - autoplay: true, - artboardName: "Square" -) -``` - -Furthermore animations can be controlled later too: - -To play an animation named "rollaround": - -```swift -viewModel.play(animationName: "rollaround") -``` - -When playing animations, the loop mode and direction of the animations can also be set: - -```swift -viewModel.play( - animationName: "rollaround", - loop: .oneShot, - direction: .backwards -) -``` - -Similarly, animations can be paused or stopped. - -```swift -viewModel.stop() -``` - -```swift -viewModel.pause() -``` - -### Delegates & Events -The `rive-ios` runtime allows for delegates that can be set on the `RiveViewModel`. If provided, -these delegates will be fired whenever a matching event is triggered to be able to hook into and -listen for certain events in the Rive animation cycle. - -Currently, there exist the following delegates: -- `RivePlayerDelegate` - Hook into the playback events -- `RiveStateMachineDelegate` - Hook into state changes on a state machine lifecycle - -You can create your own delegate or mix in with the `RiveViewModel`, implementing as many protocols -as are needed. Below is an example of how to customize a RiveViewModel's implementation of -the `RivePlayerDelegate`: - -```swift -class FancyViewModel: RiveViewModel { - init() { - super.init(fileName: "fancy_rive_file", animationName: "Drive") - } - - override func player(loopedWithModel riveModel: RiveModel?, type: Int) { - // do things when the animation loops. - } - - override func player(playedWithModel riveModel: RiveModel?) { - // do things when the animation starts playing. - } - - override func player(pausedWithModel riveModel: RiveModel?) { - // do things when the animation is paused. - } - - override func player(stoppedWithModel riveModel: RiveModel?) { - // do things when the animation is stopped. - } - - override func player(didAdvanceby seconds: Double, riveModel: RiveModel?) { - // do something every time the RiveView advances during its render loop - } -} -``` - -Then you would instantiate your view model and configure it with the `RiveView` as you normally would: - -```swift -class FancyAnimationViewController: UIViewController { - @IBOutlet weak var riveView: RiveView! - var fancyVM = FancyViewModel() - - override func viewDidLoad() { - fancyVM.setView(riveView) - } -} -``` - -## Blend modes -Rive allows the artist to set blend modes on shapes to determine how they are to be merged with the -rest of the animation. - -Each runtime is supporting the various blend modes natively, this means that there are some discrepancies -in how blend modes end up being applied, we have a test file that is shipped inside the application that -highlights the differences. - -For ios, hue and saturation blend modes do not match the original. - -Original | iOS | -:-------------------------:|:-------------------------: -![Source](images/editor.png ) | ![iOS](images/ios.png) - - -## Developing `rive-ios` -please see [CONTRIBUTING.md](/CONTRIBUTING.md) for information on how to get setup and running with -developing `rive-ios` +Have an issue with using the runtime, or want to suggest a feature/API to help make your development life better? Log an issue in our [issues](https://github.com/rive-app/rive-ios/issues) tab! You can also browse older issues and discussion threads there to see solutions that may have worked for common problems.