From Multi Theft Auto: Wiki
(Redirected from UnbindControlKeys)
Jump to navigation Jump to search

These useful clientside functions bind the keys bound to a control individually, using bindKey, and unbind them using unbindKey. The objective of these functions is to bypass the limitation of binding a control directly which ignores key presses if the control is deactivated at the moment (so the script would be able to react if the player presses aim_weapon in a vehicle, for example).


boolean/nil bindControlKeys ( string control, misc bindData )
boolean/nil unbindControlKeys ( string control )

Required arguments

  • control: The name of the control to bind or unbind. See control names.
  • bindData: (bindControlKeys only) Configures how the control keys will be bound. See clientside bindKey syntaxes for reference.


These functions return true if no error arised. They return nil plus an error message otherwise.


You can only have one control keys bind per control. That should be enough for most scripts. If you want to create more binds, copy these functions into a new script file (or resource) and mark them as local.

Functions source

Click to collapse [-]
Clientside script
local controls = { "fire", "next_weapon", "previous_weapon", "forwards", "backwards", "left", "right", "zoom_in", "zoom_out",
 "change_camera", "jump", "sprint", "look_behind", "crouch", "action", "walk", "aim_weapon", "conversation_yes", "conversation_no",
 "group_control_forwards", "group_control_back", "enter_exit", "vehicle_fire", "vehicle_secondary_fire", "vehicle_left", "vehicle_right",
 "steer_forward", "steer_back", "accelerate", "brake_reverse", "radio_next", "radio_previous", "radio_user_track_skip", "horn", "sub_mission",
 "handbrake", "vehicle_look_left", "vehicle_look_right", "vehicle_look_behind", "vehicle_mouse_look", "special_control_left", "special_control_right",
 "special_control_down", "special_control_up" }

local boundControlsKeys = {}
local bindsData = {}

function unbindControlKeys(control)
    -- Ensure the argument has got the appropiate type
    assert(type(control) == "string", "Bad argument @ unbindControlKeys [string expected, got " .. type(control) .. "]")
    -- Check if we have a valid control
    local validControl
    for _, controlComp in ipairs(controls) do
        if control == controlComp then
            validControl = true
    assert(validControl, "Bad argument @ unbindControlKeys [Invalid control name]")
    -- Have we got a bind on this control?
    assert(boundControlsKeys[control], "Bad argument @ unbindControlKeys [There is no bind on such control]")
    -- Unbind each key of the control
    for _, bindData in pairs(bindsData[control]) do
    -- Remove references
    boundControlsKeys[control] = nil
    bindsData[control] = nil
    return true

function bindControlKeys(control, ...)
    -- Ensure the argument has got the appropiate type
    assert(type(control) == "string", "Bad argument 1 @ bindControlKeys [string expected, got " .. type(control) .. "]")
    -- Check if we have a valid control
    local validControl
    for _, controlComp in ipairs(controls) do
        if control == controlComp then -- Is the specified control in the table?
            validControl = true -- If so, it's a valid control
    assert(validControl, "Bad argument 1 @ bindControlKeys [Invalid control name]")
    -- Do we already have this control bound?
    if boundControlsKeys[control] then
        unbindControlKeys(control) -- Delete the first control keys bind
    boundControlsKeys[control] = getBoundKeys(control) -- Store the keys of that control that will be bound
    bindsData[control] = {} -- Store bind data, so we can unbind each key of the control later
    for key in pairs(boundControlsKeys[control]) do
        -- Can we bind the key with the specified arguments?
        assert(bindKey(key, unpack(arg)), "Bad arguments @ bindControlKeys [Could not create key bind]")
        -- If so, register the bind data and continue
        table.insert(bindsData[control], { key, unpack(arg) })
    return true

-- The keys bound to a control can be changed in Settings. The next function updates the binds properly in that case.
-- Also note that the next function IS NOT MEANT to be exported or called by the script.
local function keepControlKeyBindsAccurate()
    if next(boundControlsKeys) then -- Have we got any control keys bound?
        for boundControl, boundKeys in pairs(boundControlsKeys) do
            if toJSON(boundKeys) ~= toJSON(getBoundKeys(boundControl)) then -- Have we changed the keys bound to a control?
                -- Update our custom control bind
                for _, bindData in ipairs(bindsData[boundControl]) do
                    unbindKey(unpack(bindData)) -- Unbind every key of that cotnrol that we have bound before
                    -- Bind again the appropiate keys
                    for key in pairs(getBoundKeys(boundControl)) do
                        local bindDataNoKey = bindData -- Copy bindData into another variable
                        table.remove(bindDataNoKey, 1) -- Ignore the key of our bindData
                        bindKey(key, unpack(bindDataNoKey)) -- Bind again the data, but with the updated key
                        bindData[1] = key -- Update the key in the references
                boundControlsKeys[boundControl] = getBoundKeys(boundControl) -- Update the control bound keys list
