AttachElementToBone: Difference between revisions

Revision as of 10:03, 15 February 2021

This function allows you to attach an object, ped, player or vehicle to a ped or player bone for ONE FRAME. In order to attach an element continuously to a bone, this function should be used in conjunction with onClientPedsProcessed. The function checks if a player is actually on screen and if he is not, the object gets moved out of the stream distance in order to preserve some performance. Unlike bone_attach, this function provides perfect accuracy for the attached elements and performs better.

Syntax

bool attachElementToBone(element theElement, ped thePed, int boneID, float offsetX, float offsetY, float offsetZ, float rotationOffsetX, float rotationOffsetZ, float rotationOffsetZ)

Required arguments

theElement: The element which should be attached to the ped/player bone. Should work with any element that is supported by matrix functions.
thePed: The ped or player which the element should be attached to.
boneID: The target bone where the element should be attached to.
offsetX: The X position offset from the bone.
offsetY: The Y position offset from the bone.
offsetZ: The Z position offset from the bone.
rotationOffsetX: The rotation X-axis offset from the bone, in radians.
rotationOffsetY: The rotation Y-axis offset from the bone, in radians.
rotationOffsetZ: The rotation Z-axis offset from the bone, in radians.

Bone numbers

1: BONE_PELVIS1
2: BONE_PELVIS
3: BONE_SPINE1
4: BONE_UPPERTORSO
5: BONE_NECK
6: BONE_HEAD2
7: BONE_HEAD1
8: BONE_HEAD
21: BONE_RIGHTUPPERTORSO
22: BONE_RIGHTSHOULDER
23: BONE_RIGHTELBOW
24: BONE_RIGHTWRIST
25: BONE_RIGHTHAND
26: BONE_RIGHTTHUMB
31: BONE_LEFTUPPERTORSO
32: BONE_LEFTSHOULDER
33: BONE_LEFTELBOW
34: BONE_LEFTWRIST
35: BONE_LEFTHAND
36: BONE_LEFTTHUMB
41: BONE_LEFTHIP
42: BONE_LEFTKNEE
43: BONE_LEFTANKLE
44: BONE_LEFTFOOT
51: BONE_RIGHTHIP
52: BONE_RIGHTKNEE
53: BONE_RIGHTANKLE
54: BONE_RIGHTFOOT

Return

Returns true if the object has successfully been attached to the ped/player, returns false if the specified ped/player is not on screen and the object has been moved out of the streaming distance.

Code

function attachElementToBone(element, ped, bone, offX, offY, offZ, offrx, offry, offrz)
    if isElementOnScreen(ped) then
        local boneMat = getElementBoneMatrix(ped, bone)
        local sroll, croll, spitch, cpitch, syaw, cyaw = math.sin(offrz), math.cos(offrz), math.sin(offry), math.cos(offry), math.sin(offrx), math.cos(offrx)
        local rotMat = {
            {sroll * spitch * syaw + croll * cyaw,
            sroll * cpitch,
            sroll * spitch * cyaw - croll * syaw},
            {croll * spitch * syaw - sroll * cyaw,
            croll * cpitch,
            croll * spitch * cyaw + sroll * syaw},
            {cpitch * syaw,
            -spitch,
            cpitch * cyaw}
        }
        local finalMatrix = {
            {boneMat[2][1] * rotMat[1][2] + boneMat[1][1] * rotMat[1][1] + rotMat[1][3] * boneMat[3][1],
            boneMat[3][2] * rotMat[1][3] + boneMat[1][2] * rotMat[1][1] + boneMat[2][2] * rotMat[1][2],-- right
            boneMat[2][3] * rotMat[1][2] + boneMat[3][3] * rotMat[1][3] + rotMat[1][1] * boneMat[1][3],
            0},
            {rotMat[2][3] * boneMat[3][1] + boneMat[2][1] * rotMat[2][2] + rotMat[2][1] * boneMat[1][1],
            boneMat[3][2] * rotMat[2][3] + boneMat[2][2] * rotMat[2][2] + boneMat[1][2] * rotMat[2][1],-- front 
            rotMat[2][1] * boneMat[1][3] + boneMat[3][3] * rotMat[2][3] + boneMat[2][3] * rotMat[2][2],
            0},
            {boneMat[2][1] * rotMat[3][2] + rotMat[3][3] * boneMat[3][1] + rotMat[3][1] * boneMat[1][1],
            boneMat[3][2] * rotMat[3][3] + boneMat[2][2] * rotMat[3][2] + rotMat[3][1] * boneMat[1][2],-- up
            rotMat[3][1] * boneMat[1][3] + boneMat[3][3] * rotMat[3][3] + boneMat[2][3] * rotMat[3][2],
            0},
            {offX * boneMat[1][1] + offY * boneMat[2][1] + offZ * boneMat[3][1] + boneMat[4][1],
            offX * boneMat[1][2] + offY * boneMat[2][2] + offZ * boneMat[3][2] + boneMat[4][2],-- pos
            offX * boneMat[1][3] + offY * boneMat[2][3] + offZ * boneMat[3][3] + boneMat[4][3],
            1}
        }
        setElementMatrix(element, finalMatrix)
        return true
    else
        setElementPosition(element, 0, 0, -1000)
        return false
    end
