RegisterCommand e RegisterKeyMapping: keys rebindáveis em FiveM

Você quer um comando como /garage que qualquer um possa digitar, uma key como E que faça o mesmo, e uma forma para cada jogador mudar aquela key. FiveM te dá RegisterCommand para o comando e RegisterKeyMapping para a key. Este artigo mostra ambos, como restringir um comando para admins, como fazer uma ação que funciona enquanto uma key é mantida, e por que mudar uma default key depois não faz nada para jogadores existentes.

#Um comando simples

Um comando é um nome e uma função:

RegisterCommand('garage', function(source, args, rawCommand)
    print('garage opened')
end, false)

No cliente, source não é útil. A tabela args contém as palavras digitadas após o comando, e rawCommand é o texto completo. No server, source é o id do jogador, ou 0 quando o comando vem do console do server.

O mesmo no server, com um argumento:

RegisterCommand('heal', function(source, args)
    local target = tonumber(args[1]) or source
    TriggerClientEvent('my_script:heal', target)
end, true)

#Restrinja um comando com ACE

O último argumento de RegisterCommand é restricted. Com true, ninguém pode rodar o comando a menos que tenha a permissão ACE command.<name>. Dê-a aos seus admins em server.cfg:

add_ace group.admin command.heal allow
add_principal identifier.license:your_license_here group.admin

Jogadores sem ela recebem um erro de permissão e o comando nunca roda. Como grupos e principals ACE funcionam é coberto em ACE permissions for FiveM admins.

Atenção: um comando false pode ser digitado por todos, incluindo cheaters que o chamam manualmente. Nunca confie em um comando client-side para guardar algo valioso. Faça a verificação real de permissão no server.

#Vincule o comando a uma key

RegisterKeyMapping amarra um comando a uma key, no cliente. O comando deve existir, então registre ambos:

RegisterCommand('garage', function()
    print('garage opened')
end, false)

RegisterKeyMapping('garage', 'Open the garage', 'keyboard', 'F5')

Os quatro argumentos são o nome do comando, a descrição mostrada ao jogador, o dispositivo de entrada ('keyboard' aqui) e a key padrão. O nome da key é escrito como E, F5 ou LSHIFT.

Jogadores agora podem pressionar F5, ou digitar /garage, e ambos fazem a mesma coisa.

#Onde jogadores rebindem

A key padrão é apenas uma sugestão. Jogadores abrem as Settings > Key Bindings > FiveM do jogo e encontram sua ação lá, listada pelo texto de descrição. Podem mudar a key para o que quiser.

Escreva uma descrição clara ('Open the garage', não 'garage'), pois é tudo que o jogador vê. Mantenha curto e único, então dois scripts não mostram o mesmo label.

#Ações de hold com comandos + e -

Para algo que dura enquanto uma key é mantida, como um push-to-talk ou uma corda, registre um par de comandos: um começando com + e outro com -. O jogo roda +name quando a key desce e -name quando sobe:

local holding = false

RegisterCommand('+my_hold', function()
    holding = true
end, false)

RegisterCommand('-my_hold', function()
    holding = false
end, false)

RegisterKeyMapping('+my_hold', 'Hold to aim the tool', 'keyboard', 'G')

CreateThread(function()
    while true do
        if holding then
            -- do the held action here
            Wait(0)
        else
            Wait(250)
        end
    end
end)

Mapeie o nome +. Ambos os comandos + e - devem ser registrados, ou o release nunca é visto.

#Por que uma nova default key não faz nada

Isso pega muitos developers. Você lança versão 1 com 'F5', depois muda para 'F6' na versão 2. Jogadores que já rodaram versão 1 ainda pressionam F5.

A razão: a default key de RegisterKeyMapping é aplicada apenas a primeira vez que o jogo vê aquele mapping. Depois disso o binding vive nas suas próprias configurações, e a nova default não é usada. Então:

• Novos jogadores recebem a nova key.
• Jogadores existentes mantêm a antiga, ou qualquer que eles pegarem a si mesmos.

Não há forma limpa de forçar uma key em jogadores que já têm o binding. Suas opções:

1. Diga aos jogadores para rebindarem em Settings > Key Bindings > FiveM. Coloque nas suas notas de atualização.
2. Use um novo nome de comando para a ação, por exemplo garage_v2 em vez de garage. É um novo mapping, então o novo padrão se aplica. Jogadores verão ambas as entradas até a antiga ser removida.
3. Não confie no padrão. Mostre a key real em sua UI em vez de uma letra fixa, ou diga aos jogadores como rebindarem.

Isso também é por que você deve testar mudanças de key em um perfil fresco, ou após remover o binding nas configurações. Senão você continua testando sua key antiga.

#Mantenha a lógica do comando pequena

Um handler de comando deveria fazer uma coisa: chamar uma função. Depois a key, o comando e uma interação de target (veja ox_target: how to add targets) todos chamam a mesma função:

local function openGarage()
    print('garage opened')
end

RegisterCommand('garage', openGarage, false)
RegisterKeyMapping('garage', 'Open the garage', 'keyboard', 'F5')

Evite keys que outras coisas já usam. Checando IsControlJustPressed em um loop para a mesma key que um comando mapeado faz ambos dispararem. Use apenas o mapping.

#Checklist