A Bevy game template

Template for a Game using the awesome Bevy engine featuring out of the box builds for Windows, Linux, macOS, Web (Wasm), Android, and iOS.

What does this template give you?

• small example "game"
• easy setup for running the web build using trunk (trunk serve)
• run the native version with cargo run
• workflow for GitHub actions creating releases for Windows, Linux, macOS, and Web (Wasm) ready for distribution
  • the same workflow creates development builds for the mobile platforms (two separate workflows can push to the stores after some setup)
  • push a tag in the form of v[0-9]+.[0-9]+.[0-9]+* (e.g. v1.1.42) to trigger the flow
• CI workflow that checks your application on all native platforms on every push

WARNING: if you work in a private repository, please be aware that macOS and Windows runners cost more build minutes. For public repositories the workflow runners are free!

How to use this template?

1. Click "Use this template" on the repository's page
2. Look for ToDo to use your own game name everywhere
3. Update the icons as described below
4. Start coding 🎉
   • Start the native app: cargo run
   • Start the web build: trunk serve
     • requires trunk: cargo install --locked trunk
     • requires wasm32-unknown-unknown target: rustup target add wasm32-unknown-unknown
     • this will serve your app on 8080 and automatically rebuild + reload it after code changes
   • Start the android app: cargo apk run -p mobile
     • requires following the instructions in the bevy example readme for android setup
   • Start the iOS app (see the bevy example readme for ios setup instructions)
     • Install Xcode through the app store
     • Launch Xcode and install the iOS simulator (check the box upon first start, or install it through Preferences > Platforms later)
     • Install the iOS and iOS simulator Rust targets with rustup target add aarch64-apple-ios x86_64-apple-ios aarch64-apple-ios-sim
     • run make run inside the /mobile directory

You should keep the credits directory up to date. The release workflow automatically includes the directory in every build.

Updating the icons

1. Replace build/macos/icon_1024x1024.png with a 1024 times 1024 pixel png icon and run create_icns.sh or create_icns_linux.sh if you use linux (make sure to run the script inside the build/macos directory) - Note: create_icns.sh requires a mac, and create_icns_linux.sh requires imagemagick and png2icns
2. Replace build/windows/icon.ico (used for windows executable and as favicon for the web-builds)
   • You can create an .ico file for windows by following these steps:
     1. Open macos/AppIcon.iconset/icon_256x256.png in Gimp
     2. Select the File > Export As menu item.
     3. Change the file extension to .ico (or click Select File Type (By Extension) and select Microsoft Windows Icon)
     4. Save as build/windows/icon.ico
3. Replace build/android/res/mipmap-mdpi/icon.png with macos/AppIcon.iconset/icon_256x256.png, but rename it to icon.png

Deploy web build to GitHub pages

1. Trigger the deploy-github-page workflow
2. Activate GitHub pages for your repository
   1. Source from the gh-pages branch (created by the just executed action)
3. After a few minutes your game is live at http://username.github.io/repository

To deploy newer versions, just run the deploy-github-page workflow again.

Deploy mobile platforms

For general info on mobile support, you can take a look at one of my blog posts about mobile development with Bevy which is relevant to the current setup.

Android

Currently, cargo-apk is used to run the development app. But APKs can no longer be published in the store and cargo-apk cannot produce the required AAB. This is why there is setup for two android related tools. In mobile/Cargo.toml, the package.metadata.android section configures cargo-apk while mobile/manifest.yaml configures a custom fork of xbuild which is used in the release-android-google-play workflow to create an AAB.

There is a post about how to set up the android release workflow on my blog.

iOS

The setup is pretty much what Bevy does for the mobile example.

There is a post about how to set up the iOS release workflow on my blog.

Removing mobile platforms

If you don't want to target Android or iOS, you can just delete the /mobile, /build/android, and /build/ios directories. Then delete the [workspace] section from Cargo.toml.

Development environments

Nix Support

nixgl is only used on non-NixOS Linux systems; when running there we need to use the --impure flag:

nix develop --impure

If using nixgl, then .e.g. gl cargo run, other use cargo as usual.

Getting started with Bevy

You should check out the Bevy website for links to resources and the Bevy Cheat Book for a bunch of helpful documentation and examples. I can also recommend the official Bevy Discord server for keeping up to date with the development and getting help from other Bevy users.

Known issues

Audio in web-builds can have issues in some browsers. This seems to be a general performance issue and not due to the audio itself (see bevy_kira_audio/#9).

License

This project is licensed under CC0 1.0 Universal except some content of assets and the Bevy icons in the build directory (see Credits). Go crazy and feel free to show me whatever you build with this (@nikl_me / @nikl_me@mastodon.online ).