bevy-template/CLAUDE.md

Bevy Nix Template - Detailed Dev Guide

This is the canonical deep guide for newcomers and AI agents working in this repo.

Project Snapshot

• Purpose: minimal Bevy template for fast workshop iteration with optional local AI workflows.
• Stack:
  • Rust 1.95.0 target (via flake.nix dev shell)
  • Bevy 0.18.1
  • 2D-first project scope
• Current app behavior (src/main.rs):
  • starts Bevy app with a titled 1280x720 window
  • spawns a single Camera2d

Canonical File Map

Authoritative files:

• AGENTS.md: coding and architecture rules for this template.
• Cargo.toml: Rust package and Bevy dependency configuration.
• flake.nix: reproducible Nix development environment.
• justfile: daily dev commands.
• .opencode/opencode.json: OpenCode command templates and permissions.
• ai/scripts/*.sh: local context and llama automation scripts.
• docs/ai/*.md: Bevy design and debugging references.
• src/main.rs: current game entrypoint.

Generated files:

• ai/context/project-context.md: generated by just context or ./ai/scripts/build-context.sh.
  • Do not hand-edit this file.
  • Regenerate when source/docs change and before context-heavy AI prompts.

Setup Paths

Recommended path (reproducible):

nix develop
cargo run

Optional host-native path:

# install rust + tooling yourself, then run
cargo run

Run prerequisites checker:

bash ./scripts/check-requirements.sh --mode native
bash ./scripts/check-requirements.sh --mode nix-host
nix develop -c bash ./scripts/check-requirements.sh --mode nix-shell

On macOS, install Xcode Command Line Tools if missing:

xcode-select --install

Fast Iteration Workflows

Native commands:

cargo run
cargo watch -x run
cargo fmt --all
cargo check
cargo clippy --workspace --all-targets --all-features -- -D warnings

Nix-wrapped equivalents:

nix develop -c cargo run
nix develop -c cargo watch -x run
nix develop -c cargo fmt --all
nix develop -c cargo check
nix develop -c cargo clippy --workspace --all-targets --all-features -- -D warnings

Just shortcuts:

just run
just watch
just check
just lint
just test

VS Code Tasks

Tasks are defined in .vscode/tasks.json and cover:

• requirements checks (native and nix)
• build check (native and nix)
• lint pipeline (fmt -> check -> clippy, native and nix)
• dev run/watch (native and nix)
• release run with --no-default-features (native and nix)

Use:

Cmd/Ctrl+Shift+P -> "Tasks: Run Task"

AI Workflows

Build/update project context:

just context
# or
./ai/scripts/build-context.sh

Run local llama flows:

export LLAMA_MODEL=/absolute/path/to/model.gguf
just ai-chat
just ai-plan "add player movement"
just ai-fix "camera jitters on move"
just ai-review "review ECS plugin split"

OpenCode config:

• Canonical config: .opencode/opencode.json
• It expects ai/context/project-context.md to exist or be refreshed.

Verification Workflow

After Rust code edits, run in this order:

cargo fmt --all
cargo check
cargo clippy --workspace --all-targets --all-features -- -D warnings

For runtime smoke checks:

cargo run
cargo watch -x run

Troubleshooting

• Could not resolve host: index.crates.io:
  • network access is required for first dependency download.
• xcode-select errors on macOS:
  • install CLT with xcode-select --install.
• llama-cli: command not found:
  • install llama.cpp tooling or skip local llama commands.
• missing ai/context/project-context.md:
  • run just context before prompts that read project context.