Key mappings

Register a named action, default key and Lua callback with RegisterKeyMapping. Players can rebind it under Pause → Settings → KEY BINDINGS. Bindings persist across servers and launcher restarts.

Developers coming from FiveM will recognize the call. Open77 has no client command bus, so the mapping runs a Lua callback the resource supplies directly, rather than a registered command string.

A binding is observe-only: pressing its key fires the action but never hides the key from the game, and it is suppressed whenever a page owns the keyboard (chat open, the pause menu open, a rebind in progress), so typing never triggers an action.

Permission#

Every entry point requires the input.actions permission — the same one that gates Open77.input.isDown:

resource "flashlight"
version "1.0.0"

client_script "client/main.lua"

permissions { "input.actions" }

Declare a mapping#

RegisterKeyMapping is a bare global, mirrored as Open77.input.registerKeyMapping. The positional form is the common case:

-- RegisterKeyMapping(id, name, defaultKey, onPressed [, onReleased])
RegisterKeyMapping("flashlight", "Toggle flashlight", "F", function()
    toggleFlashlight()
end)

The callback receives the mapping id as its only argument. RegisterKeyMapping returns true, "<effectiveKey>" on success — the effective key is the player's saved rebind if there is one, otherwise the default — or false, "<reason>".

Re-registering the same id replaces the previous entry (reload-safe) and keeps the player's rebind.

Press and hold#

By default the action fires once on the key-down edge. Supply a release callback — or set hold in the table form — to receive the key-up edge as well. Use the table form when you need hold explicitly:

Open77.input.registerKeyMapping({
    id = "sprint",
    name = "Hold to sprint",
    key = "SHIFT",           -- `defaultKey` is accepted as an alias
    hold = true,
    onPressed  = function() startSprint() end,
    onReleased = function() stopSprint() end,
})

In the positional form, passing a fifth argument (the release callback) implies hold mode.

Key names#

Keys use the same vocabulary as Open77.input.isDown, normalized to upper case:

• a single alphanumeric — A–Z, 0–9
• The French AZERTY number row: &, é, ", ', (, -, è, _, ç, à, ), =. Common punctuation is accepted too: + [] {} ; : , . / \\ and ` ~ ! ? @ # $ % ^ * < > | ù ².
• F1–F12
• SPACE, ENTER/RETURN, TAB, SHIFT, CTRL/CONTROL, ALT, CAPSLOCK, BACKSPACE, INSERT, DELETE, HOME, END, PAGEUP, PAGEDOWN, and the four arrow keys UP, DOWN, LEFT, RIGHT.

The pause page's capture, the Lua layer, and the native dispatch all agree on this set, so a key chosen in the rebinding UI maps to exactly what a resource registered.

Letters are normalized to uppercase; accented characters and punctuation are preserved. These are logical keys on the player's current Windows layout, not US physical labels: on French AZERTY, é and 2 refer to the same top-row key. No Shift chord is required. The menu displays the captured character, including when CEF provides no event.code. Use UTF-8 Lua files, for example RegisterKeyMapping("slot2", "Second slot", "é", callback).

Only keyboard keys can be bound. A mapping's key is persisted, listed in the pause menu and polled by the engine's own dispatcher, and that dispatcher reads keys. Mouse buttons and gamepad controls are readable — see the next section — but they are not bindable, and the vocabulary was deliberately left alone so that a key saved in keybinds.json can never name a control nothing polls.

Reading a device directly#

Open77.input also reads the mouse, the wheel, a gamepad and the cursor. Same table, same input.actions permission: a mouse button is the same kind of read as a key, and a second permission string would only mean every menu manifest grows a line.

Control names#

Names are case-insensitive. Open77.input.devices() is the authoritative list for the machine the resource is running on, and it is the list to build a settings screen from rather than the table above.

These are physical reads#

Everything here reports the device, not the game's interpretation of it. It does not know the player's Cyberpunk key bindings, it does not know whether the game or a menu is currently consuming the control, and it does not know about in-game controller remapping. In FiveM's vocabulary that makes every one of these the GetDisabledControlNormal flavour rather than the GetControlNormal one.

To get the enabled flavour, combine it with the two questions Open77 can answer about who owns the input:

