RegisterCommand y RegisterKeyMapping: teclas rebindables en FiveM

Quieres un comando como /garage que cualquiera pueda escribir, una tecla como E que haga lo mismo, y una forma para que cada jugador cambie esa tecla. FiveM te da RegisterCommand para el comando y RegisterKeyMapping para la tecla. Este artículo muestra ambos, cómo restringir un comando a administradores, cómo hacer una acción que funcione mientras se mantiene presionada una tecla, y por qué cambiar una tecla predeterminada más adelante no hace nada para los jugadores existentes.

#Un comando simple

Un comando es un nombre y una función:

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

En el cliente, source no es útil. La tabla args contiene las palabras escritas después del comando, y rawCommand es el texto completo. En el servidor, source es el id del jugador, o 0 cuando el comando viene de la consola del servidor.

Lo mismo en el servidor, con un argumento:

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

#Restringir un comando con ACE

El último argumento de RegisterCommand es restricted. Con true, nadie puede ejecutar el comando a menos que tenga el permiso ACE command.<name>. Dáselo a tus administradores en server.cfg:

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

Los jugadores sin él obtienen un error de permiso y el comando nunca se ejecuta. Cómo funcionan los grupos y principales de ACE se cubre en permisos ACE para administradores de FiveM.

Cuidado: un comando false puede ser escrito por cualquiera, incluyendo tramposos que lo llamen a mano. Nunca confíes en un comando del lado del cliente para proteger algo valioso. Haz la verificación de permiso real en el servidor.

#Vincula el comando a una tecla

RegisterKeyMapping vincula un comando a una tecla, en el cliente. El comando debe existir, así que registra ambos:

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

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

Los cuatro argumentos son el nombre del comando, la descripción mostrada al jugador, el dispositivo de entrada ('keyboard' aquí) y la tecla predeterminada. El nombre de la tecla se escribe como E, F5 o LSHIFT.

Los jugadores ahora pueden presionar F5, o escribir /garage, y ambos hacen lo mismo.

#Dónde los jugadores lo revinculan

La tecla predeterminada es solo una sugerencia. Los jugadores abren la Configuración del juego > Asignaciones de Teclas > FiveM y encuentran tu acción allí, listada por el texto de descripción. Pueden cambiar la tecla a lo que quieran.

Escribe una descripción clara ('Open the garage', no 'garage'), ya que es todo lo que el jugador ve. Mantenlo corto y único, así que dos scripts no muestran la misma etiqueta.

#Acciones de retención con comandos + y -

Para algo que dure mientras se mantiene presionada una tecla, como un push-to-talk o una cuerda, registra un par de comandos: uno comenzando con + y otro con -. El juego ejecuta +name cuando la tecla se presiona y -name cuando se suelta:

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)

Mapea el nombre +. Ambos comandos + y - deben estar registrados, o el lanzamiento nunca se ve.

#Por qué una nueva tecla predeterminada no hace nada

Esto atrapa a muchos desarrolladores. Lanzas la versión 1 con 'F5', luego cambias a 'F6' en la versión 2. Los jugadores que ya ejecutaron la versión 1 aún presionan F5.

La razón: la tecla predeterminada de RegisterKeyMapping se aplica solo la primera vez que el juego ve esa asignación. Después de eso, la vinculación vive en la configuración propia del jugador, y el nuevo valor predeterminado no se usa. Entonces:

• Nuevos jugadores obtienen la nueva tecla.
• Jugadores existentes mantienen la antigua, o la que ellos mismos eligieron.

No hay una forma limpia de forzar una tecla en jugadores que ya tienen la vinculación. Tus opciones:

1. Dile a los jugadores que revinculen en Configuración > Asignaciones de Teclas > FiveM. Ponlo en tus notas de actualización.
2. Usa un nuevo nombre de comando para la acción, por ejemplo garage_v2 en lugar de garage. Es una nueva asignación, así que se aplica el nuevo valor predeterminado. Los jugadores verán ambas entradas hasta que se elimine la antigua.
3. No confíes en el valor predeterminado. Muestra la tecla real en tu interfaz en lugar de una letra fija, o dile a los jugadores cómo revincular.

Esta también es la razón por la que debes probar cambios de teclas en un perfil nuevo, o después de eliminar la vinculación en la configuración. De lo contrario, sigue probando tu tecla antigua.

#Mantén la lógica del comando pequeña

Un manejador de comando debe hacer una cosa: llamar a una función. Luego la tecla, el comando y una interacción objetivo (consulta ox_target: cómo añadir objetivos) todos llaman a la misma función:

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

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

Evita teclas que otras cosas ya usan. Verificar IsControlJustPressed en un bucle para la misma tecla que un comando mapeado hace que ambos se ejecuten. Usa la asignación sola.

#Lista de verificación