Nikl's Blog

Bevy ECS as a data layer for static site generation with Leptos

Sat, 06 Jan 2024 00:00:00 GMT

TLDR: I wrote a static site generator using Leptos and Bevy ECS called Cinnog.

There are many static site generators and since I tend to use this website as a playground for learning new technologies, it has used a couple of different ones in the past. The current version is built using Gatsby which is in part because Gatsby uses React (which I wanted to learn at the time) and because I like their data layer.

A data layer in a static site generator simplifies collecting and preparing data required to build the website. For example, a user might get their blog posts from a headless CMS and generate different resolutions for image assets. When deciding what routes to generate, they can look into the data layer to see what blog posts there are and then generate a route for every post. The just-generated smaller version of a post's image could be displayed on the list of blog posts while the post itself uses the original version.

Many generators support a given structure of data and asset files but leave more complex data loading and preparation to their users. I think it is very helpful when a generator provides the structure and access for collecting, preparing and using any kind of data needed for building a website¹. This is especially the case if there is a good API for third-party plugins to hook into.

So... I have some time during the holidays... How about trying to build a static site generator with Leptos using Bevy ECS as the data layer?

Static site generation with Leptos

Leptos is an open source Rust framework for building websites. It supports both client-side rendering and server-side rendering utilizing WebAssembly (WASM) for reactivity in the browser. By default, the client-side rendered approach is a single page application, where the index.html loads a WASM binary that will render the website and handle navigation client-side. Every component that you write will be rendered out of the same WASM binary in the browser. Leptos uses an interesting setup for fine-grained reactivity that performs very well.

Since version 0.5, Leptos supports basic static site generation (see the release notes on "Static Site Generation"). It can be used to pre-generate some routes in a server-side-rendered application for improved performance. If you restrict your whole project to static routes, you can generate the complete website with multiple pages.

In the same update, Leptos also released an experimental feature called "islands" (see the release notes on Islands). When using islands, "normal" Leptos components are static and served as HTML instead of being rendered client-side through WASM. Only islands will use WebAssembly for reactivity in the browser.

I think the combination of islands and static site generation is perfect for a website like mine. Leptos is the first web framework in Rust that seriously tempts me to rewrite this website (again). If you are interested in web development with Rust, check it out!

What has been keeping me from rewriting this blog using Leptos, is that I use Gatsby's GraphQL data layer to do a bunch of stuff that is not supported in Leptos itself. I could do things like reading all my markdown files and converting them to HTML as part of the Leptos app, but it feels like there should be a general data layer that one can fill and manipulate before reading it from the Leptos components. Things like automatically creating anchors for headers or generating an RSS feed from all blog posts are easier with a data layer.

Bevy ECS

Bevy is an open source Rust game engine built with the Entity Component System (ECS) pattern to separate data from behaviour. Using ECS involves breaking up your program into entities, components, and systems. Entities are identifiers that are assigned groups of components. Systems process entities with given sets of components².

In Bevy ECS, components are simple rust structs and systems are "normal" functions. A system requests the data it needs through its parameters, which feels a bit like dependency injection. One can think about an ECS as an in-memory database where systems are the queries.

Many reasons for choosing an ECS for game development are not relevant for a static site generator. And honestly, I am not yet convinced that this is a sane idea at all. But the API of Bevy ECS is nice to work with. Writing rust functions that automatically get the data they ask for feels close to perfect for querying a data layer.

Bevy and Leptos call different things "component". In Leptos, a component is a building block for the website (like a React component). While in Bevy, components are data and live in the ECS World. In this post, I try to write "Bevy component" and "Leptos component" to differentiate between the two.

What could it look like

Static site generation with Leptos currently consists of two steps:

Collect all static routes
Build route content

Leptos compiles some code only for the native target. This code usually serves the website and offers server functions. Part of this code will be filling the data layer from the file system, external APIs, or anywhere else. Once all data is in the ECS, the two steps from above are executed and given access to the data layer. What routes to build can be dependent on the data in the ECS. The same goes for the content of Leptos components in step 2.

Functionality like converting markdown to HTML could be shared in the form of Bevy ECS systems. Common functionality can be part of the generator itself. More specific systems that, for example, build RSS feeds could be offered by external crates. As long as the generator establishes a set of Bevy components for things like HTML, crates should be compatible with each other and the basic generator should be easy to extend. The Bevy ecosystem shows what is possible in regard to extending an ECS by sharing a set of Components and Systems.

What does it look like

When I started to write this post, the whole thing was only an idea. Some days later, I had a working integration of Bevy ECS into Leptos and had to give it a name. It's now called Cinnog³. You can find the main repository on GitHub as well as an example website that is hosted on Netlify.

In the main function of the example website, the data layer is filled from the file system. Some ron files are read from the people directory and markdown files are read from the blog directory. All markdown in the data layer is then converted to HTML.

#[tokio::main]
async fn main() -> io::Result<()> {
    let mut data = DataLayer::new();
    data.insert_resource(SiteName("Bevy ECS + Leptos = 💕".to_owned()));

    data.run(read_ron_files_from_directory::<PersonData>, "people")?;
    data.run(read_markdown_from_directory::<PostFrontMatter>, "blog")?;
    data.run(convert_markdown_to_html, ());

    data.build(App).await
}

It's rather crude, but quite compact and all the used systems are part of Cinnog.

Data types like PersonData and PostFrontMatter implement the Trait Ingest. This Trait controls which components will be added to the data layer. For example, PersonData is split into two components:

#[derive(serde::Deserialize)]
struct PersonData {
    name: String,
    age: u8,
}

impl Ingest for PersonData {
    fn ingest(self, commands: &mut EntityCommands) {
        commands.insert((PersonName(self.name), Age(self.age)));
    }
}

The ingest method has to be implemented. If the file path is important, ingest_path can be overwritten. I started sorting the example blog posts into year directories:

#[derive(serde::Deserialize, Default)]
#[serde(default)]
pub struct PostFrontMatter {
    pub test: String,
    pub title: String,
    pub draft: bool,
}

impl Ingest for PostFrontMatter {
    fn ingest(self, commands: &mut EntityCommands) {
        commands.insert((TestFontMatter(self.test), PostTitle(self.title), Post));
        if self.draft {
            commands.insert(DraftPost);
        }
    }

    fn ingest_path(&self, commands: &mut EntityCommands, path: &Path) {
        let reg = Regex::new(r"/blog/(<year>[0-9]+)/\.*").unwrap();
        if let Some(caps) = reg.captures(&path.to_string_lossy()) {
            let year = &caps["year"];
            commands.insert(BlogYear(year.to_owned()));
        };
        commands.insert(default_bundle_from_path(path));
    }
}

