Input

Input reads the keyboard and mouse.

function Update()
    if Input.GetKeyDown(Key.E) then Debug.Print("E was pressed") end
end

Keys come from the Key table: Key.E, Key.Space, Key.LShift. Input is checked once per frame, so read it in Update, not in FixedUpdate (which may run zero or several times in a frame and miss or repeat a press).

---

Keyboard

Function	Returns
GetKeyDown(key)	boolean	true only on the frame the key was pressed.
GetKey(key)	boolean	true every frame while the key is held.
GetKeyUp(key)	boolean	true only on the frame the key was released.
GetDoubleKey(key, keyTwo)	boolean	true while both keys are held.
GetDoubleKeyDown(key, keyTwo)	boolean	true on the frame both keys become held: either one was just pressed while the other is down. Good for shortcuts like Key.LCtrl, Key.S.
GetKeyName(key)	string	The key's name in the Key table: "E" for Key.E, "Space" for Key.Space. Good for on-screen prompts like [E] Open.
GetAnyKey()	Key or nil	A held key.
GetAnyKeyDown()	Key or nil	A key pressed this frame.
GetAnyKeyUp()	Key or nil	A key released this frame.

Keys

Every key is a value in the global Key table. The script editor and VS Code suggest them as you type Key..

Group	Values
Letters	Key.A to Key.Z
Number row	Key.Alpha0 to Key.Alpha9 (the row above the letters, not the numpad)
Special	Key.Space, Key.Escape, Key.Enter, Key.Tab, Key.Backspace
Arrows	Key.Left, Key.Right, Key.Up, Key.Down
Modifiers	Key.LShift, Key.RShift, Key.LCtrl, Key.RCtrl, Key.LAlt, Key.RAlt

The values are plain numbers, so you can keep one in a variable or compare two with ==.

A misspelled key (Key.Spcae) is nil, and passing nil or a number that isn't a key raises an error naming the problem.

Keys are physical positions on a US layout. On other layouts Key.Z is the key where Z is on a US keyboard, which keeps WASD-style controls in the same place.

The GetAnyKey functions

They return nil when no key qualifies. Keys without a value in the Key table, like F1, are ignored. If several keys qualify, they return the one that comes first: letters, then the number row, then the rest. They are best for "press any key to continue" and for simple key rebinding.

-- Wait for a key, then remember it as the "use" key.
local useKey = Key.E
local listening = false

function Update()
    if listening then
        local key = Input.GetAnyKeyDown()
        if key ~= nil then
            useKey = key
            listening = false
        end
    elseif Input.GetKeyDown(useKey) then
        Debug.Print("Use!")
    end
end

---

Mouse

Name	Returns
GetMouseButtonDown(button)	boolean	true only on the frame the button was pressed.
GetMouseButton(button)	boolean	true while the button is held.
GetMouseButtonUp(button)	boolean	true only on the frame the button was released.
GetMousePosition()	Vector2	The cursor position in window pixels, from the top-left corner.
MouseLeft, MouseMiddle, MouseRight	integer	Button numbers to pass to the functions above.

if Input.GetMouseButtonDown(Input.MouseLeft) then Fire() end
if Input.GetMouseButton(Input.MouseRight) then Aim() end

While the game runs, the mouse is captured for mouse look and the cursor is hidden, so GetMousePosition isn't very useful yet. Mouse look itself is handled by the Player Controller, not by scripts.

---

Examples

Toggle a flashlight

-- Scripts/Flashlight.lua (sector script): F switches the room light on and off.
local on = true
local litColor

function Start()
    litColor = sector.light
end

function Update()
    if not Input.GetKeyDown(Key.F) then return end

    on = not on
    sector:FadeLight(on and litColor or Vector3(20, 20, 20), 0.1)
end

Charge a throw while a key is held

-- Scripts/ChargeThrow.lua (on the player): hold G to charge, release to throw.
---@field maxCharge number @ Seconds To Full Power
maxCharge = 1.5

local charge = 0

function Update()
    if Input.GetKey(Key.G) then
        charge = mathT.Min(charge + GameTime.deltaTime, maxCharge)
    end

    if Input.GetKeyUp(Key.G) then
        local power = charge / maxCharge   -- 0..1
        Debug.Print("Throw with power", mathT.Round(power, 2))
        charge = 0
    end
end