bevyengine / bevy_github_ci_template

Bevy GitHub CI Template

This repo show how to set up CI on a GitHub project for Bevy.

It creates two workflows:

• CI
• Release

CI

Definition: .github/workflows/ci.yaml

This workflow runs on every commit to main branch, and on every PR targeting the main branch.

It will use rust stable on linux, with cache between different executions, those commands:

• cargo test
• cargo clippy -- -D warnings
• cargo fmt --all -- --check

If you are using anything OS specific or rust nightly, you should update the file ci.yaml to use those.

Release

Definition: .github/workflows/release.yaml

This workflow runs on every tag.

It will build:

• For Linux and Windows, a .zip archive containing the executable and the assets.
• For macOS, a dmg image with a .app containing the assets.
• For wasm, a .zip archive with the wasm binary, the js bindings, an html file loading it, and the assets.

If you don't want to target some of those platforms, you can remove the corresponding job from the file release.yaml.

If you don't want to attach the builds to the GitHub release, set env.add_binaries_to_github_release to false.

If you are using Git LFS, set env.use_git_lfs to true so your assets are properly checked out.

Warning

GitHub's LFS storage has a quota. Please take a look at GitHub's documentation here to understand the quota and costs before enabling this option.

Git Tag from GitHub UI

You can follow Managing releases in a repository

Git Tag from the CLI

Execute the following commands:

git tag -a "my-game-1.0" -m "First official release"
git push --tags

Result

A new release will be available in GitHub, with the archives per platform available as downloadable assets.

The git commands above produced this release: my-game-1.0.

Using the workflows in your own project

If you would like to use the GitHub workflows included here for your own project, there are a few things you might have to adapt:

1. The release workflow relies on the index.html file under /wasm for web builds
2. Make sure that the env variable binary (release.yaml) matches the name of your binary
3. Adapt the used toolchain if you are using nightly
4. In your GitHub repo's settings, under Actions -> General make sure "Read and Write permissions" is selected under "Workflow permissions" near the bottom. This fixes the error Error: Resource not accessible by integration.

Publish on itch.io

The release flow can be configured to push the releases to itch.io:

1. Create an API key in https://itch.io/user/settings/api-keys
2. Go to the repository's Settings tab in GitHub, click on Secrets->Actions in the sidebar,and add a repository secret named BUTLER_CREDENTIALS set to the API key.
3. Uncomment env.itch_target in release.yaml and set it to the itch.io username and the name of the game on itch.io, separated by a slash (/)