So far, I like the direction Cinnog is taking. There are a lot of rough edges, but basic functionality works. Since the Holidays are over, development might slow down a bit. But I will try to get Cinnog to the point where it can be used for this website. It's definitely a fun project! I might attempt to upstream the required changes to Leptos⁴. Smaller things like removing the .static file ending for statically generated files will probably not be an issue, but I had to make some changes to leptos_router to integrate with Bevy ECS and for those I am unsure how that could be upstreamed.

Update: Cinnog no longer relies on a custom fork of Leptos as of Leptos version 0.6. Cinnog is now available on crates.io.

All changes from the custom fork were either upstreamed (#2113 and #2207) or no longer needed after a refactor of the Bevy ECS integration into Leptos.

Thank you for reading! If you have any feedback, questions, or comments, you can find me at @nikl.me or on the Bevy Discord server (@nikl).

This increases complexity and the gained flexibility might not always be needed. But the generator could use the data layer to easily support a classic structure with data files. Simple projects would almost work out of the box, but if they grow and need more flexibility, the data layer could offer it.↩
Properly explaining ECS is out of scope here, but there are already a lot of good resources for that. You could take a look at Sander's ECS FAQ for general information and the Bevy ECS docs for some code examples.↩
Following the naming of Leptos ("thin", "small" in Greek), Cinnog means "small" in one of Tolkien's Elvish languages. I just thought it reads nice ^^↩
Some smaller changes have been upstreamed already: leptos-rs/leptos#2113 ↩

Notes on mobile development with Bevy #2

Thu, 03 Aug 2023 00:00:00 GMT

My Bevy mobile app is very incomplete, but I would like to be able to distribute test builds early on. That means Android builds need to be acceptable for the Play Store and iOS builds need to pass Apple's bar for the App Store. On the way to that goal, there are a couple technical issues to solve and some configuration to do in App Store Connect and Google Play Console. I will concentrate on the technical challenges while mentioning some store configurations.

Most of this effort did not directly go into my current app project. I decided to add iOS and Android support to bevy_game_template first. This way, the community might benefit more from my work and I can just copy the setup for other projects.

The starting point of this post is the mobile example from Bevy with small adjustments discussed in a previous post.

Android

Getting an Android App Bundle

The cargo-apk setup from Bevy's mobile example allows us to build APK files. The Play Store no longer accepts APKs, but requires app bundles. This makes sense to keep downloads small and still support multiple device ABIs (Application Binary Interface), but it requires some extra work to get an app bundle for a Bevy game.

The only tool I could convince to create an app bundle from my Bevy project is xbuild, the WIP successor of cargo-apk¹. We can configure xbuild to bundle our project for Android with the following manifest.yaml

android:
  gradle: true
  icon: "your_icon.png"
  manifest:
    package: "com.example.bevygame"
    version_code: 1
    application:
      label: "Bevy game"

Currently, xbuild decides to create app bundles only when using gradle: true and only for production builds. Running x build --platform android --store play creates an app bundle, but derived APKs instantly crash.

I had to do a couple changes to get xbuild to create working app bundles. Some of them might get upstreamed, but a few are obvious hacks that only work for the Bevy project structure (like a single, hardcoded assets directory). For the xcode commands in this post to work as expected, you need to install xbuild from my fork: cargo install --git https://github.com/NiklasEi/xbuild.

libc++ shared is missing

Looking at the logs with adb logcat while trying to start the app on my phone yields the following error:

java.lang.UnsatisfiedLinkError: Unable to load native library "/data/app/~~0cxWIprct-rKy7Vggu9E4g==/me.nikl.bevygame-YTVT_qxOwHzm_kGsGV9cYw==/lib/arm64/libmobile.so": dlopen failed: library "libc++_shared.so" not found

The helpful line among hundreds of unhelpful ones.

Opening the APK as an archive indeed shows that lib/arm64-v8a/ does not include libc++_shared.so, while an APK built with cargo-apk includes it. This library is required for audio support in Bevy. I probably could have just ripped out audio for now and moved on, but who am I kidding? I want audio!

Telling gradle to include libc++_shared.so turned out to be more complicated than I had thought. Usually, it should realize on its own that the library is needed and include it. The problem is, that we are not using gradle to build the game library, but cargo. So gradle has no way of knowing that we need libc++_shared.so. In the end, I gave up on a "clean" solution and went with a hack. I basically told gradle that the project includes a c++ library which requires the shared library. The c++ project is empty, but it does the trick and creates minimal bloat (~4kB).

With this change, the UnsatisfiedLinkError from above is gone, but the game still doesn't work.

Include assets

While cargo-apk allows simply configuring an asset directory, xbuild does not jet support that. There is an open PR to add support for assets to the non-gradle builds, but that only works for APKs².

Since Bevy usually comes with a single assets directory in the root of the project, I told gradle to just include that with a hardcoded path from deep inside the target directory. At this point, the build generated by xbuild using gradle runs properly.

Continuous deployment

The app bundle needs to be signed with jarsigner and can then be uploaded to Google Play Console. Doing this manually for every version is no fun, so I wrote a GitHub workflow for it.

Support more Android devices

After uploading an app bundle, we can use the app bundle explorer in the Google Play Console to check bundle exports for different devices. My early bundles contained libraries for 4 different ABIs due to the dummy c++ library and gradle compiling for all non-deprecated ABIs by default. The game, on the other hand, was only compiled for arm64-v8a, which was hardcoded in xbuild.

The device list in the app bundle explorer can be filtered by ABI. Out of the 18.919 devices, 8.599 are arm64-v8a and 10.096 armeabi-v7a. Most of the other couple hundred devices are x86 or x86_64³. I went back to xbuild, fixed the support for arm in gradle builds and told it to always build for arm64 and arm when making a build with the --store option.

The bundle still contains lib directories for x86 and x86_64 due to the "dummy cpp lib" workaround. Those lib directories tell the play store that our app bundle can generate APKs for those ABIs which is not correct since we do not build our game for them. A small gradle configuration tells it to not build the dummy library for the x86(64) ABIs.

iOS

I don't own a Mac or iPhone, but still want to support iOS. So I borrowed a Mac for a couple of days to get everything set up in bevy_game_template.

The first time I tried to let Xcode publish the app with the copied setup from the Bevy mobile example, the process ended in a list of errors from the App Store. The required changes boiled down to adding an app icon and a launch screen.

Add Icons

The App Store requires apps for iOS 11 or later to include app icons with an asset catalog. I did this following the developer documentation from Apple (icon + name).

Adding a launch screen

Our app requires a launch screen. The Info.plist from the Bevy mobile example includes an entry for UILaunchStoryboardName, but the launch screen itself is not included. I created one in Xcode following a stack overflow answer that just contains a centered icon.

Continuous deployment

At this point, Xcode can create app builds and push them to App Store Connect. I spent some time on creating a GitHub workflow to automate the process. The iOS workflow requires a bit more setup than the Android one, but hopefully, I don't need to organize a Mac again anytime soon.

One issue left...

...the app has no audio on iOS. I have only tested this with bevy_kira_audio so far, so bevy_audio might be fine. Maybe someone else knows what's going on here?

Getting ready for a release

Both stores require some setup for the store pages. The app from bevy_game_template is not supposed to go live in the app stores, but it would be nice to be able to share a link that allows anyone to install it. For iOS the goal is "external testing" in AppFlight. In Google Play this release type is called "open testing". Both of these programs require the app to go through a review and the store page to be mostly complete.

Getting screenshots

Screenshots are a big part of finishing the required setup for publishing. Luckily, the last Bevy update came with a very handy screenshot API. Setting the window dimension and adding the below system gives nice screenshots in configurable resolution.

fn screenshot_on_spacebar(
    input: Res<Input<KeyCode>>,
    main_window: Query<Entity, With<PrimaryWindow>>,
    mut screenshot_manager: ResMut<ScreenshotManager>,
    mut counter: Local<u32>,
) {
    if input.just_pressed(KeyCode::Space) {
        let path = format!("./screenshot-{}.png", *counter);
        *counter += 1;
        screenshot_manager
            .save_screenshot_to_disk(main_window.single(), path)
            .unwrap();
    }
}

The system is borrowed from the Bevy screenshot example.

Thank you for reading! If you have any feedback, questions, or comments, you can find me at @nikl.me or on the Bevy Discord server (@nikl).

Crossbow might also work, but I didn't manage to set it up correctly. If you do, please tell me.↩
It also doesn't support globs yet, which is a bit unpractical for Bevy's asset directory. Every file and subdirectory would need to be listed separately. I added simple glob support for APK builds on my fork and will try to upstream that once basic assets support has landed.↩
Now I understand why the Bevy mobile example has the two arm targets configured for cargo-apk builds :D↩

GitHub workflow to publish a Bevy Android app

Wed, 02 Aug 2023 00:00:00 GMT

This is a guide on how to configure a GitHub workflow for building, signing and publishing an Android app that uses Bevy (there is a separate guide for iOS).

The workflow uses the tool xbuild from a customized fork, which includes a couple fixes and hacks needed to get app bundles. Some of these changes are explained and motivated in a separate post. If you want to see the workflow in use, you can take a look at bevy_game_template

xbuild setup

You can install xbuild from my fork with cargo install --git https://github.com/NiklasEi/xbuild. Check your environment with x doctor and install missing dependencies.

To run your project with xbuild, add the following as manifest.yaml:

android:
  gradle: true
  icon: "icon.png"
  manifest:
    package: "com.example.app"
    version_code: 1
    application:
      label: "Bevy game"

Make sure to correct the path to your app icon. Also, update the package identifier and the app label.

Connect your Android device to your machine and note down the device id from x devices. Now run x run --device <device ID>. Gradle should build the project and then start your app on the device. If this works, you can also try building a bundle with x build --release --platform android --store play.

The workflow

The following goes into a yaml file in your GitHub workflows directory (for example .github/workflows/release-android-google-play.yaml).

name: release-android-google-play

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'GitHub Release'
        required: true
        type: string
      play_release:
        description: 'Release name from google play console'
        required: true
        type: string

env:
  # used for uploading the app to a GitHub release
  APP_NAME: bevy_game
  BUNDLE_PATH: "target/x/release/android/mobile.aab"
  PACKAGE_NAME: "com.example.app"
  # release track; you can promote a build to "higher" tracks in the play console or publish to a different track directly
  # see track at https://github.com/r0adkll/upload-google-play#inputs for more options
  TRACK: internal
  MOBILE_DIRECTORY: mobile

permissions:
  contents: write

jobs:
  bundle-sign-release:
    runs-on: ubuntu-latest
    timeout-minutes: 40
    steps:
      - name: Install Dependencies
        run: sudo apt-get update; sudo apt-get install pkg-config libx11-dev libasound2-dev libudev-dev lld llvm
      - uses: actions/checkout@v3
      - uses: dtolnay/rust-toolchain@stable
      - name: Add Android targets
        run: rustup target add aarch64-linux-android armv7-linux-androideabi
      - name: Install cargo-binstall
        run: curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash
      - name: Install xbuild
        run: cargo binstall --git https://github.com/NiklasEi/xbuild --bin-dir x xbuild -y
      - name: Build app bundle
        run: |
          cd ${{ env.MOBILE_DIRECTORY }}
          x doctor
          x build --release --platform android --store play
      - name: sign app bundle
        run: |
          KEYSTORE_PATH=${{ runner.temp }}/upload-keystore.jks
          echo -n "${{ secrets.PLAYSTORE_KEYSTORE }}" | base64 --decode > $KEYSTORE_PATH
          jarsigner -verbose -sigalg SHA256withRSA -digestalg SHA-256 -keystore $KEYSTORE_PATH -storepass "${{ secrets.PLAYSTORE_KEYSTORE_PASSWORD }}" ${{ env.BUNDLE_PATH }} upload
      - name: Upload self-signed bundle to GitHub
        uses: svenstaro/upload-release-action@v2
        with:
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          file: ${{ env.BUNDLE_PATH }}
          asset_name: ${{ env.APP_NAME }}_${{ inputs.version }}_android.aab
          release_name: ${{ inputs.version }}
          tag: ${{ inputs.version }}
          overwrite: true
      - name: prepare Google play store secrets
        run: |
          SERVICE_ACCOUNT=${{ runner.temp }}/service-account.json
          echo -n "${{ secrets.PLAYSTORE_SERVICE_ACCOUNT }}" | base64 --decode > $SERVICE_ACCOUNT
      - name: upload bundle to Google play store
        uses: r0adkll/upload-google-play@v1
        with:
          serviceAccountJson: ${{ runner.temp }}/service-account.json
          packageName: ${{ env.PACKAGE_NAME }}
          releaseName: ${{ inputs.play_release }}
          releaseFiles: ${{ env.BUNDLE_PATH }}
          track: ${{ env.TRACK }}

Change the env section according to your project. The bundle name is going to be your crate name with an aab file ending. If the crate that is built as a library for Android is at the root of your project, remove the MOBILE_DIRECTORY variable and its usage. Otherwise, adapt the value.

The workflow requires multiple secrets to be configured in GitHub. You need to have a Google Play Developer account which comes with a one-time 25$ registration fee.

Before configuring the required secrets, let's quickly go through the workflow steps:

Install dependencies for Bevy and xbuild
Check out the repository
Install the stable toolchain of Rust
Install Rust targets for Android
Install cargo-binstall to significantly speed up the next step
Install xbuild from my fork using a prebuilt binary
Create an app bundle with xbuild
Sign the app bundle using jarsigner
Upload the bundle to a GitHub release
Prepare the Google Play Store service account secret
Upload the bundle to Google Play Store

Produced app bundles will contain libraries for the ABIs arm64-v8a and armeabi-v7a, which cover more than 90% of the devices currently supported by Android (see Notes on mobile development with Bevy #2 for more details).

Setting up the secrets

Simple strings like passwords can directly go into a GitHub secret. Files will be encoded first using base64 (e.g. openssl base64 -in ~/upload-keystore.jks).

To configure a secret go to your repository settings in GitHub. Navigate to "Security" -> "Secrets and variables", select "Actions" then click "New repository secret".

PLAYSTORE_KEYSTORE and PLAYSTORE_KEYSTORE_PASSWORD
- You can generate a keystore with keytool -genkey -v -keystore ~/upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload
- add the password and the base64 encoded keystore to GitHub
PLAYSTORE_SERVICE_ACCOUNT
- go to the Service accounts page to create a new service account
  - select a project or create a new one, then click on "Create service account"
  - set a name and press "Continue"
  - click "Select a role", then find and select "Service Accounts" -> "Service Account User", and press "Done"
  - open the "Actions" vertical three-dot menu of the service account you just created
  - select "Manage keys" and click "Add Key" + "Create New Key"
  - chose the json type and press "Create"
  - the key should be automatically downloaded to your machine
  - encode the key and add it to GitHub
- visit the Google Play Console and navigate to "Setup" -> "API access"
- under "Service accounts", find your newly created account and click "Manage Play Console permissions"
- go to the "App permissions" tab and add your app
- click "Invite user" to finish the process

Before running the workflow for the first time, got to Play Store Connect and create a release in "Internal testing". Remember the name (e.g. "v0.1.0") since you will have to pass it to the workflow. Create a bundle on your machine following the workflow steps 7 and 8, then upload it manually to the release. Otherwise, the Google Play API will return the error "Package not found".

Now you can head over to the "Actions" tab in your repository. Find the workflow in the list on the left, select it and click "Run workflow" in the top right. Put a name for a GitHub release in the first input and the release name from Google Play Console in the second and press "Run workflow".

Final comments

The app build number is taken from the manifest.yaml and needs to be bumped for every build. Otherwise, the upload is not accepted by Google Play Console.

Workflow runs are free for public repositories on GitHub. If your project is private, it will use build minutes from your allowance (2000 minutes per month on a free account).

Thank you for reading! If you have any feedback, questions, or comments, you can find me at @nikl.me or on the Bevy Discord server (@nikl).

GitHub workflow to publish an iOS app

Sat, 29 Jul 2023 00:00:00 GMT

Last update Jan 24 2026 (fixed an appstore connect link)

I built a GitHub workflow to bundle, sign and publish an iOS app. There are already a couple guides on how to do this, but none of them worked out of the box for me (an iOS/mac noob). With lots of googling plus trial and error, I pieced together the missing and broken parts. Since I wouldn't wish that on anyone, here is some information on how to set up the workflow.

The project that the workflow was build for might be a bit unconventional. It's a mobile app using the Rust game engine Bevy. The workflow expects a specific project structure with the Xcode project living in a subdirectory. You can change the name of the subdirectory and the Xcode project in the env section. The whole workflow is part of this post, but if you want to see it in use, you can look at bevy_game_template.

The Workflow

The following goes into a yaml file in your GitHub workflows directory (for example .github/workflows/release-ios-testflight.yaml).

name: release-ios-testflight

on:
   workflow_dispatch:
      inputs:
         version:
            description: 'Version - e.g. v1.2.3'
            required: true
            type: string

env:
   # used for uploading the app to a GitHub release
   APP_NAME: bevy_game
   XCODE_PROJECT: mobile
   MOBILE_DIRECTORY: mobile

permissions:
   contents: write

jobs:
   build-for-iOS:
      runs-on: macos-latest
      timeout-minutes: 40
      steps:
         - uses: actions/checkout@v3
         - uses: dtolnay/rust-toolchain@stable
         - name: Add iOS targets
           run: rustup target add aarch64-apple-ios
         - name: Install the Apple certificate and provisioning profile
           id: profile
           env:
              IOS_CERTIFICATE: ${{ secrets.IOS_CERTIFICATE }}
              IOS_CERTIFICATE_PASSWORD: ${{ secrets.IOS_CERTIFICATE_PASSWORD }}
              IOS_PROVISION_PROFILE: ${{ secrets.IOS_PROVISION_PROFILE }}
              IOS_KEYCHAIN_PASSWORD: ${{ secrets.IOS_KEYCHAIN_PASSWORD }}
           run: |
              # create variables
              CERTIFICATE_PATH=${{ runner.temp }}/build_certificate.p12
              PP_PATH=${{ runner.temp }}/profile.mobileprovision
              KEYCHAIN_PATH=${{ runner.temp }}/app-signing.keychain-db

              # import certificate and provisioning profile from secrets
              echo -n "$IOS_CERTIFICATE" | base64 --decode -o $CERTIFICATE_PATH
              echo -n "$IOS_PROVISION_PROFILE" | base64 --decode -o $PP_PATH
              uuid=`grep UUID -A1 -a $PP_PATH | grep -io "[-A-F0-9]\{36\}"`
              echo "uuid=$uuid" >> $GITHUB_OUTPUT

              # create temporary keychain
              security create-keychain -p "$IOS_KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
              security set-keychain-settings -lut 21600 $KEYCHAIN_PATH
              security unlock-keychain -p "$IOS_KEYCHAIN_PASSWORD" $KEYCHAIN_PATH

              # import certificate to keychain
              security import $CERTIFICATE_PATH -P "$IOS_CERTIFICATE_PASSWORD" -A -t cert -f pkcs12 -k $KEYCHAIN_PATH
              security list-keychain -d user -s $KEYCHAIN_PATH

              # apply provisioning profile
              mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles
              cp $PP_PATH ~/Library/MobileDevice/Provisioning\ Profiles/$uuid.mobileprovision
         - name: Build app for iOS
           run: |
              cd ${{ env.MOBILE_DIRECTORY }}
              xcodebuild PROVISIONING_PROFILE=${{ steps.profile.outputs.uuid }} -scheme ${{ env.XCODE_PROJECT }} clean archive -archivePath "Actions" -configuration Release -arch arm64
         - name: export ipa
           env:
              EXPORT_PLIST: ${{ secrets.IOS_EXPORT_PRODUCTION }}
           run: |
              EXPORT_PLIST_PATH=${{ runner.temp }}/ExportOptions.plist
              echo -n "$EXPORT_PLIST" | base64 --decode --output $EXPORT_PLIST_PATH
              xcodebuild PROVISIONING_PROFILE=${{ steps.profile.outputs.uuid }} -exportArchive -archivePath ${{ env.MOBILE_DIRECTORY }}/Actions.xcarchive -exportOptionsPlist $EXPORT_PLIST_PATH -exportPath ${{ runner.temp }}/export
         - name: decode API key
           env:
              API_KEY_BASE64: ${{ secrets.IOS_APPSTORE_API_PRIVATE_KEY }}
           run: |
              mkdir -p ~/private_keys
              echo -n "$API_KEY_BASE64" | base64 --decode --output ~/private_keys/AuthKey_${{ secrets.IOS_APPSTORE_API_KEY_ID }}.p8
         - name: Upload to testflight
           run: |
              xcrun altool --validate-app -f ${{ runner.temp }}/export/${{ env.XCODE_PROJECT }}.ipa -t ios --apiKey ${{ secrets.IOS_APPSTORE_API_KEY_ID }} --apiIssuer ${{ secrets.IOS_APPSTORE_ISSUER_ID }}
              xcrun altool --upload-app -f ${{ runner.temp }}/export/${{ env.XCODE_PROJECT }}.ipa -t ios --apiKey ${{ secrets.IOS_APPSTORE_API_KEY_ID }} --apiIssuer ${{ secrets.IOS_APPSTORE_ISSUER_ID }}
         - name: Upload release
           uses: svenstaro/upload-release-action@v2
           with:
              repo_token: ${{ secrets.GITHUB_TOKEN }}
              file: ${{ runner.temp }}/export/${{ env.XCODE_PROJECT }}.ipa
              asset_name: ${{ env.APP_NAME }}_${{ inputs.version }}_ios.ipa
              release_name: ${{ inputs.version }}
              tag: ${{ inputs.version }}
              overwrite: true

Configure the env section according to your project.

The workflow requires multiple secrets to be configured in GitHub. Some of those need an active membership in the Apple developer program, which costs 99$ per year. We'll get back to getting and configuring the secrets later. First, let's go through the workflow steps:

Check out the repository
Install the stable toolchain of Rust (remove this in case you do not use Rust)
Install Rust targets for iOS (remove this in case you do not use Rust)
Some of the required secrets need to be written to files in specific locations. The build certificate and provisioning profile are files encoded in base64 and need to be decoded.
- The build certificate is imported into a temporary keychain using its password. Xcode will read the certificate from the keychain automatically.
- Provisioning profiles are picked up by Xcode from ~/Library/MobileDevice/Provisioning\ Profiles/. I use its uuid as file name, because I had some issues where Xcode couldn't find the correct profile, but I am not sure if this is actually needed.
Use xcodebuild to archive your project.
Use ExportOptions.plist to export an ipa from the archive.
Decode the API to talk to the App Store. The key is moved to ~/private_keys and needs to contain the key id in its name for altool to find it.
Talk to the App Store to validate and upload the ipa.
Upload the self-signed ipa to a GitHub release.

Before starting the workflow for the first time, your app should be configured in App Store Connect. The builds will automatically show up in TestFlight after a short processing period.

Setting up the secrets

Simple strings like passwords can directly go into a GitHub secret. Files will be encoded first using base64 (e.g. openssl base64 -in ~/ExportOptions.plist).

To configure a secret go to your repository settings in GitHub. Navigate to Security - Secrets and variables, select Actions then click "New repository secret".

You will need:

IOS_CERTIFICATE and IOS_CERTIFICATE_PASSWORD
- You can use Xcode to create a certificate for you
  - Use the certificate type Apple Distribution to be able to publish the builds in the store
- Export the certificate as .p12 from xbuild and set the password while doing so
- The exported .p12 file needs to be base64 encoded before adding it as a GitHub secret
IOS_PROVISION_PROFILE
- After creating your distribution certificate, you can visit your developer account resources to create a new distribution profile. Select "+", chose Distribution - App Store, then select your app and the previously created distribution certificate. The final step is setting the name of your profile, which you should remember for the export options further down. After clicking "Generate", you can download your .mobileprovision file and proceed with base64 encoding and configuring the secret in GitHub.
IOS_KEYCHAIN_PASSWORD
- This can be any string since it is only used to create and open a temporary keychain on the action runner

IOS_EXPORT_PRODUCTION

You can start off your ExportOptions.plist with the following:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>destination</key>
        <string>export</string>
        <key>provisioningProfiles</key>
        <dict>
               <key>{application identifier e.g. me.nikl.bevygame}</key>
               <string>{name of distribution profile}</string>
        </dict>
        <key>manageAppVersionAndBuildNumber</key>
        <true/>
        <key>method</key>
        <string>app-store</string>
        <key>signingStyle</key>
        <string>manual</string>
        <key>stripSwiftSymbols</key>
        <true/>
        <key>teamID</key>
        <string>{your team id}</string>
        <key>uploadSymbols</key>
        <true/>
</dict>
</plist>

Replace the application identifier, provisioning profile name and team ID
- You can find your teamID under "Membership details" in your account info
Encode the file using base64 and add it to GitHub

IOS_APPSTORE_API_PRIVATE_KEY and IOS_APPSTORE_API_KEY_ID
- Follow the docs to create a new API key
- You can use the role "Developer"
- Download (.p8) and encode the key using base64 before adding it as a secret
- Copy the key ID of the just created key from the table
IOS_APPSTORE_ISSUER_ID
- Visit "Users and Access" to copy the issuer ID

Now that all required secrets are configured, head over to the "Actions" tab in your repository. Find the workflow in the list on the left, select it and click "Run workflow" in the top right.

Final comments

The version input of the workflow is only used as GitHub release to upload the artifact. The actual app version is defined in your Info.plist and needs to be new for the App Store to accept your build.

You cannot easily install the signed ipa on any device without going through the App Store or TestFlight. For macOS apps, there is a different certificate type called "Developer ID Installer" to do so, but there doesn't seem to be something similar for iOS apps.

Workflow runs are free for public repositories on GitHub. If your project is private, it will use build minutes from your allowance (2000 minutes per month on a free account). Know that every minute with a macOS runner is billed as 10 minutes.

In case you are also interested in Android development with Bevy, there is a separate post about a workflow for Android builds.

Thank you for reading! If you have any feedback, questions, or comments, you can find me at @nikl.me or on the Bevy Discord server (@nikl).

Notes on Android development using Bevy

Sat, 08 Jul 2023 00:00:00 GMT

While working on an Android logic puzzle app with Bevy, I learned some things about the current state of Android support in the engine and its dependencies. The following are a few notes that hopefully are not only useful to myself, but also to others who would like to use Bevy to write an Android app.

The starting point is Bevy's mobile example. Take a look at the example Readme for instructions on how to run it. For now, I will ignore all things iOS since I don't have a setup for iOS development. When my app was only a copy of the Bevy example, I could connect my phone, run cargo apk run -p <app_lib_name> and the example would open up after around one and a half minutes. Let's work on that.

Shorter feedback cycles

Installing the app on my phone should be significantly faster than one minute to not constantly wait after code changes. cargo apk run mostly does three things:

Compile your code as cdylib
Bundle and sign the APK
Install the APK on the connected device

Looking at the first step already, we can half the compile time of the Bevy example. It configures two android targets aarch64-linux-android and armv7-linux-androideabi. Every code change you make will be compiled for both targets, but my phone ran fine with only either of them configured. For now, I only build for aarch64-linux-android. When it comes to releasing the app, I might revisit this and add more targets.

The second step is pretty fast already. One point about the signing though: if you would like a release build, cargo-apk will complain, that you need a key. If you only want something quick for testing, you can point to the same key that is already used for debug builds:

[package.metadata.android.signing.release]
path = "~/.android/debug.keystore"
keystore_password = "android"

Configuration for signing a release APK with the debug key. This is the path to the debug keystore on my linux laptop, but it should be similar for other OS.

For incremental installs, the third step took by far the longest. More than a minute was spent on copying the APK to my phone. This was easily explained when looking at the size of the bundled APK: 1.5Gb. Half of the APK was gone once I removed a target, but ~750Mb is still too much.

Looking at the documentation of cargo-apk, I found an option to strip the shared libraries from debug symbols. This is done by default for release builds, but you can enable it for all builds by configuring strip = "strip" under [package.metadata.android] (this is now also done for the Bevy example).

While developing android specific things, I can now run cargo watch -x 'apk run -p <app_lib_name>' and the app opens up in acceptable time (compile + ~6s).

Desktop build

Even with all the size improvements for our debug APK, running the application on the phone takes longer than on desktop. For code changes that are not platform specific, it's helpful to have a desktop target set up. Especially, because I can't get the app to run in an emulator.

Since cargo-apk requires a cdylib, I split the project into two crates. One crate contains a library exporting everything as a plugin and a main.rs file to target desktop. The other crate only contains a lib.rs file, uses the #[bevy_main] macro, and configures the android application in its Cargo.toml.

Now cargo watch -x run restarts the app on my desktop after every code change.

Where to render

Different mobile devices have different screen geometries and cut-outs for e.g. cameras. A mobile application should not render content behind the info bar or software buttons. This is one of the challenges I have not completely solved yet.

My current attempt is the following system that runs in an early state and every time the orientation changes:


pub fn calculate_layout(
    mut commands: Commands,
    windows: NonSend<WinitWindows>,
    primary_window: Query<Entity, With<PrimaryWindow>>,
) {
    info!("Calculating layout");
    let primary_entity = primary_window.single();
    let primary = windows.get_window(primary_entity).unwrap();
    let inner = primary.inner_size();
    let scale = primary.scale_factor();

    let content_rect = if cfg!(target_os = "android") {
        use winit::platform::android::WindowExtAndroid;
        let content_rect = primary.content_rect();
        let content = ContentRect {
            bottom: (inner.height as f32 - content_rect.bottom as f32) / scale as f32,
            left: content_rect.left as f32 / scale as f32,
            right: (inner.width as f32 - content_rect.right as f32) / scale as f32,
            top: content_rect.top as f32 / scale as f32,
        };
        info!("Adjusting content to {content:?} due to inner {inner:?}, content {content_rect:?} and scale {scale}");

        content
    } else {
        ContentRect {
            bottom: 0.,
            left: 0.,
            right: 0.,
            top: 0.,
        }
    };
    commands.insert_resource(Layout { content_rect });
}

#[derive(Resource)]
pub struct Layout {
    pub(crate) content_rect: ContentRect,
}

#[derive(Debug)]
pub struct ContentRect {
    pub top: f32,
    pub bottom: f32,
    pub right: f32,
    pub left: f32,
}

This system calculates the distance in pixels that content should keep from the borders of the screen to not overlap with cut-outs or things like software buttons. The pixel values are stored in a resource and default to 0 on other platforms than Android.

The idea is to use the Layout resource in all systems that spawn sprites or UI and use the top, bottom, left and right values to keep appropriate distance from software buttons and cut-outs. On my S10+, this works perfectly for the software buttons on the bottom, but not for the info bar on top of my screen. The content rect reports too big numbers for the top and I opened rust-windowing/winit#2931 for that (but I am not sure if this is really a winit issue or further upstream).

Performance

A simple app should not constantly drain battery while running 60 FPS for nothing. The first thing we can do is to tell winit to only run frames when something happened (like user input). In Bevy, we can do this by adding the resource WinitSettings::desktop_app() to our app. This configures winit to run only one frame every 5 seconds while the application is open, but not receiving any user input.

These winit settings can break animations, since the screen effectively freezes without user input. If you know that you want to run the next frame independent of the user doing something or not, you can send a RequestRedraw event.

My app will only contain logic puzzles and as such doesn't need input apart from touch events; I thought. Then I attempted to use the software back button on my phone and didn't get any keyboard input. This seems to be an open issue in winit (rust-windowing/winit#2304). After a little investigation, I hacked something in my bevy fork and moved on (for now).

On desktop, I am used to navigating backwards with my mouse. This is not supported in the latest winit release, but was merged recently and should make its way to Bevy soon. For now, I hardcoded MouseButton::Other(8) to be back navigation.

Moving the app to the background

Anyone playing around with Bevy on Android will notice, that the App lifecycle events are not yet completely handled. When you minimize and open the app back up, it will not resume where you left of, but start from the beginning (Update - Fixed in Bevy 0.12). This issue is known and solutions were discussed a bit in bevyengine/bevy#86, but since I couldn't find an open issue for the specific problem, I opened bevyengine/bevy#9057 to track it. For now, my workaround in the app is to save the current state in a database, so the app can always go back to where the user left.

There is a follow-up post concentrating on how to get a Bevy application into the app stores

Thank you for reading! If you have any feedback, questions, or comments, you can find me at @nikl.me or on the Bevy Discord server (@nikl).

Dynamic assets

Tue, 01 Mar 2022 00:00:00 GMT

One of my favorite Bevy projects at the moment is the plugin bevy_asset_loader (repository). Its goal is to minimize boilerplate for asset handling while improving code readability and maintainability for games with a lot of assets. I wrote about the motivation and basic idea of the plugin in a previous blog post. Most of the future functionality mentioned in the post is now implemented. The biggest feature added to bevy_asset_loader since then, was not discussed though. That's what this post is all about.

The idea

In the beginning of bevy_asset_loader, all the information needed to load a certain asset was given at compile time. Things like the file path, type information (load it as a standard material plz), or tile sizes for a sprite sheet are passed in derive macro attributes.

#[derive(AssetCollection)]
pub struct TextureAssets {
    #[asset(path = "textures/player.png")]
    pub player: Handle<Image>,
    #[asset(texture_atlas(tile_size_x = 64., tile_size_y = 32., columns = 6, rows = 1))]
    #[asset(path = "textures/dog_sprite_sheet.png")]
    pub dog: Handle<TextureAtlas>,
}

Giving all asset configuration at compile time.

At compile time the derive macro will "hardcode" the file paths and other configuration in the generated code to load the assets. The information directly on the asset collection structs is convenient and reads very well. But there is an issue with this.

If different people (or even different teams) take care of assets and coding, the information seems to be at the wrong place. Tile sizes for a sprite sheet might change with updates on the sprite sheet. Changing this configuration feels like it should happen outside the code. The configuration for an asset should be an asset itself.

Dynamic assets

In some way, configuration and asset handle still need to be connected. I went for the simplest approach and use string keys to connect them. These keys need to be given in our asset collections as derive macro attributes. From now on I will call assets "dynamic" if they have a string key and no other hardcoded asset configuration like a file path.

#[derive(AssetCollection)]
pub struct TextureAssets {
    #[asset(key = "player")]
    pub player: Handle<Image>,
    #[asset(key = "dog")]
    pub dog: Handle<TextureAtlas>,
}

An asset collection with "dynamic assets".

At compile time, the file paths and texture atlas configuration are not known. The code generated by the AssetCollection derive macro uses the string key to grab all asset configuration at run time. bevy_asset_loader stores the key <-> asset configuration mapping in a resource. Users can either manage it manually and configure all used keys before the loading state, or load everything from ron files.

fn setup_system(
    mut asset_keys: ResMut<AssetKeys>,
) {
    asset_keys.register_asset(
        "player",
        DynamicAsset::File {
            path: "textures/player.png".to_owned(),
        },
    );
    asset_keys.register_asset(
        "dog",
        DynamicAsset::TextureAtlas {
            path: "textures/dog_sprite_sheet.png".to_owned(),
            tile_size_x: 64.,
            tile_size_y: 32.,
            columns: 6,
            rows: 1
        },
    );
}

Manually registering the required asset keys to load the TextureAssets asset collection.

Manual registration does not solve the original problem. The asset configuration is still a part of our code. This is why I think the main use case of dynamic assets is the possibility to load key <-> asset configuration mappings from ron files. If you enable the feature dynamic_assets, the following file can be loaded by bevy_asset_loader. All asset keys will be automatically registered before dynamic assets are resolved.

({
    "player": File (
        path: "textures/player.png",
    ),
    "dog": TextureAtlas (
        path: "textures/dog_sprite_sheet.png",
        tile_size_x: 64.,
        tile_size_y: 32.,
        columns: 6,
        rows: 1
    ),
})

File in ron notation containing asset keys and their configurations. By default, the file ending should be .assets.

With such a ron file, all configurations regarding your assets are assets themselves. A little setup is required to tell bevy_asset_loader which ron files should be loaded before which loading state.

fn main() {
    let mut app = App::new();
    app.add_plugins(DefaultPlugins);

    AssetLoader::new(MyStates::AssetLoading)
        .continue_to_state(MyStates::Next)
        .with_asset_collection_file("dynamic_asset_ron.assets")
        .with_collection::<TextureAssets>()
        .build(&mut app);
    app.run();
}

Setup to load asset configurations from a ron file.

That's it. We now moved all asset configuration out of our code.

Supported extras

I showed examples for loading a texture atlas and "simple" files as dynamic assets. You can also load an image directly as a StandardMaterial or load a complete directory as a vector of untyped handles. With dynamic assets it is also possible to have optional fields on asset collections. If the key cannot be resolved at run time, the field will be None.

In some cases, it is required to give more information at compile time than just the key. For example, when loading a directory, the field needs to be additionally annotated with #[asset(folder)]. In the same way, optional fields need #[asset(optional)]. This is a limitation I have not been able to lift, because I need to handle return types that are different from Handle<T> separately at compile time.

Some open issues

There are a few things I am not yet happy with. Admittedly, the API to load .assets files feels a bit clunky. One of the original ideas for this new functionality was that it should be easy to internationalize assets. If you have assets that need to be localized, you could configure them in different ron files and load them according to the user language. Currently, this would require the usage of internal APIs.

I think the biggest missing feature at this point is an ergonomic way to define dependencies between asset collections. It should be possible to load .assets files as part of collections and tell bevy_asset_loader to load and apply certain collections before others.

There is also more design work to be done when thinking about different loading states in a "real" game. There are multiple szenarios in which a game would want to change the loaded assets. For example, localized assets need to be reloaded when the user changes the game language at run time. Even more common: the player might be switching between different levels requiring different asset collections to get loaded and unloaded.

At the moment, all .assets files only get loaded and applied the first time a loading state is entered. If the same key gets overwritten in a later loading state, it's value would be wrong when re-entering the first loading state again.

Thank you for reading! If you have any feedback, questions, or comments, you can find me at @nikl.me or on the Bevy Discord server (@nikl).

Asset handling in Bevy apps

Fri, 06 Aug 2021 00:00:00 GMT

This post outlines the path that led to me writing bevy_asset_loader (repository), a plugin to simplify asset handling in Bevy applications. The later part of the post is about current features of the plugin and thoughts on improvements.

Minimalistic approach

A first usage of assets in your Bevy game might look like this:

fn draw_the_player(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    mut materials: ResMut<Assets<ColorMaterial>>,
) {
    commands.spawn_bundle(SpriteBundle {
        material: materials.add(asset_server.load("player.png").into()),
        ..SpriteBundle::default()
    });
}

A system that loads the player texture where and when it's needed.

Here we are telling the asset server to load "player.png" from our assets directory. The actual loading of the file happens asynchronously. The SpriteBundle will be in the ECS at the end of the current frame, but will not be rendered until the asset finished loading. As soon as the handle has the state LoadState::Loaded, our player texture will show up.

In most games there will be a lot more assets than just one player texture. Probably, we would also have heroic background music, sound effects, and some fancy font to tell a story. If we load all of those assets when we need them, most will start loading in the first frame. Some might be ready after one frame, others will take longer. Imagine our first screen is build from different textures; the screen will render texture for texture over some duration. Not that nice...
Loading handles where and when you need them is fine for small experiments, but most of the time, you want something more elaborate. All required assets should already be finished loading when they are used. Additionally, there should be an easy way to use the same handle at different points in the code.

Preparing all assets in a "loading state"

A common approach is to load all needed assets before starting the game. Most games have some sort of loading screen that gives them time to prepare their assets and indicates progress to the player.
We can use states in Bevy to run a certain set of systems before our actual game logic runs. If we keep the loaded asset handles in resources, systems running during later states can use them through the ECS. The previous example might then look like this:

// the asset is loaded in a previous state and 
// TextureAssets is inserted as a resource
struct TextureAssets {
   player: Handle<ColorMaterial>
}

fn draw_the_player(
    mut commands: Commands,
    texture_assets: Res<TextureAssets>,
) {
    commands.spawn_bundle(SpriteBundle {
        material: texture_assets.player.clone(),
        ..SpriteBundle::default()
    });
}

A system using a resource that contains the needed player material handle.

There are three parts to implementing a "loading state" in Bevy.

Start loading all required assets when entering the state
Check the LoadState of all the assets on update
When the state of all assets is LoadState::Loaded, build resources containing the handles, insert them, and change the state

I will not show all of that code here. In case you want to implement this yourself, you can take a look at the cookbook for an example of checking asset loading state. You can of course also look at the implementation in bevy_asset_loader on GitHub.

In my first few Bevy projects I found myself copying and pasting the "loading state" plugin. Apart from the code duplication between projects, there were also a few other pain points. There was too much boilerplate when adding new resources or adding more handles to existing resources. In both cases the code had to be adjusted in several places.
Another issue I had with my code at that point has to do with readability. When I see a piece of code that uses a handle from a resource, I want to be able to find the corresponding asset file path as fast as possible. With the initial implementation, the asset file paths where defined pretty far away from the resources, and it took multiple jumps in my IDE to get to them. The best case scenario would be to have the paths directly at their corresponding handle fields. This literally screams for some macro magic.

A perfect opportunity to write a Bevy plugin.

Introducing bevy_asset_loader

The idea of bevy_asset_loader is to solve the above mentioned pain points and stop code duplication. There should be minimal boilerplate when adding new resources containing asset handles (from here on called asset collections) or adding new assets to an existing collection. At the same time, the asset path should be close to the resource field containing its handle.
The current implementation of bevy_asset_loader delivers on all these points. An internal plugin that loads three asset collections during the state GameState::Loading looks like this:

pub struct LoadingPlugin;

impl Plugin for LoadingPlugin {
    fn build(&self, app: &mut AppBuilder) {
        AssetLoader::new(GameState::Loading, GameState::Menu)
            .with_collection::<FontAssets>()
            .with_collection::<AudioAssets>()
            .with_collection::<TextureAssets>()
            .build(app);
    }
}

#[derive(AssetCollection)]
pub struct FontAssets {
    #[asset(path = "fonts/FiraSans-Bold.ttf")]
    pub fira_sans: Handle<Font>,
}

#[derive(AssetCollection)]
pub struct AudioAssets {
    #[asset(path = "audio/background.ogg")]
    pub background: Handle<AudioSource>,
    #[asset(path = "audio/lost.ogg")]
    pub lost: Handle<AudioSource>,
}

#[derive(AssetCollection)]
pub struct TextureAssets {
    #[asset(path = "textures/jar.png")]
    pub jar: Handle<Texture>,
    #[asset(path = "textures/shelf.jpg")]
    pub shelf: Handle<Texture>,
}

A Bevy plugin using bevy_asset_loader to load three different asset collections during the state GameState::Loading

All the boilerplate for the "loading state" is gone. Annotations directly at the fields contain the asset paths, keeping the internal name of the asset close to the file name. The derive macro currently works for structs with named fields. The field types need to be handles for assets that can be loaded directly from a file. This requires a one-to-one relationship of files to handles.

For some use cases this is fine, but common assets like TextureAtlas need some extra steps. In Bevy, we can either build an atlas out of many textures (example), or split a sprite sheet (example). In both cases, we can load the initial textures like demonstrated above. The plugin currently cannot create the atlas out of the textures though. It would be nice to be able to use bevy_asset_loader to remove the boilerplate of creating the texture atlas and inserting a resource with the handle.

In the last update, a small feature in this direction was added to bevy_asset_loader. The AssetLoader struct got an init_resource function, that can be used to initialize and insert a resource implementing FromWorld. The only difference of this function to Bevy's AppBuilder::init_resource is the timing of the initialisation. Bevy builds the resource on startup, while the AssetLoader will do it after inserting all our asset collections into the ECS. We can write a FromWorld implementation and retrieve our asset collections in it to, e.g., use the loaded sprite sheet to create a texture atlas.

pub struct LoadingPlugin;

impl Plugin for LoadingPlugin {
    fn build(&self, app: &mut AppBuilder) {
        AssetLoader::new(GameState::Loading, GameState::Menu)
            .with_collection::<RawTextureAssets>()
            .init_resource::<TextureAssets>()
            .build(app);
    }
}

#[derive(AssetCollection)]
pub struct RawTextureAssets {
    #[asset(path = "textures/cauldron.png")]
    pub cauldron_sheet: Handle<Texture>,
}

pub struct TextureAssets {
    pub cauldron: Handle<TextureAtlas>,
}

impl FromWorld for TextureAssets {
    fn from_world(world: &mut World) -> Self {
        let cell = world.cell();
        let raw_textures = cell
            .get_resource::<RawTextureAssets>()
            .expect("RawTextureAssets not loaded");
        let mut texture_atlases = cell
            .get_resource_mut::<Assets<TextureAtlas>>()
            .expect("Could not get TextureAtlas assets");
        TextureAssets {
            cauldron: texture_atlases
              .add(TextureAtlas::from_grid(
                raw_textures.cauldron_sheet.clone(),
                Vec2::new(192., 192.),
                6,
                1,
            )),
        }
    }
}

Implementing FromWorld to create a texture atlas out of a sprite sheet. The asset loader will take care of initialising and inserting the resource.

This removes some boilerplate, but at the same time moves the asset path further away from the atlas handle. I am sure we can do better.

Future improvements

The current state of the plugin already makes it a lot easier to prepare assets in a "loading state". The support for common asset types like TextureAtlas could be improved though. I would like to extend the derive macro for AssetCollection to add more helper annotations. Maybe in the future it will be possible to create asset collections like below.

#[derive(AssetCollection)]
pub struct TextureAssets {
    #[asset(texture_atlas(tile_size_x = 192., tile_size_y = 192., columns = 6, rows = 1))]
    #[asset(path = "textures/sprite_sheet.png")]
    pub sprite: Handle<TextureAtlas>,
}

Maybe in future versions of the library, texture atlases can be created with attributes on a derived AssetCollection (edit: this is possible since version 0.5.0).

I would also like to make it easier for users of bevy_asset_loader to build nice loading screens. There is an open issue on GitHub asking for loading statistics, which should help a lot. The idea would be to offer a resource that keeps track of how many assets are currently loading, how many are done, and how many have not yet started to load. A system running during the "loading state" could then show a progress indicator based on this information.

Thank you for reading! If you have any feedback, questions, or comments, you can find me at @nikl.me or on the Bevy Discord server (@nikl).

Nikl's Blog

Bevy ECS as a data layer for static site generation with Leptos

Static site generation with Leptos

Bevy ECS

What could it look like

What does it look like

Notes on mobile development with Bevy #2

Android

Getting an Android App Bundle

libc++ shared is missing

Include assets

Continuous deployment

Support more Android devices

iOS

Add Icons

Adding a launch screen

Continuous deployment

One issue left...

Getting ready for a release

Getting screenshots

GitHub workflow to publish a Bevy Android app

xbuild setup

The workflow

Setting up the secrets

Final comments

GitHub workflow to publish an iOS app

The Workflow

Setting up the secrets

Final comments

Notes on Android development using Bevy

Shorter feedback cycles

Desktop build

Where to render

Performance

Backward navigation

Moving the app to the background

Dynamic assets

The idea

Dynamic assets

Supported extras

Some open issues

Asset handling in Bevy apps

Minimalistic approach

Preparing all assets in a "loading state"

Introducing bevy_asset_loader

Future improvements