ποΈ Bevy Shell - Template
An opinionated, monolithic template for Bevy with cross-platform CI/CD, native + WASM + mobile launchers, and managed cross-platform deployment.
![](https://user-images.githubusercontent.com/20546772/184515793-9f7dea0d-ff21-45ba-9869-49804094e237.png)
β¨ Features
- Single, monolithic repository for a cross-platform Bevy App
- Automated CI on pushes and merge requests to
main
- Cross-platform delivery of your Bevy app through GitHub releases
- Windows, Linux, MacOS, Web (Demo), iOS, Android (TODO: PRs accepted!)
- Options to deploy Web to DockerHub (self-host) or GitHub Pages (free)
- Settings for automated dependency management through Renovate
- Best practices in GitOps and IaC
β Quickstart
- Use or Fork this template
- Setup RenovateBot with permissions to your repository to automatically detect dependency updates
- Setup your WASM build with one of:
- GitHub Pages (I'm new to hosting, no equipment)
- Docker (I know what I'm doing)
- Optional: Modify your Bevy App, which is self-contained in
src/
- You can preview your WASM version with
trunk serve
(Trunk required) - You can preview the Native version with
cargo run
- You can preview your WASM version with
- Cut a release to cross-deploy your game across WASM, Windows, Mac, and Linux
ππ» Information
Below is detailed information for the features of this template
π¦ Multi-platform CI/CD
This template uses GitOps to deploy a multi-platform release. GitHub Actions powers testing pipelines and release deployment to ensure a solid foundation for production release infrastructure.
Automated testing
Pushing to the main branch automatically triggers CI pipelines:
- Unit Testing
- Build - Ubuntu
- Build - Windows
- Build - MacOS
- Build - iOS
- TODO: Build - Android
- Build - WebAssembly
πΈ You can ensure all pull requests must pass CI testing before merging through GitHub's branch protection rules.
Automated dependency management
Renovate is a free open source bot on GitHub for your repositories to automatically create pull requests for dependency updates on your projects. This template's Renovate settings file allows for automatic merging of minor and patch updates, if all CI tests pass. You can change these settings yourself.
πΈ More information is available at renovatebot.com
Release cutting
Creating a release on your template will trigger the release pipeline, which packages download bundles for all major platforms, including mobile and web. The pipeline will create a branch gh-pages
with the WASM bundle to serve by GitHub Pages (demo), or DockerHub image (example), depending on the hosting strategy you choose to setup.
π₯ WARNING: We enforce releases are tagged with a semantic version name, e.g. "v0.1.0", not "v1" This can be modified on the
release-*
workflow files.
π‘ Web Hosting
There are two ways to host the WASM build of your Bevy game, with Docker or GitHub Pages. You could be creative to adapt this to other hosting platforms, but we will only explain these two. You would likely choose one, not both. If you don't have hosting equipment or know what you're doing, choose GitHub Pages.
GitHub Pages
To automatically serve your WASM bundle like our demo, here are the steps:
-
Modify the GitHub Pages GitHub Action file's variarable
PUBLIC_URL
with the slug for your GitHub Pages hosting.- If the repo name is the same as the repo owner, this should be
/
, otherwise, it will should be/<repository-name>/
(e.g./bevy-shell-template/
)
- If the repo name is the same as the repo owner, this should be
-
Optional: Delete the DockerHub GitHub Action, as you probably don't need it.
-
Cut a release and wait for pipeline completion
-
On your GitHub template repo, visit Settings > Pages
-
Select
gh-pages
branch from the dropdown menu and press "Save".
Docker
To serve your WASM bundle with Docker, here are the steps:
- Signup to DockerHub
- Navigate to your project Settings > Secrets > Actions
- Create two repository GitHub Action secrets:
DOCKERHUB_USERNAME
Your DockerHub username (e.g. simbleau)DOCKERHUB_TOKEN
A DockerHub access token with write privileges
- Modify the DockerHub GitHub Action file's variable
RELEASE_NAME
with your desired image name (e.g.my_game
) - Optional: Delete the GitHub Pages GitHub Action, as you probably don't need it.
- Cut a release and wait for pipeline completion
- On your server hardware with Docker installed, run
docker run -p 80:80 <DOCKERHUB_USERNAME>/<RELEASE_NAME>:latest
, which should pull from DockerHub automatically. - Your WASM build should be served via
http://localhost:80
, wherelocalhost
is your server's address
πΈ The Dockerfile
uses NGINX, and uses Docker.nginx.conf
for configuration.
π Launchers
WASM (Web)
To build and run the WASM app locally we recommend Trunk:
Serve with
trunk serve
and openhttp://127.0.0.1:8080
in your browser
- Assets are streamed through the hosting provider, so that the initial WASM bundle is smaller.
- We use all the WASM optimizations discussed described here in the Rust and WebAssembly book.
- There is an initial loading screen provided through Yew while the WASM bundle loads.
Native (Windows, MacOS, Linux)
Run with
cargo run
- Assets are bundled with the release when cut.
- There is no loading screen.
Native (iOS, Android)
TODO: Android is not yet supported
Run with
launchers/ios/run-ios-sim.sh
- Assets are bundled with the release when cut.
- There is no loading screen.