Manual
Manual
Keyboard, mouse and gamepads
Most of a game reads input actions, which work the same from every device. This page covers what is underneath: reading keys and mouse buttons directly, the order keys went down in, typed text, files dropped on the window, the cursor locked and hidden, gamepads, how keys are named whatever the keyboard's layout, and writing devices into a test.
Read keys and the mouse directly
world.ReadInput() gives everything the engine knows of the keyboard and the mouse this frame as one snapshot, an InputState. Read it once a frame and ask it as much as you like: it costs one call into the engine however many questions follow.
InputState input = world.ReadInput();
if (input.IsDown(Key.W)) { /* ... */ }if (input.AllDown(Key.ControlLeft, Key.S)) { /* ... */ }if (input.WasPressed(Key.Escape)) { /* ... */ }
if (input.MousePressed.HasFlag(MouseButtons.Left) && world.Input.Pointer is Vector2 pointer){ Pick(pointer);}| Member | What it says |
|---|---|
IsDown(key), WasPressed(key), WasReleased(key) | A key is down; went down this frame; came up this frame |
AllDown(keys) | Every key of a combination is down. An empty one is down. |
MouseHeld, MousePressed, MouseReleased | The mouse buttons down, gone down this frame, come up this frame, as MouseButtons flags: Left, Right, Middle, Back and Forward |
CursorInWindow, CursorX, CursorY | Whether the cursor is in the window, and where, in logical pixels from its top left |
MotionX, MotionY | How far the mouse moved this frame |
ScrollX, ScrollY, ScrollUnit | How far the wheel turned this frame, and in what |
HasWindow | Whether there is a window. Without one every field is zero. |
Reading it twice in a frame gives the same answer. A system reads input through actions, context.Input; to read the snapshot from a system, register an InputState resource of your own and copy the snapshot into it once a frame, and the system takes it as Res<InputState> (see Resources).
Four things worth knowing:
- The cursor is the window's. While the game plays in the editor, that is the editor's window, not the Game panel's picture. For the point over the game, which a camera's
ScreenRaytakes, readworld.Input.Pointer(see Input actions). - Mouse motion is not the change in the cursor's position. Motion keeps coming while the cursor is locked, or has run off the edge of the screen, which is what a camera turned by the mouse wants. Its Y is down positive, as the screen's is; an action's is up positive.
- Scroll comes in lines or pixels. A mouse's wheel reports lines and a trackpad pixels, and
ScrollUnitsays which. Treat them alike, and the game scrolls imperceptibly on one and far too fast on the other. - About a hundred keys are named. Media keys, international keys and F13 up are not reported, as if the keyboard had none.
Keys in the order they went down
The snapshot says which keys moved during a frame, not in what order. A shortcut typed fast, Ctrl+A and at once a capital X, moves Ctrl, A and Shift in one frame, and the snapshot reads it as Ctrl+Shift+A. world.ReadKeys() gives every key that went down or came up since it was last called, in order, each a KeyEvent with its Key and whether it went Down:
foreach (KeyEvent pressed in world.ReadKeys()){ if (pressed.Down && pressed.Key == Key.Enter) { /* ... */ }}Each event is given once; a key held down is not repeated. What it returns is good until the next call, so copy what you keep.
Typed text
Typing is not a set of keys down: it has an order, it repeats, and a dead key or an input method makes a character with no key of its own. world.ReadText() gives what was typed since it was last called, as Unicode code points in order. Each character comes once, so read it once a frame and pass it on.
Enter, Tab and Backspace are not in it; read them as keys, since they move a caret and delete rather than insert. Neither is a letter typed with Ctrl or the Super key held, which is a shortcut, while one typed with Ctrl and Alt together, which is AltGr on many keyboards, is text.
A text field in a UI document reads typing for you.
Files dropped on the window
world.ReadFileDrops() lists the files dragged over the game's window or dropped on it since it was last called, each a FileDrop: its Kind, Hovered as it comes over, Dropped as it is let go of, or Canceled as the drag goes away, and its Path as the platform names it.
Keys are places on the keyboard
A Key names a place on the keyboard, not the letter printed there: Key.W is the key where W sits on a US keyboard, whatever layout the player types with. On a French keyboard it is the key printed Z. So W A S D movement sits in the same place on every keyboard, and a game's controls work the same on a Russian layout as on an English one.
The names follow the US layout too: Key.Semicolon is the key right of L. What a key types depends on the layout, so read typed text, not keys, for anything a player writes. A prompt, input.Prompt, names a key by its US name, W or Left Shift, whatever the layout.
| Keys | Names |
|---|---|
| Letters and digits | A to Z, Digit0 to Digit9 |
| Function keys | F1 to F12 |
| Arrows | ArrowLeft, ArrowRight, ArrowUp, ArrowDown |
| Modifiers | ShiftLeft, ShiftRight, ControlLeft, ControlRight, AltLeft, AltRight, SuperLeft, SuperRight |
| Editing | Space, Enter, Escape, Tab, Backspace, Delete, Insert, Home, End, PageUp, PageDown |
| Punctuation | Minus, Equal, BracketLeft, BracketRight, Backslash, Semicolon, Quote, Comma, Period, Slash, Backquote |
| Keypad | Numpad0 to Numpad9, NumpadAdd, NumpadSubtract, NumpadMultiply, NumpadDivide, NumpadDecimal, NumpadEnter |
| Others | CapsLock, NumLock, ScrollLock, PrintScreen, Pause |
The cursor
world.Cursor holds the cursor still and hides it, for a camera turned by the mouse:
world.Cursor.Lock(); // held where it is, from the next frame; the mouse's motion still comesworld.Cursor.Hide(); // hidden over the game
world.Cursor.Unlock();world.Cursor.Show();
bool held = world.Cursor.IsLocked;A game on its own holds and hides the cursor on its window. In the editor, the cursor is held in the Game panel while the panel has focus, and hidden while it is over the game's picture. Escape lets it go, and a click into the Game panel's picture takes it again. Each Play starts with the cursor free and shown.
Gamepads
Gamepads are read through actions: bind an action to a pad's buttons or sticks, in the Input page or in code, and ask the action. Every pad connected drives player 0. Pads are read through Bevy's bevy_gilrs.
A pad's buttons are named for where they sit, since that is what every pad has alike:
GamepadButton | Xbox | PlayStation | Nintendo |
|---|---|---|---|
South | A | Cross | B |
East | B | Circle | A |
West | X | Square | Y |
North | Y | Triangle | X |
LeftShoulder, RightShoulder | LB, RB | L1, R1 | L, R |
LeftTrigger, RightTrigger | LT, RT | L2, R2 | ZL, ZR |
Select, Start | View, Menu | Create, Options | −, + |
LeftStickPress, RightStickPress | LS, RS | L3, R3 | Left Stick Press, Right Stick Press |
DPadUp, DPadDown, DPadLeft, DPadRight | D-Pad Up, and so on |
The triggers are buttons, from zero to one, held past halfway. A stick's directions are GamepadAxis values, LeftStickX, LeftStickY, RightStickX and RightStickY, from −1 to 1 with up and right positive; a whole stick is a GamepadStick, Left, Right, or DPad, the pad's four arrows as a stick.
Which pad a player holds is known by its maker: input.LastDevice.Gamepad is Xbox, PlayStation, Nintendo or Other, and input.Prompt names its buttons as they are printed on it (see Prompts). There is no rumble yet, and no touch.
In the editor
While the game plays in the editor, its actions read the keyboard and the mouse only while the Game panel has focus, and gamepads whatever has focus (see In the editor).
ReadInput, ReadKeys and ReadText are not held back that way. In the editor they read the keyboard whatever panel has focus, and the cursor in the pixels of the editor's own window, not the Game panel's picture. A game that should behave in the editor as it will once built reads its actions.
Testing input
A test writes devices into a world as they would write themselves, read on the next frame:
world.SimulateKey(Key.Space, down: true);world.SimulateMouseButton(MouseButtons.Left, down: true);world.SimulateMouseMotion(12f, -4f); // pixels, down positive as the screen's areworld.SimulateScroll(0f, 1f); // lines
SimulatedGamepad pad = world.SimulateGamepad(vendor: 0x054C); // a pad by Sonypad.Press(GamepadButton.South);pad.Press(GamepadButton.RightTrigger, 0.4f); // part waypad.Move(GamepadAxis.LeftStickX, 1f);pad.Release(GamepadButton.South);pad.Disconnect();These work in a world with no window too. To press a UI element, see Test a game's interface.
In the Scripting API
- InputState: the keyboard and the mouse this frame.
- Key, MouseButtons and ScrollUnit: what the snapshot names.
- KeyEvent and FileDrop: keys in order, and files dropped.
- GameCursor: the cursor locked and hidden.
- GamepadButton, GamepadAxis, GamepadStick and GamepadKind: a pad's buttons and sticks, and its maker.
- SimulatedGamepad: a pad that is not there, for a test.
- World:
ReadInput,ReadKeys,ReadText,Cursorand theSimulatemethods.
