NEOLearn

Windows

Configure the game's window, switch between windowed and fullscreen, control the cursor and vsync, save power, react to window messages, open more windows and take screenshots.

Updated October 20, 2026

On this page

A window is an entity with a Window component. WindowPlugin, part of DefaultPlugins, spawns the first one, the primary window, and marks it with PrimaryWindow. You configure it up front through the plugin, and change it while the game runs by editing the component.

Configure the primary window#

Rust
use neo::{prelude::*, window::PresentMode};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins.set(WindowPlugin {
            primary_window: Some(Window {
                title: "Space Race".into(),
                resolution: (1280, 720).into(),
                present_mode: PresentMode::AutoVsync,
                resizable: true,
                ..default()
            }),
            ..default()
        }))
        .run();
}
FieldWhat it does
titleThe title bar text.
resolutionThe size, as a WindowResolution. Read width(), height() (logical pixels), physical_width(), physical_height() and scale_factor(); change it with set(w, h).
modeWindowMode::Windowed, BorderlessFullscreen(monitor) or Fullscreen(monitor, video_mode).
positionWindowPosition::Automatic, Centered(monitor) or At(IVec2).
present_modeHow frames reach the screen; see below.
resizable, decorations, transparent, enabled_buttonsWhether it can be resized, has a title bar and borders, is see-through, and which title bar buttons work.
window_levelNormal, AlwaysOnTop or AlwaysOnBottom.
window_themeSome(WindowTheme::Dark) or Light, where the system supports it.
visibleStart hidden and show it once the first frames are ready, to avoid a white flash.
resize_constraintsMinimum and maximum size.
canvas, fit_canvas_to_parent, prevent_default_event_handlingIn a browser: which canvas to draw into, whether it fills its parent, and whether the game keeps keys such as Space and F1 from the page.

WindowPlugin also has exit_condition (OnAllClosed, the default; OnPrimaryClosed; or DontExit) and close_when_requested, which closes a window when its close button is pressed.

Example: cargo run --example window_settings.

Change the window while running#

Query the Window component and edit it. Single is handy when there's one window:

Rust
use neo::window::{MonitorSelection, WindowMode};

fn toggle_fullscreen(keys: Res<ButtonInput<KeyCode>>, mut window: Single<&mut Window>) {
    if keys.just_pressed(KeyCode::F11) {
        window.mode = match window.mode {
            WindowMode::Windowed => WindowMode::BorderlessFullscreen(MonitorSelection::Current),
            _ => WindowMode::Windowed,
        };
    }
}

With more than one window, filter for the main one with Single<&mut Window, With<PrimaryWindow>>.

Present mode and vsync#

PresentModeWhat it does
AutoVsync (default)Waits for the display's refresh, using the best mode the system has. No tearing.
AutoNoVsyncDoesn't wait, using the best mode the system has. Lowest latency; can tear.
Fifo, FifoRelaxed, Immediate, MailboxRequest a specific mode. Not every platform has every mode.

Turn vsync off while measuring performance, so the frame time shows the real cost.

The cursor#

The cursor's behaviour is a separate CursorOptions component on the window entity:

Rust
use neo::window::{CursorGrabMode, CursorOptions};

fn capture_mouse(mouse: Res<ButtonInput<MouseButton>>, mut cursor: Single<&mut CursorOptions>) {
    if mouse.just_pressed(MouseButton::Left) {
        cursor.visible = false;
        cursor.grab_mode = CursorGrabMode::Locked;
    }
}
CursorGrabModeWhat it does
NoneThe cursor moves freely.
ConfinedThe cursor can't leave the window.
LockedThe cursor stays in place; read mouse motion instead. For first-person and orbit cameras.

Not every platform has every mode: macOS has no Confined (it falls back to None), X11 has no Locked (it falls back to Confined), and browsers only lock the pointer after a click. Phones and tablets have no cursor. The cursor's look is a CursorIcon component: a SystemCursorIcon such as Pointer or Text, or a custom image (the custom_cursor feature, on in NEO's builds). Examples: cargo run --example window_settings, custom_cursor_image.

Power saving#

How often the app updates is set by the WinitSettings resource, separately for when the window has focus and when it doesn't. The default is WinitSettings::game().

Rust
use neo::winit::WinitSettings;

app.insert_resource(WinitSettings::desktop_app());
SettingBehaviour
WinitSettings::game() (default)Updates continuously while focused, and about 60 times a second in the background.
WinitSettings::desktop_app()Updates on input and other window events, or after 5 seconds without any; in the background, after a minute. For tools and menus.
WinitSettings::mobile()Updates on events or 60 times a second while focused, once a second in the background.
WinitSettings::continuous()Updates as fast as possible, focused or not.
WinitSettings { focused_mode, unfocused_mode }Your own: UpdateMode::Continuous or UpdateMode::reactive(wait) / reactive_low_power(wait).

In a reactive mode, write a RequestRedraw message to draw a frame when something changes without input. Example: cargo run --example low_power.

Window messages#

Read these with MessageReader:

MessageSent when
WindowResizedThe window changed size (window, width, height).
WindowFocusedThe window gained or lost focus.
WindowCloseRequestedThe user asked to close the window.
WindowMoved, WindowScaleFactorChanged, WindowOccludedIt moved, changed DPI, or was hidden behind others.
CursorMoved, CursorEntered, CursorLeftThe cursor moved over, entered or left the window.
FileDragAndDropA file was dropped on (or hovered over) the window. Desktop only.
AppLifecycleThe app is suspended or resumed, on phones.
Rust
use neo::window::WindowResized;

fn on_resize(mut resized: MessageReader<WindowResized>) {
    for e in resized.read() {
        info!("window is now {} x {}", e.width, e.height);
    }
}

Examples: cargo run --example window_resizing, drag_and_drop.

More windows#

Spawn another Window entity, and point a camera at it with RenderTarget::Window:

Rust
use neo::{camera::RenderTarget, window::WindowRef};

let second = commands.spawn(Window { title: "Map".into(), ..default() }).id();
commands.spawn((
    Camera3d::default(),
    Transform::from_xyz(0.0, 20.0, 0.0).looking_at(Vec3::ZERO, Vec3::Z),
    RenderTarget::Window(WindowRef::Entity(second)),
));

Despawn the entity to close the window. Several windows are desktop only. Example: cargo run --example multiple_windows.

Screenshots#

Spawn a Screenshot and observe it to save the image:

Rust
use neo::render::view::screenshot::{save_to_disk, Screenshot};

fn screenshot(mut commands: Commands, keys: Res<ButtonInput<KeyCode>>) {
    if keys.just_pressed(KeyCode::F12) {
        commands.spawn(Screenshot::primary_window()).observe(save_to_disk("screenshot.png"));
    }
}

Example: cargo run --example screenshot.

Next steps#