Skip to content

keybindTested⚓︎

This event fires whenever a keybind is tested by the game. A keybind test is often used to see if a button is pressed, but it can also be done to see if an input was toggled or released. Blocking this event is equivalent to setting the result event data to false.

--- @param e keybindTestedEventData
local function keybindTestedCallback(e)
end
event.register(tes3.event.keybindTested, keybindTestedCallback)

Tip

This event can be filtered based on the keybind event data.

Tip

This event supports blocking by setting e.block to true or returning false. Blocking the event prevents vanilla behavior from happening. For example, blocking an equip event prevents the item from being equipped.

Tip

An event can be claimed by setting e.claim to true, or by returning false from the callback. Claiming the event prevents any lower priority callbacks from being called.

Event Data⚓︎

  • keybind (tes3.keybind): Read-only. The keybind that was tested. This maps to the tes3.keybind.* constants.
  • result (boolean): The read state of the keybind. If true, the key was pressed/released/toggled as determined by the transition event data.
  • transition (tes3.keyTransition): Read-only. The transition type specified for the test. Each game mechanic may choose to trigger on a specific transition type. This is typically tes3.keyTransition.downThisFrame (key pressed), but not guaranteed to be. Always be sure to check what transition is being used.

Examples⚓︎

Example: Block Journal Keybind

Prevents the journal keybind from ever being registered as pressed.

--- @param e keybindTestedEventData
local function noJournalMenu(e)
    --[[ A keybind can have different transition types.

    tes3.keyTransition.downThisFrame     - If keybind changed from up to down ("pressed")
    tes3.keyTransition.upThisFrame       - If keybind changed from down to up ("unpressed")
    tes3.keyTransition.changedThisFrame  - If keybind changed state ("toggled")
    tes3.keyTransition.isDown            - If keybind is currently pressed ("while held")

    The transition type is specific per test, as there are different use cases for each transition, and there may be multiple tests per keybind. You may need to log this event to see how the game utilizes a keybind.
    ]]--

    -- We only care about keybind tests that check if the key was pressed this frame.
    if (e.transition ~= tes3.keyTransition.downThisFrame) then
        return
    end

    -- If the result was false, we also don't care.
    if (not e.result) then
        return
    end

    -- Set the result to false to make the game think the key wasn't pressed.
    -- We could also block this event by using `return false`.
    tes3.messageBox("You aren't allowed to open your journal.")
    e.result = false
end
event.register(tes3.event.keybindTested, noJournalMenu, { filter = tes3.keybind.journal })