Bevy Cross-Platform Template

A reusable Bevy starter project with first-class Android support. Clone this repo, run the configurator once, and you have a buildable cross-platform app skeleton with AdMob, JNI bridges, lifecycle plumbing, audio, haptics, persistence, and a brand theme already wired in.

Quickstart

git clone <this-template-repo> my-app
cd my-app
cargo run --bin configure --manifest-path tools/configure/Cargo.toml
# Answer the TUI prompts: app name, package ID, AdMob IDs, subsystem toggles.
# The configurator rewrites the project in place and removes itself.

git status                          # review what changed
git add -A && git commit -m "configure: initialise project from template"
rm -rf .git && git init             # optional: start fresh history
cargo build                         # verify
./build.sh                          # build an Android debug APK

Note: The template is intentionally not buildable in its placeholder state. Cargo will reject __APP_CRATE_NAME__ as a name. Run the configurator before any cargo command.

What the template includes

• App shell (crates/core, crates/states, src/lib.rs): minimal Bevy app + AppState (Splash, Home).
• Android plumbing (crates/windowing, crates/insets, crates/lifecycle): window, safe-area insets, onPause/onResume.
• AdMob (crates/ads + Java AdsManager.java): banner / interstitial / rewarded with test-ID fallback.
• JNI bridges: ads, haptics, insets, lifecycle.
• Audio + Haptics (crates/audio, crates/haptics): cross-platform scaffolding.
• Persistence (crates/persistence): SQLite scaffold (db + migration + settings plugin).
• Theme (crates/theme): single brand::ACCENT placeholder + black/cream constants.
• UI primitives (crates/views/widgets): back button, hover shadow, page title, segmented control, etc.
• Layout (crates/layout): breakpoint + orientation helpers.

What the configurator does

A one-shot TUI that prompts for:

• App identity (display name, reverse-DNS package ID, crate name, version).
• AdMob unit IDs + test device IDs (optional; falls back to Google's public test IDs).
• Subsystem toggles (audio, haptics, ads, persistence, theme — each can be ripped out).

Then it rewrites the project (Cargo.toml, AndroidManifest, package paths, etc.), conditionally deletes opted-out subsystems, runs cargo check --workspace, and self-destructs (removes tools/configure/ and template.manifest.toml).

Customising further after configure

The configurator handles the boilerplate. The following are intentional manual edits after configure:

• Brand colors: edit crates/theme/src/palette.rs::brand::*.
• AppState variants: edit crates/states/src/app_state.rs.
• Plugin wiring: edit src/plugins.rs.

Project layout

See the workspace Cargo.toml [workspace] members for the full crate list.

Known workarounds

assets/shaders/post_processing.wgsl

This passthrough fullscreen fragment shader is shipped as a patch for a wgpu bug that causes UI flicker on a subset of mobile CPU/GPU architectures. Inserting a no-op post-processing pass forces an extra resolve and side-steps the flicker. The underlying bug is fixed in wgpu 28+, so Bevy 0.19+ should not need this workaround — once you bump to that version, the shader (and any wiring you added for it) can be deleted.

Troubleshooting

Android build fails: assets folder missing

The Android Gradle build relies on a symlink at platform/android/app/src/main/assets pointing at the workspace assets/ directory. Git on Windows often clones this as a plain text file containing the link target, which breaks the build.

Re-create the symlink:

• POSIX (Linux/macOS): scripts/fix-asset-symlinks.sh
• Windows (PowerShell): scripts/fix-asset-symlinks.ps1 (requires Developer Mode or Administrator)