165 lines
3.6 KiB
Markdown
165 lines
3.6 KiB
Markdown
# 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):
|
|
|
|
```bash
|
|
nix develop
|
|
cargo run
|
|
```
|
|
|
|
Optional host-native path:
|
|
|
|
```bash
|
|
# install rust + tooling yourself, then run
|
|
cargo run
|
|
```
|
|
|
|
Run prerequisites checker:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
xcode-select --install
|
|
```
|
|
|
|
## Fast Iteration Workflows
|
|
|
|
Native commands:
|
|
|
|
```bash
|
|
cargo run
|
|
cargo watch -x run
|
|
cargo fmt --all
|
|
cargo check
|
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
|
```
|
|
|
|
Nix-wrapped equivalents:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
Cmd/Ctrl+Shift+P -> "Tasks: Run Task"
|
|
```
|
|
|
|
## AI Workflows
|
|
|
|
Build/update project context:
|
|
|
|
```bash
|
|
just context
|
|
# or
|
|
./ai/scripts/build-context.sh
|
|
```
|
|
|
|
Run local llama flows:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
cargo check
|
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
|
```
|
|
|
|
For runtime smoke checks:
|
|
|
|
```bash
|
|
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.
|