addEventHandler("onClientRender", root, keepControlKeyBindsAccurate)


This example allows players to toggle driveby by pressing or releasing the aim_weapon control.

local function toggleDriveby()
    if isPedInVehicle(localPlayer) then
        setPedDoingGangDriveby(localPlayer, not isPedDoingGangDriveby(localPlayer))
bindControlKeys("aim_weapon", "both", toggleDriveby)

See also

Table functions

  • addTableChangeHandler » This function monitors the changes of a table.
  • getTableFromSql » This functionality is used to obtain saved tables using the function (SetTableToSql ).
  • isValueInTable » This function returns true if the value exists in the table, false if the value does not exist in the table.
  • pairsByKeys » This function sort pairs table.
  • rangeToTable » This function converts a string range to a table containing number values.
  • setTableProtected » This function protects a table and makes it read-only.
  • setTableToSql » This function is used to save the table in the database (sql).
  • Sort_Functions » These functions are able to sort your tables by a key.
  • » This function checks whether two given tables are equal.
  • table.copy » This function copies a whole table and all the tables in that table.
  • table.deepmerge » This function deep merges two tables. Every nested table will be correspondingly merged.
  • table.element » This function returns a new table with only userdata content.
  • table.fromString » This function converts string to a table.
  • table.getRandomRows » This function returns random rows from table.
  • » This function goes through a table and replaces every field with the return of the passed function, where the field's value is passed as first argument and optionally more arguments.
  • table.merge » This function merges two or more tables together.
  • table.random » This function retrieves a random value from a table.
  • table.removeValue » This function removes a specified value from a table.
  • table.size » This function returns the absolute size of a table.
  • table.toString » This function converts table to a string.
  • table.flip » This function flip table values.

ACL functions

  • aclGroupClone » This function clone a group to another group with/without ACLs and/or objects.
  • getAccountsRanks » This function is used to detect the account name groups and put them in the chat.
  • getPlayerAcls » This function returns a table of all ACL groups on a player.
  • getPlayersInACLGroup » This function returns all players in an ACL group.
  • isPlayerInACL » This function checks if a player element is in an ACL group.
  • renameAclGroup » This function gives an existing ACL group a new name.
  • isPlayerACLAdmin » This function checks if a player element belong to Admin group in ACL

Account functions

Camera functions

  • smoothMoveCamera » This function allows you to create a cinematic camera flight.

Colshape functions

Cursor functions

Drawing functions

Effects functions

  • attachEffect » This function allows you attach an effect to an element.
  • setScreenFlash » This function will make the screen flash(like a screenshot).

Element functions

  • autoAttach » This function attaches one element into another at the same position and rotation they are.
  • isElementPlayer » This function checks whether the element is a player or not.
  • attachElementToBone » This function allows you to attach an element to ped bone accurately using new bone functions.
  • getElementsInDimension » This function returns a table of elements that are in the specified dimension.
  • getElementSpeed » This function returns the specified element's speed in m/s, km/h or mph.
  • getElementsWithinMarker » This function returns a table of elements that are within a marker's collision shape.
  • getElementUsingData » This function returns table elements that contains the elements data with the given key and value.
  • getNearestElement » This function returns the nearest element (of a specific type) to a player.
  • isElementInPhotograph » This function checks if an element is in the player's camera picture area.
  • isElementInRange » This function allows you to check if an element's range to a main point is within the maximum range.
  • isElementMoving» This function checks if an element is moving.
  • isElementWithinAColShape» This function checks if an element is within a collision shape element.
  • isElementInAir» This function checks if an element is in air or not.
  • multi_check » This function checks one element to many, handy and clean.
  • setElementSpeed » This function allows you to set the speed of an element in kph or mph units.
  • getElementDirectionCardialPoint » This function returns the direction of the element according to the wind rose.


  • onVehicleWeaponFire » This code implements an event that is triggered when a player in a vehicle fires a vehicle's weapon.