end

Example

Click to collapse [-]

Client

This example attaches a sniper rifle and a backpack to the local player.

local theGun = createObject(358, 0, 0, 0)
local thePara = createObject(371, 0, 0, 0)

local function onPedsProcessed()
attachElementToBone(theGun, localPlayer, 24, 0, 0, 0, 0, 0, 0)-- Attach the sniper model to bone #24 of the local player, no offset is needed because the default GTA weapon models fit perfectly fine into bone #24
attachElementToBone(thePara, localPlayer, 3, 0.1, -0.14, 0, math.rad(90), 0, 0)-- Attach parachute to bone #3 of the local player with a small position and rotation offset, so it looks nice
end
addEventHandler("onClientPedsProcessed", root, onPedsProcessed)

addTableChangeHandler » This function monitors the changes of a 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.
getKeyFromValueInTable » This function returns the key of the specified value in 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.
table.compare » 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.flip » This function returns the table from the last value to the first value, such as reflection.
table.fromString » This function converts string to a table.
table.getRandomRows » This function returns random rows from table.
table.map » 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.

ACL functions

aclGroupClone » This function clone a group to another group with/without ACLs and/or objects.
renameAclGroup » This function gives an existing ACL group a new name.
getPlayersInACLGroup » This function returns all players in an ACL group.
isPlayerInACL » This function checks if a player element is in an ACL group.

Account functions

getPlayerFromAccountName » This function is used to obtain a player by the name of his account.
isPlayerAccount » This function checks if the account is a valid player account (account exists and is not a guest account)

Camera functions

smoothMoveCamera » This function allows you to create a cinematic camera flight.
sCamera » The function creates a speed camera in-game, fines speeding vehicles, and notifies the driver and take money from player based on vehicle speed.

Colshape functions

createGarageColShape » This function creates a collision shape from the specified garage.

Cursor functions

getCursorMovedOn » This function checks in which way the cursor is currently moving.
setCursorCenteredOnRectangle » This functions will center the cursor inside a rectangle.

Drawing functions

