5.6 KiB

Raw Blame History

Bevy UI Example - ECS-Based Game Interfaces

Production-ready Bevy UI 0.15+ patterns for ECS-based game user interfaces.

Last Updated: 2026-03-14 Bevy Version: 0.15+ Rust Version: 1.85+ (2021 edition)

Purpose

This example demonstrates building production-ready game UIs using Bevy UI 0.15+ with ECS (Entity-Component-System) architecture. Patterns include:

ECS UI State Management - Component-based UI state, system-driven updates
Zero-Copy UI State Transfer - Direct memory transfer, no serialization overhead
Accessibility Patterns - ARIA-like ECS components, focus management systems
Systemic Consistency - ECS validation rules, state machine consistency
Game Design Integration - Player HUD, inventory UI, dialogue systems

2026 Best Practices

Bevy UI 0.15+ Architecture Patterns

Pattern	Use Case	Implementation
UI Camera	Dedicated UI rendering	`Camera2dBundle::ui()`
UI State Component	State storage	`#[derive(Component)]`
State System	State transitions	`fn ui_state_system()`
Event-driven UI	Reactive updates	`Events::<UiEvent>::send()`
Zero-Copy Transfer	High-performance	`bytemuck` derive, direct memory

ECS UI State Management

// ECS UI state component pattern
#[derive(Component, Clone, Debug)]
struct UiState {
    focus: Option<Entity>,
    active_panel: PanelType,
    theme: UiTheme,
    accessibility: AccessibilityConfig,
}

// System-driven state updates
fn update_ui_state(
    mut ui_state: ResMut<UiState>,
    input: Res<InputMap>,
    mut commands: Commands,
) {
    if input.pressed("Tab") {
        ui_state.focus = ui_state.next_focus();
    }
}

Zero-Copy Transfer Patterns

Pattern	Use Case	Implementation
Bytemuck Derive	Safe zero-copy	`#[derive(Bytemuck)]`
Pod Trait	Plain old data	`unsafe impl Pod`
Zeroable Trait	Zero initialization	`unsafe impl Zeroable`
Direct Slice	Batch transfers	`&[T]` without allocation
GPU Upload	Texture/buffer	`encoder.write_buffer()`

Requirement	ECS Pattern	WCAG Level
Focus Tracking	`FocusComponent` on entities	AA
ARIA Labels	`LabelComponent` with text	A
Keyboard Nav	InputMap system bindings	A
High Contrast	`ThemeComponent` variants	AA
Screen Reader	Text-to-speech events	AA

Systemic Consistency Rulesets

ECS UI CONSISTENCY RULES:

1. **STATE MACHINE VALIDATION**
   - UI state transitions validated by systems
   - Invalid transitions logged + rejected
   - State machine type-checked at compile time

2. **COMPONENT BOUNDARIES**
   - UI components separate from game components
   - No direct mutation across boundaries
   - Systems enforce separation

3. **EVENTUAL CONSistency**
   - UI events queued via Events<T>
   - Systems process in deterministic order
   - Conflicts resolved by system priority

4. **ZERO-COPY GUARANTEES**
   - All UI state derives Bytemuck
   - No allocation during transfer
   - GPU upload via direct memory

Running the Example

cd examples/rust/bevy-ui-example
cargo init
cargo add bevy@0.15
cargo add bytemuck
cargo run

File Structure

File	Purpose	Key Patterns
`main.rs`	Bevy app setup, UI systems	UI camera, state systems
`ecs-ui-state.rs`	ECS UI state management	Components, systems, events
`zero-copy-transfer.rs`	Zero-copy UI transfer	Bytemuck, Pod, Zeroable

Architecture

+------------------+     +------------------+     +------------------+
|   Bevy App       |     |   ECS Systems    |     |   GPU Renderer   |
|   (UI Camera)    |     |   (State Logic)  |     |   (wgpu)         |
+------------------+     +------------------+     +------------------+
        |                        |                        |
        | UI Components          |                        |
        |-----------------------|                        |
        |                        |                        |
        | State Systems         | Validate state         |
        |-----------------------|------------------------|
        |                        |                        |
        | Zero-Copy Transfer    | Direct memory          |
        |-----------------------|------------------------|
        |                        |                        |
        |                       | GPU Upload             |
        |                       |------------------------|
        |                       |                        |
        |                       | Render                 |
        |                       |------------------------|

Guardrails Compliance

Rule	Implementation
PRODUCTION FIRST	ECS systems before UI tests
COMPONENT BOUNDARIES	UI/game separation enforced
ACCESSIBILITY	Focus, labels, keyboard nav
ZERO-COPY	No allocation during transfer
STATE VALIDATION	All transitions type-checked

AGENT_GUARDRAILS.md - Core safety protocols
TEST_PRODUCTION_SEPARATION.md - Separation standards
WEB_UI_IMPLEMENTATION.md - Web UI patterns

Authored by: Claude Code (Anthropic) Document Owner: Project Maintainers Review Cycle: Monthly

5.6 KiB Raw Blame History