Input functions

  • bindControlKeys » This function allows you to bind each key bound to a control individually. Doing this bypasses a little MTA restriction.
  • getBoundControls » This function returns a table of control names that are bound to the specified key.
  • unbindControlKeys » This function allows you to unbind each key bound to a control individually. Use this function with bindControlKeys.
  • isCommandHandlerAdded » This function allows you to check if a command is added or not in the respective resource.

Data functions

  • byte2human » This function converts an integer (number of bytes) into a human-readable unit.
  • capitalize » This function capitalizes a given string.
  • convertDate » This function converts date to another look.
  • convertServerTickToTimeStamp » This function converts server ticks to a unix timestamp.
  • convertTextToSpeech » This function converts the provided text to a speech in the provided language which players can hear.
  • findRotation3D » This function takes two sets of XYZ coordinates. It returns the 3D direction from point A to point B.
  • findRotation » This function takes two points and returns the direction from point A to point B.
  • formatDate » This function formats a date on the basis of a format string and returns it.
  • formatNumber » This function formats large numbers by adding commas.
  • generateRandomASCIIString » This function returns a random string which uses ASCII characters.
  • generateString » This function generates a random string with any characters.
  • getAge » This function calculates the age of a given birthday.
  • getDistanceBetweenElements » Returns the distance between two elements.
  • getDistanceBetweenPointAndSegment2D » This function takes point coordinates and line (a segment) starting and ending coordinates. It returns the shortest distance between the point and the line.
  • getEasterDate » This function returns easter date monthday and month for a given year.
  • getElementRelatedAngle » This function returns the related angle between one element to another. This is useful to check which side an element is to another.
  • getFreeDimension » This function get free dimension.
  • getKeyFromValueInTable » This function returns the key of the specified value in a table.
  • getOffsetFromXYZ » This function allows you to take an entity and a position and calculate the relative offset between them accounting for rotations.
  • getPointFromDistanceRotation » This function finds a point based on a starting point, direction and distance.
  • getRealMonth » This function returns the current month name
  • getRGColorFromPercentage »This function returns two integers representing red and green colors according to the specified percentage.
  • getScreenRotationFromWorldPosition » This function returns a screen relative rotation to a world position.
  • getTimestamp » This function returns the UNIX timestamp of a specified date and time.
  • gradientString » This function transforms a string in a new coloured gradient string.
  • hex2rgb » This function convert hex to rgb.
  • hexColorToRGB » This function convert hex string/number to RGBA values.
  • isLeapYear » This function returns a boolean representing if a given year is a leap year.
  • isValidMail » This function checks whether a provided e-mail string is valid.
  • removeHex » This function is used to remove hexadecimal numbers (colors, for example) from strings.
  • RGBToHex » This function returns a string representing the color in hexadecimal.
  • RGBToHSV » This function convert RGB to HSV color space.
  • RGBToDecimal » This function convert RGB to Decimal color.
  • secondsToTimeDesc » This function converts a plain seconds-integer into a user-friendly time description.
  • string.count » This function counts the amount of occurences of a string in a string.
  • string.explode » This function splits a string at a given separator pattern and returns a table with the pieces.
  • string.insert » This function inserts a string within another string at a given position.
  • switch » This function allows the value of a variable or expression to control the flow of program execution via a multiway branch.
  • tocolor2rgba » This function convert tocolor to rgba.
  • toHex » This function converts a decimal number to a hexadecimal number, as a fix to be used client-side.
  • var dump » This function outputs information about one or more variables using outputConsole.
  • wavelengthToRGBA » This function converts a physical wavelength of light to a RGBA color.

GUI functions

  • centerWindow » This function centers a CEGUI window element responsively in any resolution.
  • guiMoveElement » This function moves guiElement by/like using moveObject.
  • guiSetStaticImageMovable » This function allows you to move a static image like a gui window.
  • isMouseOnGUICloseButton » This function allows you to check whether the mouse cursor/pointer is within a gui-window's native close button.
  • isMouseOnGuiElement » This function allows you to check whether or not your mouse is over a specific gui element, this is especially useful if the gui element has a parent.
  • guiLabelAddEffect » This function add an effects to the gui-label like (shadow, outline).

Marker functions