local function gameplayInput(control)
    if Open77.input.isCaptured() then return false end        -- a WebUI has the keyboard
    if Open77.session.isMenuOpen() then return false end      -- some modal owns the screen
    return Open77.input.isDown(control) == true
end

Gamepad reads are also zero — and buttons false — while the game window is not in the foreground. The keyboard already behaved that way; this only extends the rule to the pad.

A missing device is named, never answered zero#

An unplugged gamepad refuses by name. This matters more than it looks: an axis that always reads zero cannot be told from a stick held at centre, so a menu built on a silent zero looks broken rather than unsupported.

local turn, reason = Open77.input.axis("padRightStickX")
if turn == nil then
    -- reason == "gamepad_not_connected" on a machine with no pad
    turn = 0
end

Asking for an axis by isDown, or a button by axis, is a real mistake and each is named: control_is_an_axis and control_is_a_button. An unknown name is unsupported_action_key.

Gamepad support is XInput, slot 0. Controllers that present themselves as XInput devices — the Xbox pads, and a DualSense or DualShock through Steam Input or DS4Windows — are read; one that does not is invisible and reports as not connected. Sticks come back with XInput's own dead zones removed and the remainder rescaled, so a stick at rest reads exactly 0 and at the rim exactly 1; stick Y is positive up.

The wheel and the motion counters are cumulative#

mouseWheel, mouseWheelX, mouseDeltaX and mouseDeltaY count from the moment the client started and are not consumed by reading them. Difference two samples:

local previous = Open77.input.axis("mouseWheel") or 0
CreateThread(function()
    while true do
        Wait(0)
        local now = Open77.input.axis("mouseWheel") or 0
        if now ~= previous then
            scrollList(now - previous)   -- positive is away from the player
            previous = now
        end
    end
end)

A consume-on-read wheel would be shorter to use and wrong: two resources reading it would each receive part of the same scroll, and neither could tell.

The pointer, and which space it is in#

Open77.input.pointer() returns x, y as 0..1 across the rendered image, origin top left, plus a source. That is the same frame Open77.camera.project answers in and Open77.camera.unproject consumes, so hit-testing a projected world point is a subtraction:

local x, y = Open77.input.pointer()
local target = Open77.camera.project({ x = 100.0, y = 220.0, z = 15.0 })
if x and target and target.onScreen then
    local dx, dy = x - target.x, y - target.y
    if dx * dx + dy * dy < 0.02 * 0.02 then showTooltip() end
end

Coordinates are normalized rather than pixel-based. DPI scaling can make the window's client rectangle differ from the render buffer; normalized values use a consistent coordinate space.

source says which regime produced it:

During ordinary gameplay Cyberpunk recentres the OS cursor every frame, so system reads near 0.5, 0.5. That is where the cursor is, not a failed read.

Rebinding UI#

The pause menu's KEY BINDINGS tab lists every registered action across every running resource and rebinds them. It is only a viewer: it reads the registry and writes back through the same management API any resource may call.

This includes both bundled client resources and resources downloaded from the current server. Callbacks stay in their owning resource; the pause menu can list, rebind and reset them across the two client layers. Stopped/disconnected resources disappear from the list, while their saved choices are retained for the next session. There are no demo bindings in the shipped pause menu.

The engine raises the local event open77:keybinds:changed (no arguments) after any register, rebind, reset, or unregister, so a viewer can reload its list:

AddEventHandler("open77:keybinds:changed", function()
    -- refresh a custom keybind display
end)

Registration reference#

A resource may register up to 64 mappings. Bindings never fire while another WebUI owns keyboard focus, and pressing a mapped key does not stop the game from also seeing it — choose keys that do not clash with an in-world action, or let players rebind.

Persistence#

Rebinds are stored in a single machine-global file, …/storage/keybinds.json, deliberately outside the per-server KVP layout so a rebind follows the player to every server and survives a relaunch. The engine owns and validates the format; a corrupt file degrades to defaults rather than refusing bindings. A mapping inherits its saved key at registration time, so the player's choice is applied the moment the resource declares the action on the next session.

If writing the preferences fails, rebind/reset returns false, "keybind_save_failed" and keeps the previous effective key. Updating one client layer does not discard the other's overrides.