dxDrawAnimWindow » This function draws an animated 2D window on the screen.
dxDrawBorderedRectangle » This is a function that will create a bordered rectangle.
dxDrawBorderedText » This is a function that will create a bordered text.
dxDrawDashedLine » This function draws a line with dashes.
dxDrawEditbox » This function draws a edit box across the screen - rendered for one frame. This should be used in conjunction with onClientRender in order to display continuously.
dxDrawGifImage » This function simulates the effect of a GIF image by using image sprites in 2D.
dxDrawImage3D » This function draws a 3D image in GTA world.
dxDrawImageOnElement » This function draws an image on any element.
dxDrawLinedRectangle » This is a function that will create a rectangle outline with dx lines.
dxDrawLoading » This function draws a loading bar on the screen.
dxDrawOctagon3D » This function creates a 3D Octagon
dxDrawPolygon » This function draws a custom polygon on the screen.
dxDrawProgressBar » This function simulates a progress bar drawed using DirectDraw.
dxDrawRectangle3D » This function draws a 3D rectangle in GTA world.
dxDrawRectangleOnPlayer » This function draws a 3D rectangle above the player.
dxDrawRing » This function draws a ring with dx lines.
dxDrawRombo » This function creates a Rhombus.
dxDrawSprite » This function draw a sprite in the 3D world.
dxDrawTextOnElement » This function draws a text on any element.
dxDrawTextOnRectangle » Esta funcion crea un rectangle con un texto dentro.
dxDrawTriangle » This is a function that will create a triangle with dx lines.
dxDrawBordered3DLine »This function creates a bordered area with 3D dx lines.
dxFade » This function fade-in or fade-out any dxDraw by gradually changing its alpha value.
dxGetFontSizeFromHeight » This function calculates the font size from given height.
dxGetRealFontHeight » This function calculates the height of a font.
wordWrap » This function breaks a long string into a table of separate lines limited to a specific length in pixels, for drawing separately.
CreateRectangle3D » This is a function that will create a 3d rectangle on the player screen.
getScreenStartPositionFromBox » This function helps with getting the correct position for your dx-effects.

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.
attachElementToBone » This function allows you to attach an element to ped bone accurately using new bone functions.
getElementDirectionCardialPoint » This function returns the direction of the element according to the wind rose.
getElementSpeed » This function returns the specified element's speed in m/s, km/h or mph.
getElementUsingData » This function returns table elements that contains the elements data with the given key and value.
getElementZoneFullName » This function allows you to retrieve the zone full name of a element.
getElementsInDimension » This function returns a table of elements that are in the specified dimension.
getElementsWithinMarker » This function returns a table of elements that are within a marker's collision shape.
getNearestElement » This function returns the nearest element (of a specific type) to a player.
getPositionInFrontOfElement » This function returns position in provided distance away from element, including element's rotation.
isElementInAir » This function checks if an element is in air or not.
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.
isElementPlayer » This function checks whether the element is a player or not.
isElementWithinAColShape » This function checks if an element is within a collision shape element.
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.

Events

onClientPlayerTimeChange » This code implements an event that is triggered when the player's real time change.
onPlayerZoneChange » This code implements an event that is triggered when the player enters a new area on the map.
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.
unbindControlKeys » This function allows you to unbind each key bound to a control individually. Use this function with bindControlKeys.
getBoundControls » This function returns a table of control names that are bound to the specified key.
isCommandHandlerAdded » This function allows you to check if a command is added or not in the respective resource.

Data functions

levenshtein » This function can be used to calculate the Levenshtein distance between two strings.
gregorianToJalali » This function converts gregorian date to jalali/shamsi date.
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.
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.
splitMultiple » This function improves the split function so that multiple characters can be used as the split at character.
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.
fixPersianString » This function returns a fixed sorted bilingual RTL for strings consisting of Farsi/Arabic and English.

GUI functions

centerWindow » This function centers a CEGUI window element responsively in any resolution.
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.
guiMoveElement » This function moves guiElement by/like using moveObject.
guiSetStaticImageMovable » This function allows you to move a static image like a gui window.

Comboboxes

guiComboBoxAdjustHeight » This function adjusts a CEGUI combobox element to have the correct height.

Gridlists

convertGridListToText » This function converts grid list contents to text.
getGridListRowIndexFromText » This function returns the GridList row index from the specified text.
guiGridListAddPlayers » This function add all online players to a grid list.
isTextInGridList » This function checks if some text exist or not in the GridList.
guiGridListGetColumnIDFromTitle » This function gets a gridlist's column ID from the column title.
guiGridListGetSelectedText » This function returns a string containing the inner text of a selected gridlist item.
guiGridListSetColumnNonSortable » This function makes a gridlist column become non-sortable.

Labels

guiLabelAddEffect » This function add an effects to the gui-label like (shadow, outline).

Marker functions

createMarkerAttachedTo » This function creates a marker that is attached to an element.