Math functions

  • math.clamp » This function returns the number between range of numbers or it's minimum or maximum.
  • math.getBezierPoint » Get N-th order bezier point.
  • math.hypot » This function returns the Hypotenuse of the triangle given by sides x and y.
  • math.isPointInPolygon » Check if point is inside polygon or not.
  • math.lerp » Get val between two integer.
  • math.percent » This function returns a percentage from two number values.
  • math.polygonArea » Compute area of any polygon.
  • math.randomDiff » Generates a pseudo-random integer that's always different from the last random number generated.
  • math.rotVecToEulerAngle » Rotation Vector To Euler Angle
  • math.round » Rounds a number whereas the number of decimals to keep and the method may be set.
  • mathNumber » This function is a workaround for the client-side floating-point precision of 24-bits.
  • reMap » Re-maps a number from one range to another.
  • math.percentProgress » Returns a percentage progress from two specific values.
  • math.average » This function returns the simple arithmetic mean of multiple numbers.

Map functions

Ped functions

  • getAlivePlayers » This function returns a table of the alive players client-side.
  • getAlivePlayersInTeam » This function returns a table of the alive players in a team.
  • getGuestPlayers » This function gets a players not login or players Guest .
  • getOnlineAdmins » This function returns a table of all logged-in administrators.
  • getPedEyesPosition » This function allows you to get peds eyes position.
  • getPedGender » This function allows you to get peds their gender.
  • getPedMaxHealth » This function returns a pedestrians's maximum health by converting it from their maximum health stat.
  • getPedMaxOxygenLevel » This function returns a ped's maximum oxygen level by converting it from their maximum underwater stamina stat.
  • getPedWeaponSkill » This function returns a ped's corresponding weapon skill level name.
  • getPedHitBone » This function gets the approximate number of the bone where the ped is hit.
  • getPlayerFromNamePart » This function returns a player from partial name.
  • getPlayerFromSerial » This function returns a player from their serial.
  • getPlayersByData » This function returns a table of players that have the specified data name.
  • getPlayersInPhotograph » This function returns a table of all players in photograph.
  • getPlayersInVehicles » This function returns a table of the players insides vehicles from a specified dimension.
  • isPedAiming» This function checks if a pedestrian is aiming their weapon.
  • isPedAimingNearPed » This is similar to isPedAiming but uses a colshape to be more precise.
  • isPedDiving » This feature checks that pedestrian is diving in the water.
  • isPedDrivingVehicle » This function checks if a specified pedestrian is driving a vehicle.
  • isPlayerInTeam » This function checks if a player is in a specified team.
  • setPedAttack » This function will make a ped attack a specified target.
  • setPedFollow » This function will make a ped follow a specified target.
  • getPlayerNameFromID » This function will get the player name from the ID element data.

Player functions

Resource functions

Sound functions

Browser functions

  • playVideo » This function plays a video on the screen.

Team functions

Vehicle functions

Weapon functions

Object functions

XML functions

  • getXMLNodes » This function returns all children of a XML node.

Engine functions


  • animate » This function allows you to use interpolateBetween without render event and easily used.
  • callClientFunction » This function allows you to call any client-side function from the server's side.
  • callServerFunction » This function allows you to call any server-side function from the client's side.
  • check » This function checks if its arguments are of the right type and calls the error-function if one is not.
  • checkPassiveTimer » This function allows you to use passive timers in your conditions. For example you want to prevent players repeatedly using a command.
  • coroutine.resume » This function applies a fix for hidden coroutine error messages.
  • compact » This function create table containing variables and their values.
  • getBanFromName » This functions returns the ban of the given playername.
  • getCurrentFPS » This function returns the frames per second at which GTA: SA is running.
  • getSkinNameFromID » This function returns the name of the skin from the given id.
  • IfElse » This function returns one of two values based on a boolean expression.
  • isCharInString » This shared function allows you to check if a char specified is in a string value.
  • isMouseInCircle » This function checks if a cursor position is in circular area or not.
  • isMouseInPosition » This function allows you to check whether the mouse cursor/pointer is within a rectangular position.
  • iterElements » This function returns a time-saving iterator for your for-loops.
  • PlotTrajectoryAtTime » Calculate projectile/water trajectory.
  • preprocessor » This function allow you to use gcc macros.
  • vector3:compare » This method checks whether two vectors match, with optional precision.
  • svgCreateRoundedRectangle » This function creates a rectangle with rounded edges.
  • isLastExecuteInTimer » This function check if the execute is the last execute in the timer.