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.
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#
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();
}| Field | What it does |
|---|---|
title | The title bar text. |
resolution | The size, as a WindowResolution. Read width(), height() (logical pixels), physical_width(), physical_height() and scale_factor(); change it with set(w, h). |
mode | WindowMode::Windowed, BorderlessFullscreen(monitor) or Fullscreen(monitor, video_mode). |
position | WindowPosition::Automatic, Centered(monitor) or At(IVec2). |
present_mode | How frames reach the screen; see below. |
resizable, decorations, transparent, enabled_buttons | Whether it can be resized, has a title bar and borders, is see-through, and which title bar buttons work. |
window_level | Normal, AlwaysOnTop or AlwaysOnBottom. |
window_theme | Some(WindowTheme::Dark) or Light, where the system supports it. |
visible | Start hidden and show it once the first frames are ready, to avoid a white flash. |
resize_constraints | Minimum and maximum size. |
canvas, fit_canvas_to_parent, prevent_default_event_handling | In 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:
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#
PresentMode | What it does |
|---|---|
AutoVsync (default) | Waits for the display's refresh, using the best mode the system has. No tearing. |
AutoNoVsync | Doesn't wait, using the best mode the system has. Lowest latency; can tear. |
Fifo, FifoRelaxed, Immediate, Mailbox | Request 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:
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;
}
}CursorGrabMode | What it does |
|---|---|
None | The cursor moves freely. |
Confined | The cursor can't leave the window. |
Locked | The 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().
use neo::winit::WinitSettings;
app.insert_resource(WinitSettings::desktop_app());| Setting | Behaviour |
|---|---|
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:
| Message | Sent when |
|---|---|
WindowResized | The window changed size (window, width, height). |
WindowFocused | The window gained or lost focus. |
WindowCloseRequested | The user asked to close the window. |
WindowMoved, WindowScaleFactorChanged, WindowOccluded | It moved, changed DPI, or was hidden behind others. |
CursorMoved, CursorEntered, CursorLeft | The cursor moved over, entered or left the window. |
FileDragAndDrop | A file was dropped on (or hovered over) the window. Desktop only. |
AppLifecycle | The app is suspended or resumed, on phones. |
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:
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:
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.