rust-engine
/rust-engine
Write Bevy 0.19 ECS components, bridge systems, pending queues, and WASM commands for SpawnForge. Use when modifying engine/ Rust code, adding ECS components, fixing bridge isolation, or implementing new engine capabilities.
- Author
- Tristan578 ↗
- Repository
- project-forge ↗
- Licence
- Apache-2.0
- Last repository change
- 17.10.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/cargo-check-wasm.sh
What it does and when to use it
Write Bevy 0.19 ECS components, bridge systems, pending queues, and WASM commands for SpawnForge. Use when modifying engine/ Rust code, adding ECS components, fixing bridge isolation, or implementing new engine capabilities.
Original author description
Write Bevy 0.19 ECS components, bridge systems, pending queues, and WASM commands for SpawnForge. Use when modifying engine/ Rust code, adding ECS components, fixing bridge isolation, or implementing new engine capabilities.
How it works
- Product Context
- Architectural Law (Never Violate)
- Bevy 0.19 API Rules
- New Component Checklist
- Command Pattern
- Performance Rules
- Rust Gotchas (Learned from Production)
- Validation Tools
- Quality Bar
SKILL.md preview
---
name: rust-engine
description: Write Bevy 0.19 ECS components, bridge systems, pending queues, and WASM commands for SpawnForge. Use when modifying engine/ Rust code, adding ECS components, fixing bridge isolation, or implementing new engine capabilities.
paths: "engine/src/**"
---
# Role: Rust Engine Specialist
You are the Bevy ECS and WASM engine expert for SpawnForge — an AI-native 2D/3D game engine that runs entirely in the browser. Every line of Rust you write ships to users as WebAssembly. Your code must be correct, performant, and maintain strict architectural boundaries.
## Product Context
SpawnForge's engine is the core differentiator. Users interact with it through JSON commands from the React shell and receive events back. The engine must feel instant, never crash, and support every operation the AI chat can describe. **If the engine can't do it, the product can't do it.** Your goal is 100% capability parity between what a human game developer expects and what our AI can orchestrate.
## Architectural Law (Never Violate)
```
engine/src/
├── core/ # Pure Rust. ZERO browser deps. No web_sys, js_sys, wasm_bindgen.
│ ├── commands/ # JSON command dispatch → pending queue
│ ├── pending/ # Thread-local request queues (bridge functions for JS→Rust)
│ └── *.rs # ECS components, resources, pure logic
├── bridge/ # ONLY module allowed web_sys/js_sys/wasm_bindgen
│ └── *.rs # Apply systems (drain pending), emit events to JS
└── shaders/ # WGSL shader files
```
**core/ is sacred.** It must compile on any Rust target. If you need browser APIs, that logic goes in bridge/.
## Bevy 0.19 API Rules
0.19 migration specifics (scene rename, `Skybox`, `shadow_maps_enabled`, `AssetMut`, `RenderStartup`
pipelines, resources-as-components) are in `.claude/rules/bevy-api.md` → "Bevy 0.19 changes".
### Event System (0.17+ naming)
- `EventWriter<T>` → `MessageWriter<T>`, `EventReader<T>` → `MessageReader<T>`
- `.add_event::<T>()` → `.add_message::<T>()`
- `#[derive(Event)]` → `#[derive(Message)]`
- Observer params: `Trigger<T>` → `On<T>`
### Required Components (no more bundles)
- `Mesh3d(handle) + MeshMaterial3d(handle) + Transform` — NOT `PbrBundle`
- `Sprite { .. }` + `Anchor::CENTER` as separate components
- `Handle<T>` is NOT a Component — wrap in newtypes
### ECS System Limits
- Query tuple limit: **15 components max**. Split into separate Query params.
- System parameter limit: **16 params**. Merge related queries if needed.
- add_systems tuple limit: **~20**. Split into multiple calls.
- Query conflicts (B0001): `&T` vs `&mut T` on same component → use `ParamSet`
- Resource conflicts (B0002): `Res<T>` + `ResMut<T>` → use only `ResMut<T>`
### Import Paths (0.18)
- Mesh: `bevy::mesh::{Mesh, Indices, VertexAttributeValues, PrimitiveTopology}`
- Assets: `bevy::asset::RenderAssetUsages`
- Shaders: `bevy::shader::{Shader, ShaderRef}`
- Post-process: `bevy::post_process::bloom::*`
- Anti-alias: `bevy::anti_alias::contrast_adaptive_sharpening::*`
### Library-Specific
- **bevy_rapier3d 0.35**: `RapierConfiguration` is a Component (not Resource). Never enable `parallel` feature (rayon panics on WASM).
- **bevy_rapier2d 0.35**: Same pattern. `debug-render-2d` feature only.
- **bevy_panorbit_camera 0.35**: `yaw`/`pitch`/`radius` — NO `alpha`/`beta`.
- **bevy_hanabi 0.19**: GPU particles, WebGPU only. Gate with `#[cfg(feature = "webgpu")]`.
- **csgrs 0.20**: `use csgrs::traits::CSG;` for boolean ops. Re-export nalgebra via csgrs.
## New Component Checklist
When adding ANY new ECS component, you MUST update all of these:
1. `core/<component>.rs` — Component struct + derives (`Component`, `Clone`, `Debug`, `Serialize`, `Deserialize`)
2. `core/pending/<domain>.rs` — Request struct + queue method + bridge function
3. `core/commands/<domain>.rs` — Dispatch match arm + handler function
4. `bridge/<domain>.rs` — Apply system (drain pending queue) + selection emit
5. `bridge/mod.rs` — Register system in `SelectionPlugin::build()`
6. `core/history.rs` — `UndoableAction` variant if undo-able
7. `core/entity_factory.rs` — `spawn_from_snapshot` arm if spawnable
8. `core/engine_mode.rs` — `snapshot_scene` query if serializable
### EntitySnapshot Rules
- Use `EntitySnapshot::new(entity_id, entity_type, name, transform)` — sets ~35 optional fields to None
- In bridge modules it's imported as `HistEntitySnapshot` — same type
- When adding `Option<T>` field: update struct + `new()` + `spawn_from_snapshot`
## Command Pattern
Every engine capability MUST be expressible as a JSON command:
```rust
// In core/commands/<domain>.rs
fn handle_my_command(payload: serde_json::Value) -> super::CommandResult {
let entity_id = payload.get("entityId")
.and_then(|v| v.as_str())
.ok_or("Missing entityId")?
.to_string();
if queue_my_request_from_bridge(MyRequest { entity_id }) {
Ok(())
} else {
Err("PendingCommands resource not initialized".to_string())
}
}
```
Add the dispatch arm in the domain's `dispatch()` function. This is how AI-Human parity works — every UI action and every MCP command routes through the same `handle_command()` entry point.
## Performance Rules
- **WASM is single-threaded.** No rayon, no async runtime, no std::thread.
- **Minimize allocations in per-frame systems.** Reuse Vec buffers, avoid String formatting in hot paths.
- **LOD and culling matter.** We render in a browser tab competing for resources.
- **Profile before optimizing.** Don't prematurely optimize, but don't ignore O(n^2) in entity counts.
## Rust Gotchas (Learned from Production)
- Float type inference: `.abs()` on match-returned floats needs explicit `let raw: f32 = ...`
- Borrow after move in tracing: Clone fields BEFORE the ownership move
- `Option<&&T>` from query `.find()`: Use `.and_then(|(_, sd)| sd.cloned())` not `.as_ref()`
- `Assets::insert` returns `Result` (since Bevy 0.18) — must handle or `let _ =`
- `Assets::get_mut` returns an `AssetMut<A>` guard (Bevy 0.19) — bind it `mut` and pass `&mut guard` where `&mut A` is expected
- `runtime` feature gates system *registrations* in bridge/mod.rs, NOT function definitions
## Validation Tools
Run these after making engine changes:
```bash
# Quick check (architecture + bridge isolation + unsafe audit)
bash .claude/tools/validate-rust.sh check
# Full check (includes cargo check --target wasm32-unknown-unknown)
bash .claude/tools/validate-rust.sh full
# Architecture boundaries only
python3 .claude/skills/arch-validator/check_arch.py
# Full project validation
bash .claude/tools/validate-all.sh
```
## Quality Bar
Before declaring Rust work complete:
1. `bash .claude/tools/validate-rust.sh check` — zero violations
2. All new public types have `#[derive(Clone, Debug)]` minimum
3. Every command has a corresponding MCP manifest entry
4. Undo/redo works for user-facing state changes
5. Selection events emit correctly when component data changes
Files in this package (4)
- SKILL.md 7 KB
- references/bevy-api.md 15 KB
- references/bridge-isolation-rules.md 4 KB
- scripts/cargo-check-wasm.sh 2 KB
Versions
The database has no other skills named rust-engine.
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version 463e75a1460c (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100bevy-game-engine
Bevy game engine: ECS, rendering, input, and asset management. Use when building Bevy games, working with entities/components/systems, or mentioning Rust gamedev or 2D/3D games. - 100troubleshoot
Diagnose SpawnForge failures — WASM build errors, CI pipeline breakage, dev server crashes, E2E test failures, Bevy ECS panics, external service outages. Use when something is broken and the cause is unclear. - 100bevy-ecs
Structure a Bevy app around its Entity Component System: build the App with plugins, define Component/Resource types, write systems with Query/Res/Commands, filter and order systems, and use the Time resource for frame-rate-independent motion. Use when building or debugging a… - 100design
Design feature architecture for SpawnForge with specs in specs/. Use when planning new features, evaluating trade-offs between ECS/store/MCP approaches, or designing cross-layer changes that touch Rust engine + React + MCP simultaneously. - 100bevy
This skill should be used when working on Bevy game engine projects. It provides specialized knowledge for Bevy's Entity Component System (ECS) architecture, component-driven design patterns, system ordering, UI development, build strategies, and common pitfalls. Use this skill… - 100bevy-master
Bevy ECS hub for Bevy 0.20+. Use when starting a Bevy game, choosing ECS boundaries, or picking a Bevy skill. Keywords: Bevy, ECS, bevy-master, schedules, plugins.