Math functions

reMap » Re-maps a number from one range to another.
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.
math.percentProgress » Returns a percentage progress from two specific values.
math.average » This function returns the simple arithmetic mean of multiple numbers.
math.absin » This function returns a formula representing the just positive half of a sine wave.

Map functions

assignLod » This function lets you conveniently generate and apply a LOD model to a mapping object.
getWorldPositionFromMapPosition » This function converts an F11 map position to world position.

Ped functions

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.
getPlayerNameFromID » This function will get the player name from the ID element data.
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.
isPedNearbyWall » This function checks if player/ped is nearby a objects like buildings or walls.
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.

Player functions

countPlayersInRange » This function returns the number of players that are within a certain range of the specified coordinates.
getPlayerPreviousAndNextWeapon » This function returns the player previous and next weapon.
getPlayersInRange » This function make a table of players within certain range.
isPlayerActuallyInVehicle » This function checks if a player is actually in a vehicle instead of just in the process of entering.
isPlayerHitByVehicle » This function cancels event when a element is hit by a vehicle.

Resource functions

getResourceScripts » This function returns a table of the resource scripts.
getResourceSettings » This function returns a table of the resource settings.
getResourceSize » This function returns the size of a specified resource in kB(kilobyte)
refreshResource » This function refreshes your resource if you changed any of the files
setResourcePriority » This function set resource download priority group.

Sound functions

isSoundFinished » This function checks if a sound element has finished.
stopSoundSlowly » This function stop your sound element slowly.

Browser functions

playVideo » This function plays a video on the screen.

Team functions

getTeamFromColor » This function returns a team element by the specified color.
getTeamWithFewestPlayers » This function returns a team element with least players of all the specified teams.

Vehicle functions

findEmptyCarSeat » This function finds you the first empty seat in a vehicle.
getNearestVehicle » This function gets the nearest vehicle to the specified player in a specified distance.
getRandomVehicle » This function gets a random vehicle.
getValidVehicleModels » This function returns a table of all valid vehicle models.
getVehiclesCountByType » This function returns the amount of vehicles by the given type as an integer value.
getVehicleTurnVelocityCenterOfMass» This function gets a vehicle's turn velocity relative to the vehicle's center or mass.
isVehicleDoubleExhaust » This function checks is exhaust vehicle double.
isVehicleEmpty » This function checks whether a vehicle is empty.
isVehicleOccupied » This function checks if a specified vehicle is occupied.
isVehicleOnRoof » This function checks whether vehicle is on roof.
isVehicleOnFire » This function checks if the vehicle is on fire or not.
isVehicleReversing » This function checks if a specified vehicle is moving backwards.
isVehicleUpgraded » This function checks is vehicle upgraded by upgrade ID.
setVehicleGravityPoint » This function sets a vehicle's gravity in the direction of a 3 dimensional coordinate with the strength specified.
setVehicleTurnVelocityCenterOfMass » This function sets a vehicle's turn velocity relative to the vehicle's center or mass.
setVehicleHandlingFromText » This function sets a vehicle's handling from text.
setVehicleWheelModel » This function changes the wheel model of the informed vehicle.

Weapon functions

getJetpackWeaponsEnabled » This function returns a table of enabled weapons usable on a jetpack.

Object functions

getDynamicDoorObjectOpenRatio » This function tells you how open a dynamic door is in a range from 0 to 1.
isElementObject » This function tells you if an element is an object or no.

XML functions

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

Engine functions

engineGetCOLsFromLibrary » This function gets the collision data from the col library.
engineLoadIMGContainer » This function loads the IMG container.

Utility

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.
getBanBySerial » This function returns the ban if the serial is banned.
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.
isLastExecuteInTimer » This function check if the execute is the last execute in the timer.
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.
debounce » This function is removing unwanted input noise.
listAllFiles » This function lists all files and subdirectories within a given directory and its subdirectories.

String functions

string.endsWith » This function checks if a string ends with other string.
string.startsWith » This function checks if a string starts with other string.
string.repetition » This function repeats a substring n times.