Skip to content
Skills Library
Programming · Building & coding

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.

Licence
Apache-2.0
Last repository change
17.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 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

  1. Product Context
  2. Architectural Law (Never Violate)
  3. Bevy 0.19 API Rules
  4. New Component Checklist
  5. Command Pattern
  6. Performance Rules
  7. Rust Gotchas (Learned from Production)
  8. Validation Tools
  9. Quality Bar
Original SKILL.md headings · 144 lines, 888 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.