Once that is done, any tag pushed to GitHub will trigger an itch.io release and use the tag as the user version.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE-2.0 or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
• CC0-1.0 License (LICENSE-CC0-1.0 or https://creativecommons.org/publicdomain/zero/1.0/legalcode)

at your option.

The Ducky sprite is CC-0 licensed by Caz Creates Games.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be triple licensed as above, without any additional terms or conditions.

bevy_github_ci_template's Issues

Include workaround for AudioContext requiring interaction

Should the template include this workaround for AudioContexts?

https://developer.chrome.com/blog/web-audio-autoplay/#moving-forward

I think itch.io does something for this already, but it's fixes some issues with sounds not playing when running on other web pages.

Add notifications to GitHub channel on Discord

Also consider giving Francois ownership rights over this repo.

Add a CSS background / spinner on web for before the game has loaded

Example implementation here: https://github.com/benfrankel/bevy_jam_template/tree/main/web.

For licensing reasons, the CSS background / spinner should probably be custom-made.

Show how users can organize their code into plugins

This might be a major bikeshed.

Over the years, I've experimented with many styles of organizing Bevy games, and I've landed at the following convention:

// main.rs

mod physics;
mod level;
mod camera;

fn main() {
    App::new().add_plugins((
        DefaultPlugins,
        physics::plugin,
        level::plugin,
        camera::plugin,
}

// camera.rs, level.rs, physics.rs

pub(super) fn plugin(app: &mut App) {
    app.add_systems(...);
}

Any of these plugins can (and probably will) have sub-plugins. I usually have about one plugin per file, which works out pretty well when using this terse plugin-function-syntax above. Please see the conversation here for a writeup I did about why I prefer to organize games this way.

This is the style used in Foxtrot, parts of Blenvy, and the unofficial best practices

This stuff is certainly opinionated, but I think we have to recognize the following things:

• The template will be organized somehow
• Users will generate a lot of nested modules while coding a game
• Users will implicitly accept the organization presented in the template as a good starting point and try to follow it
• The organization used for the empty template, which will only contain a few modules, will be stretched to serve users that have dozens upon dozens of modules

This means that we should take care to make the organization presented here conductive to development.

Update template to Bevy 0.10

Should be straightforward, but we should make this work with the latest Bevy release.

macOS builds are broken

Migrate off of actions-rs in build system

See bevyengine/bevy#6432

Make this Repo a Template

Can you please enable the setting "Template Repository" for this Repo? This will allow others to use this as a template and not have to fork this, which will inevitably clutter the forks with random bevy projects.

Thanks.

Clarify itch.io release workflow in README

I think a new section ### Publish on GitHub release could be nice and mirror the new ### Publish on itch.io
(and would be easy to expand if we add more targets later, an easy one would be a publish to GitHub page with a custom html and/or the wasm version for example)

Originally posted by @mockersf in #13 (comment)

Move lint config from top of `main.rs` to `Cargo.toml`

https://github.com/bevyengine/bevy_github_ci_template/blob/main/src/main.rs#L1-L5

These can go in a [lints] table in Cargo.toml now.

Disable console on windows for release builds

See https://github.com/janhohenheim/foxtrot/blob/274563b701a4d2002ff4d585d02d54f56a7704e5/src/main.rs#L1 for an example of this.

Disable trace logging for better performance

See bevyengine/bevy-website#1503

Wasm build not working on itch in bevy 0.12.x

I am trying to put a wasm build on itch but it just doesn't work. I cloned this repo and put it on itch to see why wasm isn't building. Turns out that it is working for bevy 0.11.0, but not for 0.12.x. I can't believe that this isn't a known issue, but I also have no clue what I could be doing wrong.

I am getting the following error when trying to run the 0.12.x version in the web on itch, which I don't get in the 0.11.0 build.

WARN /home/runner/.cargo/registry/src/index.crates.io-6f17d22bba15001f/bevy_pbr-0.12.1/src/ssao/mod.rs:87 ScreenSpaceAmbientOcclusionPlugin not loaded. GPU lacks support: TextureFormat::R16Float does not support TextureUsages::STORAGE_BINDING.

GET https://html-classic.itch.zone/html/9288970-880838/assets/ducky.png.meta 403 (Forbidden)
Failed to load resource: the server responded with a status of 403 ()

ERROR /home/runner/.cargo/registry/src/index.crates.io-6f17d22bba15001f/bevy_asset-0.12.1/src/server/mod.rs:300 encountered an io error while loading asset: Encountered unexpected HTTP status 403

Full Console Log

bundle.min.js?1702356362:1 Already declared, using existing: Lightbox
window.R.window.R @ bundle.min.js?1702356362:1
bundle.min.js?1702356362:1 Already declared, using existing: ErrorLightbox
window.R.window.R @ bundle.min.js?1702356362:1
bundle.min.js?1702356362:1 Already declared, using existing: Lightbox
window.R.window.R @ bundle.min.js?1702356362:1
bundle.min.js?1702356362:1 Already declared, using existing: ErrorLightbox
window.R.window.R @ bundle.min.js?1702356362:1
bundle.min.js?1702356362:1 Already declared, using existing: SlideDown
window.R.window.R @ bundle.min.js?1702356362:1
bundle.min.js?1702356362:1 Already declared, using existing: CSRF
window.R.window.R @ bundle.min.js?1702356362:1
bundle.min.js?1702356362:1 Already declared, using existing: InputRow
window.R.window.R @ bundle.min.js?1702356362:1
bundle.min.js?1702356362:1 Already declared, using existing: TextInputRow
window.R.window.R @ bundle.min.js?1702356362:1
bundle.min.js?1702356362:1 Already declared, using existing: SimpleSelect
window.R.window.R @ bundle.min.js?1702356362:1
bundle.min.js?1702356362:1 Already declared, using existing: Select
window.R.window.R @ bundle.min.js?1702356362:1
bundle.min.js?1702356362:1 Already declared, using existing: RadioButtons
window.R.window.R @ bundle.min.js?1702356362:1
bundle.min.js?1702356362:1 Already declared, using existing: FormErrors
window.R.window.R @ bundle.min.js?1702356362:1
bundle.min.js?1702356362:1 Already declared, using existing: RecaptchaInput
window.R.window.R @ bundle.min.js?1702356362:1
lib.min.js?1702356362:2 Unrecognized feature: 'monetization'.
xe @ lib.min.js?1702356362:2
lib.min.js?1702356362:2 Unrecognized feature: 'xr'.
xe @ lib.min.js?1702356362:2
lib.min.js?1702356362:2 Allow attribute will take precedence over 'allowfullscreen'.
xe @ lib.min.js?1702356362:2
bevy_game.js:376 INFO /home/runner/.cargo/registry/src/index.crates.io-6f17d22bba15001f/bevy_winit-0.12.1/src/system.rs:55 Creating new window "App" (0v0)
bevy_game.js:376 INFO /home/runner/.cargo/registry/src/index.crates.io-6f17d22bba15001f/bevy_render-0.12.1/src/renderer/mod.rs:140 AdapterInfo { name: "ANGLE (NVIDIA Corporation, NVIDIA GeForce GTX 960/PCIe/SSE2, OpenGL 4.5.0)", vendor: 4318, device: 0, device_type: Other, driver: "", driver_info: "", backend: Gl }
bevy_game.js:376 WARN /home/runner/.cargo/registry/src/index.crates.io-6f17d22bba15001f/bevy_pbr-0.12.1/src/ssao/mod.rs:87 ScreenSpaceAmbientOcclusionPlugin not loaded. GPU lacks support: TextureFormat::R16Float does not support TextureUsages::STORAGE_BINDING.
bevy_game.js:922 
        
        
       GET https://html-classic.itch.zone/html/9288970-880838/assets/ducky.png.meta 403 (Forbidden)
imports.wbg.__wbg_fetch_1f9eb1a6c5433fb7 @ bevy_game.js:922
$web_sys::features::gen_Window::Window::fetch_with_str::h0fe830307752bd93 @ bevy_game_bg.wasm:0x1654cd4
$bevy_asset::io::wasm::HttpWasmAssetReader::fetch_bytes::{{closure}}::ha40d39234762fcd4 @ bevy_game_bg.wasm:0xba28d1
$<bevy_asset::io::wasm::HttpWasmAssetReader as bevy_asset::io::AssetReader>::read_meta::{{closure}}::h2b75dee213d66c97 @ bevy_game_bg.wasm:0x11d5698
$bevy_asset::io::AssetReader::read_meta_bytes::{{closure}}::h656947f40c991694 @ bevy_game_bg.wasm:0xed999d
$bevy_asset::server::AssetServer::load_internal::{{closure}}::hf2e538ed883c8c87 @ bevy_game_bg.wasm:0x1284be
$bevy_tasks::single_threaded_task_pool::TaskPool::spawn::{{closure}}::h61be2353f29577b0 @ bevy_game_bg.wasm:0x556610
$wasm_bindgen_futures::queue::Queue::new::{{closure}}::h3de27792acef8a83 @ bevy_game_bg.wasm:0x1025ef6
$wasm_bindgen::convert::closures::invoke1_mut::h767562161e2892f8 @ bevy_game_bg.wasm:0x15eece5
__wbg_adapter_60 @ bevy_game.js:234
real @ bevy_game.js:203
bevy_game.js:376 ERROR /home/runner/.cargo/registry/src/index.crates.io-6f17d22bba15001f/bevy_asset-0.12.1/src/server/mod.rs:300 encountered an io error while loading asset: Encountered unexpected HTTP status 403

EDIT: It works on my web server, so it's likely an issue with the files/assets location on itch (perhaps with the relative/absolute paths). Note that I still get the errors that meta files are missing, but the game still seems to work as expected.

Github Actions: "Error: Resource not accessible by integration"

When testing using this template for the Bevy 0.10 upgrade (see #25) I ran into an error with the Github actions:
Resource not accessible by integration
You can see the attempt here.

To fix this I had to go to my repo's settings -> actions -> general and enable read and write permissions for the workflows near the bottom of the page, then re-running the actions worked perfectly

I think we'll probably want to add something to the README about this? It wasn't obvious what the solution was and took some searching and ended up guessing on where to look for something to enable write permissions.

Bevy Logo License issue

The addition of the CC0 license in #42 implies that the bevy logo is CC0, but it is not.
From @cart:

I retain all rights to the logo atm. The license section explicitly calls out that the code is dual licensed under mit/apache.

https://discord.com/channels/691052431525675048/745355529777315850/995411630563262519

I think either the logo or the CC0 license needs to be removed from the template.

I would prefer the CC0 license removed personally as I think it creates a high possibility that people using this template will either include assets that are somewhat permissively licensed, but not CC0 and forget to remove the license, or they don't intend for their personal assets to be licensed this way.

Setup a basic `SystemSet` enum for the game

Same rationale as #62

Remove GitHub token from Clippy workflow job

This GitHub token reference seems unnecessary:

bevy_github_ci_template/.github/workflows/ci.yaml

Line 73 in 3e0784a

token: ${{ secrets.GITHUB_TOKEN }}

Update template to Bevy 0.14

Release action failing at Step "Prepare Package" for Windows, Linux and MacOs

Hello :)

I'm experiencing some issues with the Release action.
I removed the WASM export and kept the itch.io export disabled.
the other three, windows, linux and macos, work fine until they get to the "Prepare Package" step. There all of them are failing.

I'm using bevy 0.9.1 right now. Everything has been directly copied from this template, the only two things i changed were

• removing wasm
• edited the binary env to my binary name.

The CI from this template works without issues.

Images below with the errors.

Local web development option.

It would be great to have some instructions or scripts or something for users to easily do local testing/development for the web.

There are a bunch of ways to break a web build and the feedback loop could be substantially shortened.

Use hack to not get flickering at the start of the game

https://github.com/janhohenheim/foxtrot/blob/main/src/bevy_config.rs#L51-L60

Large canvas not downsized properly when running wasm build in mobile on itch.io

I'm having trouble with the canvas overflowing when using this template targeting mobile devices and publishing on itch.io.

I'm quite sure the change in this PR #44 previously fixed the issue and properly resized the canvas to fit smaller screens, by adding the css

 <style>
    html, body {margin:0;height:100%;}
  </style>

and configuring the window plugin to use fit_canvas_to_parent: true.

But something has changed 🤔 and this does not seem to help anymore as a canvas/window with dimensions larger then the target device will overflow and only show a cropped center part of the canvas/window content, when running on mobile on itch.io.

Anyone having the same issue (with itch.io in particular) and have found a workaround / fix?

Use app bundles when building for macos

I think there may be some reason this isn't desirable alluded to here: #13 (comment)

But I've been experimenting with this here, and it seems to generally work.

From what I can see the advantages are:

• Works better with the itch app. Unlike with a .dmg where pressing "launch" just opens up a folder containing the binary.

And the disadvantages:

• Chrome warns you about the file being unusual when downloading

In both cases, actually running the unsigned app (outside of the itch scenario) seems to require the same amount of effort.

Licensing

Shouldn't the template be licensed in a way that allows the user to start from this code and later publish it under any license they want?

The current license is copy-paste from the engine repository. It points to dual MIT/Apache 2 with two dead links.

Add credits menu

Everyone in the team behind a jam entry should have an easy way to add their name into the game for proper credit.

Add `.vscode/tasks.json` for easy integration with VS Code

Example: https://github.com/benfrankel/bevy_jam_template/blob/main/.vscode/tasks.json

Unlicense alternative license?

Maybe we could use The Unlicense so that way anyone can use this template freely

Setup a basic `State` enum for the game

Same rationale as #62

#61 is a good candidate for GameState::Boot.

Perhaps support cargo-generate

Perhaps this repo should support cargo-generate, which allows git repositories to be used as a template to bootstrap the repository. This would mean that certain things (such as the project name) could be filled in automatically, and also allows things like a window to be added by default, which has the project's name. This is something I do in my personal template repository.

Furthermore, if cargo generate is used, this also means that the repository can be used as a Project Template by RustRover, which would be nice.

How to protect Assets

Sorry if this isn't the best place for this. I want to discuss protecting the assets created along with the release build.

Right now, the release template bundles your assets folder and an executable of your game. All your game assets are just sitting there, available to anyone who downloaded your game.

I am currently making a game to be a commercial product in the future. I am worried about the assets being stolen.

What is a good way to protect my assets, at least legally? Is there a license or read me I can include in the assets folder to notify end-users that those assets are copyrighted and not permitted for reuse?

Update the licenses like bevy repo did

I'm basing my jam game off of this and wanted to include licenses.
I noticed that bevy repo updated their format (file per license), while this repo uses the old one (short file with external links).

Wasm Loading Bar

Port over loading bar that is used on https://bevyengine.org/examples/.