# Workspace guide

## Workspace
- Rust workspace uses the nightly toolchain (`rust-toolchain`), edition 2024, resolver 2.
- Members: `crates/renderer`, `crates/renderer/renderer_macros`, `crates/renderer_device`, `crates/renderer_resources`, `crates/window`, `crates/game`, `crates/text`, and `crates/bevy_vulkan_render`.
- Dependency direction for Vulkan rendering: `bevy_vulkan_render` → `renderer` → `renderer_resources` → `renderer_device`. `renderer_macros` supplies `DeviceRef` derives to `renderer` and is a dev-dependency for `renderer_device` tests.
- `renderer` re-exports device, instance, queue, and sync modules and many root device types. Prefer its paths for downstream rendering code; its resource-module aliases remain crate-private.
- `crates/renderer/renderer_macros` is the proc-macro crate used by `renderer` for `DeviceRef` derives.
- `crates/renderer_device` owns Vulkan instance/device setup, queues, sync primitives, and handle lifetimes.
- `crates/renderer_resources` owns public buffer, image, view, descriptor, sampler, shader-module, and pipeline resource APIs on `renderer_device`.
- `crates/renderer` owns rendering orchestration, commands, swapchains, and render graph APIs; resource module aliases are internal, not `renderer` public modules.
- `crates/bevy_vulkan_render` integrates the renderer with Bevy. `crates/window`, `crates/game`, and `crates/text` are separate workspace crates.
- The workspace root package is `vidya`; it also contains examples and depends on `bevy_vulkan_render`.
- `renderer_resources` depends on `renderer_device`, not `renderer`; do not introduce a dependency cycle.
- `renderer` uses `renderer_device` for device/instance ownership and accesses resource modules through crate-private aliases.
- `renderer_macros` is nested under the renderer package directory but is a distinct workspace package.

## Layout
- Workspace and shared dependency versions: root `Cargo.toml`.
- Per-crate manifests live beside crate source under `crates/`.
- Rendering shaders and assets are under `crates/renderer/shaders` and `assets/`.
- Root-level demos and examples are under `examples/`; add shared dependencies under `[workspace.dependencies]` where appropriate.
- The workspace uses Rust 2024 syntax; `renderer` and `renderer_device` use nightly features. `renderer_resources` has no crate-level nightly feature attributes.

## Conventions
- Keep changes local to the owning crate; preserve the device/rendering layer boundary.
- Follow existing Rust style and use the workspace dependency declarations in the root manifest when applicable.
- Keep the device/resource/rendering dependency boundaries described above; use `renderer`'s re-exported API in Bevy integration where possible.
- Do not commit changes; the user owns commits.
- Read the crate-level instructions before changing rendering/device/resource boundaries:
  - [`crates/renderer_device/AGENTS.md`](crates/renderer_device/AGENTS.md)
  - [`crates/renderer_resources/AGENTS.md`](crates/renderer_resources/AGENTS.md)
  - [`crates/renderer/AGENTS.md`](crates/renderer/AGENTS.md)

## Verification
- `cargo check --workspace` checks all workspace crates.
- `cargo test -p renderer_device` runs the device-layer tests.
- Rendering code uses nightly features; use the pinned workspace toolchain for all Cargo commands.
- Run Cargo commands from the workspace root to use the pinned toolchain and shared workspace configuration.
- Use crate-scoped `cargo check -p <crate>` or `cargo test -p <crate>` for focused checks, then workspace check for cross-crate API changes.
- Review `git status` and `git diff` before reporting changes; preserve unrelated user modifications.