Keybinds

encore.addKeybind creates a key mapping that players can change under Settings > Key Bindings > FiveM. You get press and release handlers, a way to switch the bind off, and the key the player has actually bound, so your prompts never say "E" when they changed it to "F".

Keybinds are client only.

#Signature

local bind = encore.addKeybind(data)

#The keybind object

encore.addKeybind returns an object you keep a reference to.

#Behaviour

• onPressed is ignored while the bind is disabled or the pause menu is open.
• onReleased only fires if the press was accepted, so a key released after unpausing doesn't trigger a stray release.
• Registering the same name twice logs Keybind "<name>" is already registered and returns the existing bind.
• Under the hood the bind registers +<name> and -<name> commands and a key mapping. The +/- chat suggestions are removed half a second later, so they don't clutter chat.

#Choosing a name

FiveM stores a player's binding under the mapping name, and it follows them between servers that use the same name. So:

• Make the name unique to your resource, for example my_loot_search, so you don't collide with another script.
• Keep the name stable once your resource is live. A new name is a new mapping, and players would have to rebind it.

#Examples

#Hold to search

local search = encore.addKeybind({
    name = 'my_loot_search',
    description = 'Search a container',
    defaultKey = 'E',
    onPressed = function(self)
        encore.showPrompt({ key = self:getCurrentKey(), label = 'Searching' })
    end,
    onReleased = function()
        encore.hidePrompt()
    end,
})

#Only active near something

Start the bind disabled, then turn it on when the player is in range.

local stash = encore.addKeybind({
    name = 'my_stash_open',
    description = 'Open the camp stash',
    defaultKey = 'E',
    disabled = true,
    onPressed = function()
        TriggerServerEvent('my-stash:open', 'camp')
    end,
})

CreateThread(function()
    while true do
        local near = #(GetEntityCoords(PlayerPedId()) - StashCoords) < 2.0
        if near ~= not stash.disabled then
            stash:disable(not near)
            if near then
                encore.showPrompt({ key = stash:getCurrentKey(), label = 'Open stash' })
            else
                encore.hidePrompt()
            end
        end
        Wait(250)
    end
end)

The server handler for my-stash:open must still check the player's distance itself, because a client can trigger the event without pressing anything.

#Related

• UI services
• Registering commands