bevyengine/bevy

bevy_winit

The OS-specific window and event-loop backend. Wraps winit and bridges it into Bevy's ECS.

Purpose

bevy_winit is what makes Bevy show a window. Its responsibilities:

Run the OS event loop on the main thread.
Translate winit::Event into Bevy events (WindowResized, KeyboardInput, MouseButtonInput, CursorMoved, …).
Create / destroy actual OS windows when ECS Window entities are spawned / despawned.
Apply ECS-side property changes (resize, cursor, fullscreen) to the OS handle.
Handle accessibility tree updates via bevy_a11y.
Provide the App::run() runner — when WinitPlugin is added, the runner becomes winit::EventLoop::run.

Directory layout

crates/bevy_winit/src/
├── lib.rs                    # WinitPlugin
├── system.rs                 # Per-frame ECS-side systems
├── state.rs                  # Event-loop state machine
├── converters.rs             # winit::* → bevy_input::* event mapping
├── winit_windows.rs          # OS window registry
├── accessibility.rs          # AccessKit bridge
├── custom_cursor.rs, cursor.rs
├── android.rs                # Android-specific logic
└── …

Key abstractions

Type	File	Description
`WinitPlugin`	`crates/bevy_winit/src/lib.rs`	Adds the runner and the bridge systems.
`WinitWindows`	`crates/bevy_winit/src/winit_windows.rs`	Map: `Entity → winit::Window`.
`WinitSettings`	`crates/bevy_winit/src/lib.rs`	Update mode (continuous / desktop-app / reactive).
`EventLoopProxyWrapper`	`crates/bevy_winit/src/lib.rs`	Wakeup channel to bring the event loop out of waiting.

How it works

sequenceDiagram
    participant OS
    participant Loop as winit::EventLoop
    participant Conv as Converter
    participant ECS as Bevy World
    participant Run as Runner

    OS->>Loop: keyboard / mouse / resize
    Loop->>Conv: winit::Event
    Conv->>ECS: send Bevy events / mutate Window
    Run->>ECS: run Main schedule once
    ECS-->>Loop: yield until next event

WinitPlugin sets the App runner to one that drives winit::EventLoop::run_app. Each iteration:

Pull pending winit events, translate, dispatch.
If WinitSettings::update_mode says "run a frame," call world.run_schedule(Main).
Either request a redraw (continuous mode) or wait for the next OS event (reactive / desktop-app modes).

The reactive modes are what allow Bevy to be used for desktop apps that don't need to redraw constantly — they let the OS schedule wake-ups instead of busy-looping.

Integration points

Depends on: winit, accesskit_winit (for a11y), bevy_app, bevy_window, bevy_input, bevy_a11y, bevy_math, bevy_image (for cursor images), bevy_render (for raw window handles → swapchain).
Depended on by: bevy_internal (default plugins).

Entry points for modification

New input event mapping: converters.rs.
Multi-window changes: winit_windows.rs + the spawn/despawn systems in system.rs.
Update-mode tweaks: state.rs.
Platform-specific behavior: android.rs, plus the per-platform winit features.