- Documentation
- Peds
Category
Peds
All Lua functions and events in the Peds category, on the server and the client.
Server functions 73
canReturns the value set withPed Be Knocked Off Bike setPedCanBeKnockedOffBike.trueby default.getAn alias ofAnalog Control State getPedAnalogControlState, kept for compatibility with existing scripts. Returns the analog control strength 0-1.getReturns a list of every bone number the server understands (1-8, 21-26, 31-36, 41-44, 51-54). Useful for looping over bones or checking whether a number typed in a command is valid.Bone IDs getReturns the English name of the bone with the given number, e.g. 8 →Bone Name "Head", 25 →"RightHand", 2 →"Pelvis". Returnsfalsewhen the number does not exist.getReturns the world point a ped is aiming at, as reported by the player's game. ReturnsPed Aim Target falsewhen the game has not sent an aim point yet.getReturns the strength of a ped's analog control (0-1) set withPed Analog Control State setPedAnalogControlState. 0 means the control is not pressed.getReturns the element an NPC is currently attacking (set withPed Attack Target setPedAttackTargetor picked by an aggressive NPC after being hurt). Returnsfalsewhen the NPC is not fighting.getReturns the ped camera heading stored withPed Camera Rotation setPedCameraRotation(0 by default). It does not read the player's real camera.getReturns the element a ped is standing on, e.g. a vehicle or an object (when a player stands on a bus roof it returns the bus). ReturnsPed Contact Element falsewhen the ped stands on regular map ground.getChecks whether a ped's control is pressed according to the state set by scripts (Ped Control State setPedControlStateorsetPedAnalogControlState). It does not read the keys a player physically presses; usegetControlStateon the client for that.getReturns at once a list of every ped control that scripts set as pressed. Handy for debugging NPCs or for saving and later restoring their state.Ped Control States getReturns the fighting style stored withPed Fighting Style setPedFightingStyle(15 by default).getReturns the ped gravity stored withPed Gravity setPedGravity(0.008 by default).getReturns the point a ped should look at according to the lastPed Look At setPedLookAt, and the time (ingetTickCountunits) until which the look lasts. Returnsfalsewhen nothing was set.getEstimates how a ped is moving right now:Ped Move State stand,walk,powerwalk,jogorsprint. The result follows from the ped's speed, or from thewalk/sprintcontrol when a script pressed it. Useful e.g. for fatigue or footstep noise systems.getReturns the oxygen value stored withPed Oxygen Level setPedOxygenLevel(0-1000). 1000 by default. It does not read the in-game oxygen bar.getReturns the name of the most recently set task (across all layers), i.e. what the ped is doing right now according to scripts. ReturnsPed Simplest Task falsewhen the ped has no tasks.getReturns the element a ped is aiming at (a player, an NPC or a vehicle), as reported by the player's game. ReturnsPed Target falsewhen the ped is not aiming at any element.getTraces a ped's line of fire (fromPed Target Collision getPedTargetStarttogetPedTargetEnd) and returns the first point where it hits a building, vehicle, ped or object. Returnsfalsewhen nothing is in the way.getReturns the end point of a ped's line of fire: the target set withPed Target End setPedAimTarget, or when none, a point 100 m ahead of the ped in the direction it faces.getReturns the point where a ped's line of fire starts, i.e. the approximate muzzle position (same asPed Target Start getPedWeaponMuzzlePosition). Together withgetPedTargetEndit defines the bullet path.getReturns the task stored in a layer byPed Task setPedTask: its name, data and the moment (ingetTickCountunits) it was set. Returnsfalsewhen the layer is empty.getReturns a table of all of a ped's task layers as "layer → task name". Useful to see what scripts told an NPC to do.Ped Tasks getReturns a pedestrian's current appearance variant: the clothing number and the skin number (both 0-3). Returns 0, 0 when no variant was set.Ped Variant getReturns the voice bank type and name stored withPed Voice setPedVoice. Returnsfalsewhen no voice was set.getReturns the walking style stored withPed Walking Style setPedWalkingStyle(0 by default).getReturns the approximate muzzle position of a ped's weapon: a point about 45 cm in front of the ped at shoulder height, in the direction it faces. The server does not know the exact arm pose, so this approximation is good enough for effects and simple line-of-fire checks.Ped Weapon Muzzle Position getReturns every weapon a ped owns, together with its ammo. The first value is a list of weapon IDs (one per occupied slot), the second is a table "weapon ID → ammo count". Useful for saving a player's inventory to a database before they leave.Ped Weapons getReturns the slot number (0-12) of the weapon a ped is currently holding. The slot follows from the weapon type: e.g. handguns are slot 2, assault rifles slot 5. When the ped is holding fists it returns 0.Ped Weapon Slot giveGives a ped a weapon with ammo, exactly likePed Weapon giveWeapon(it is the same function under another name). If the ped already has a weapon in the same slot, it is replaced, while ammo for the same weapon adds up.isChecks whether an NPC is aggressive, i.e. whether it fights back on its own when someone hurts it. Aggression is set withPed Aggressive setPedAggressiveor the seventh argument ofcreatePed.isChecks whether a ped is aiming a weapon (holding the right mouse button or aiming on a gamepad). The state comes from the player's game and refreshes several times per second.Ped Aiming isReturns the value set withPed Bleeding setPedBleeding.falseby default.isReturns the choking state stored withPed Choking setPedChoking.falseby default. The game does not set this state by itself (tear gas does not change it), so it reflects only what scripts have set.isChecks whether any of a ped's task layers holds a task with the given name (stored byPed Doing Task setPedTaskor by functions such assetPedEnterVehicle, which storeenterVehicle).isReturns the value set withPed Foot Blood Enabled setPedFootBloodEnabled.falseby default.isChecks whether a ped is frozen, i.e. cannot move or fall. Freezing is set withPed Frozen setElementFrozen; the player's game applies it immediately.isReturns the value set withPed Headless setPedHeadless.falseby default.isChecks whether a ped is standing on the ground. ReturnsPed On Ground falsewhen the ped is jumping, falling, swimming, sitting in a vehicle or flying a jetpack. The state comes from the player's game.isChecks whether a ped is reloading right now. For a player it uses the state sent by their game, and it also returnsPed Reloading Weapon truefor the time set withsetPedReloadingWeapon. Useful e.g. to block actions while reloading.isReturns the value set withPed Targeting Marker Enabled setPedTargetingMarkerEnabled.trueby default.killInstantly kills a player or an NPC: sets health to zero and fires the death event (Ped onPlayerWastedfor a player,onPedWastedfor an NPC) with the given killer, weapon and body part. Scripts that count kills or hand out rewards therefore see the death as if someone really shot the ped. Nothing happens when the ped is already dead.playSends every player thePed Voice Line onClientPedVoiceevent with the ped and the line name. The function itself does not play any sound: a client script plays the line, e.g. withplaySound3Dfrom a resource sound file attached to the ped. This lets you build custom NPC dialogue heard by everyone nearby.removeInstantly takes a player or an NPC out of a vehicle and places them next to it, without the get-out animation. It firesPed From Vehicle onPlayerVehicleExitjust like a normal exit and blocks the player from getting back in for 3 seconds so the game does not put them back. Returnsfalsewhen the ped is not in a vehicle.resetRemoves the voice stored withPed Voice setPedVoice, i.e. returns the ped to its model's original voice. AfterwardsgetPedVoicereturnsfalse.setAn alias ofAnalog Control State setPedAnalogControlState, kept for older scripts. It takes the same arguments: ped, control name and strength 0-1.setTurns an NPC's aggression on or off. When an aggressive NPC gets hurt by someone (a player or another ped), it starts attacking the attacker on its own, as if a script calledPed Aggressive setPedAttackTarget. A non-aggressive NPC (the default) takes damage and does not react. Works only for NPCs (ped), not for players.setStores the point a ped should aim at. The value is for scripts:Ped Aim Target getPedTargetEnd(and indirectlygetPedTargetCollision) returns it, but the game itself does not turn the ped's weapon that way.setSets a ped's analog control within 0-1, i.e. how hard it is "pressed" (e.g. 0.5 = half throttle). The value is stored for scripts; in addition any value above 0 presses the regular control of that name and 0 releases it, so for NPCsPed Analog Control State forwards,backwardsandsprintwork in the game as withsetPedControlState(without graded strength).setSets a ped's armour (body vest) on a 0-100 scale. The value goes straight to the player's game, so the armour bar on screen changes immediately. Values outside the range are clamped to 0-100. This is the same function asPed Armor setPlayerArmour.setMakes an NPC attack a player or another ped: the NPC walks up and punches or shoots with the weapon in its hand until the target dies, disappears or a script stops the fight. The fight is simulated by one player's game (the target player or the nearest player in the same dimension), so the NPC behaves the same for everyone. PassingPed Attack Target nilorfalseends the fight. The fight also ends by itself when the target dies, leaves the server or is destroyed.setTurns a ped's bleeding on or off. A bleeding player leaves blood drops on the ground in their game while moving (like wounded peds in the game). Health does not drop from bleeding alone. For NPCs the value is stored for scripts and returned byPed Bleeding isPedBleeding.setStores a ped's camera heading in degrees (-360 to 360). In Trilogy Hub this is state for scripts returned byPed Camera Rotation getPedCameraRotation; the player's camera does not turn. Use the Camera functions such assetCameraMatrixto control a player's camera.setSets whether a ped can be knocked off a motorbike or bicycle in a crash. For a player the setting works in their game. For NPCs the value is stored and returned byPed Can Be Knocked Off Bike canPedBeKnockedOffBike.setStores on the server whether a ped is choking (e.g. from tear gas in GTA). In Trilogy Hub this is state for scripts: the server remembers it and returns it fromPed Choking isPedChoking, but the game does not play a coughing animation or take health yet. If choking should have effects, implement them in a script, e.g. a timer that lowers health plussetPedAnimationwith a coughing animation.setPresses or releases a virtual control of a ped, e.g.Ped Control State forwards(walk forward) orsprint. For NPCs every player's game carries outforwards,backwardsandsprint, so the ped walks or runs the way it faces; other control names are stored for scripts and returned bygetPedControlState. Names are the same as inbindKey/toggleControl(e.g.fire,jump,crouch,walk).setStores whether a ped should be shooting from a vehicle window (drive-by). In Trilogy Hub this is state for scripts returned byPed Doing Gang Driveby isPedDoingGangDriveby; the game does not switch the ped into drive-by mode based on it.setTakes a ped out of its vehicle on the server, records its "exit vehicle" task and sends every client thePed Exit Vehicle onClientPedExitRequestevent (ped, vehicle). The exit works likeremovePedFromVehicle, i.e. instantly, without the door animation. Returnsfalsewhen the ped is not in a vehicle.setSets a ped's melee fighting style (4 = standard, 5 = boxing, 6 = kung fu, 7 = knee to head, 15 = grab and kick, 16 = elbows). A player gets this style in their game (as after gym training). For NPCs the value is stored and returned byPed Fighting Style getPedFightingStyle. Values outside 4-16 are rejected.setStores whether a ped should leave bloody footprints (like after stepping in a pool of blood in GTA). In Trilogy Hub this is state for scripts returned byPed Foot Blood Enabled isPedFootBloodEnabled; the game does not draw footprints based on it.setStores the gravity of a single ped (0.008 by default, the same as world gravity). In Trilogy Hub this is state for scripts returned byPed Gravity getPedGravity; only the whole world's gravity set withsetGravityaffects how peds move.setStores whether a ped should be headless (like after a sniper shot in GTA). In Trilogy Hub this is state for scripts returned byPed Headless isPedHeadless; the game does not remove the head from the ped model yet.setTurns a ped toward the given point and remembers where and for how long it should look. The body turn happens immediately (the ped's heading changes), while the point, time and element are stored for scripts and returned byPed Look At getPedLookAt; the game does not additionally turn the head. To keep following a target with the eyes usesetPedFocus.setStores a ped's underwater oxygen on a 0-1000 scale (1000 = full lungs). In Trilogy Hub this is state for scripts returned byPed Oxygen Level getPedOxygenLevel; the in-game oxygen bar does not change. Values outside 0-1000 are rejected.setMarks a ped as reloading for the given time. It does not start any animation in the game; it is a flag for scripts read byPed Reloading Weapon isPedReloadingWeapon, e.g. when your own weapon system needs its own reload time. A time of 0 or less clears the flag.setSets a San Andreas stat for a ped within 0-1000. For a player the change reaches their game immediately, so e.g. raising a weapon skill (69-79) to 999 enables dual-wielding pistols, and stat 24 raises max health. The value is also stored on the server and returned byPed Stat getPedStat.setStores whether a targeting marker (the triangle above the locked-on person's head) should be visible above a ped's target. In Trilogy Hub this is state for scripts returned byPed Targeting Marker Enabled isPedTargetingMarkerEnabled; the game does not hide the marker based on it.trueby default.setStores a "task" for a ped in a chosen layer, e.g.Ped Task primary="enterVehicle", together with any data. It is a mechanism for scripts (e.g. your own NPC AI): the game does not carry out stored tasks by itself, but other scripts can read them withgetPedTask,getPedTasks,isPedDoingTaskandgetPedSimplestTask. Passingnilas the name clears the task from the layer.setSets a pedestrian's appearance variant: the set of clothes and the skin tone. Every ped model in the Definitive Edition has 4 clothing variants (0-3) and 4 skin variants (0-3); the change is visible to every player. An omitted argument is randomised, which is whyPed Variant createPedgives each NPC a random look. Works for NPCs and for players using a ped skin.setStores a voice bank type and name for a ped (e.g. typePed Voice "PED_TYPE_GEN"and name"VOICE_GEN_BBDYG1"). The value is for scripts and comes back fromgetPedVoice; the Definitive Edition game does not change the ped's lines based on it yet. Custom lines can be played withplayPedVoiceLineand a client script.setStores a ped's walking style as a San Andreas walk animation number (e.g. 54 default, 118 man, 121 gang member, 129 woman). In Trilogy Hub this is currently state for scripts returned byPed Walking Style getPedWalkingStyle; the game does not change the way the ped walks based on it yet. Values outside 0-138 are rejected.setSwitches the weapon in a ped's hand to the one in the given inventory slot, as if the player scrolled the mouse wheel. The slot must contain a weapon; an empty slot (except 0, i.e. fists) givesPed Weapon Slot false. The change reaches the player's game immediately.warpInstantly puts a player or an NPC into the chosen vehicle seat, without walking up and without the get-in animation. If the ped was in another car, it is taken out of it first. When the chosen seat is occupied by someone else, nothing happens and the function returnsPed Into Vehicle false. The player's game receives the order immediately, and the server blocks the player from getting out on their own for 3 seconds so the warp is not undone. An NPC in a vehicle always stays seated: while it is in the car, its body has no collision (only bullets hit it), walking and turning wait until it leaves the car, and if the game takes it out of the seat, the client puts it back at once.
Client functions 7
getReturns the number of skeleton bones a ped has in this version of the game (the Definitive Edition skeleton has more than the classic one). Returns 0 when the game has not shown any ped yet. Together withPed Bone Count getPedBoneNameit lets you list every bone.getConverts a game skeleton bone name to its index, which you can then pass toPed Bone Index By Name getPedBonePositionand similar functions. Some names repeat in the skeleton (there are e.g. two "Spine" bones); the second argument picks which occurrence to return.getTranslates a bone number used by existing scripts (e.g. 8 = head, 25 = right hand) into a bone index in the Definitive Edition skeleton. Useful when porting existing scripts that use bone numbers. ReturnsPed Bone Index For Mta falsewhen the bone has no counterpart in the new skeleton.getReturns a ped bone's 4x4 matrix for this frame, in the same layout asPed Bone Matrix getElementMatrix: row 1 = the bone's X axis, 2 = Y axis, 3 = Z axis, 4 = position. These are the same axes in whichattachElementToBoneapplies its offset and rotation, so the attach point isposition + X*dx + Y*dy + Z*dz. It is computed straight from the bone rotation in the engine, without Euler angles, so it keeps its precision at 90° turns.getReturns the name of the game skeleton bone with the given index (e.g.Ped Bone Name "Head","R_Hand"). The index is the bone's position in the Definitive Edition skeleton (0 togetPedBoneCount() - 1), not a number fromgetBoneIDs.getReturns the world rotation of a chosen skeleton bone of a ped, in degrees, exactly as it looks in the current animation frame. Works for peds visible in this game. Useful for attaching objects to a hand or the head so they rotate with it.Ped Bone Rotation getReturns both the position and rotation of a ped's bone at once (x, y, z, rx, ry, rz), which is faster than callingPed Bone Transform getPedBonePositionandgetPedBoneRotationseparately every frame. Values come from the current animation frame in this game.
Shared functions 29
createCreates a new NPC ped on the server (a pedestrian driven by the game, not by a player) and shows it right away to every player nearby. The ped gets 100 health, a random appearance variant (clothes and skin tone, seePed setPedVariant) and belongs to the resource that created it, so it disappears together with that resource onstop. Optionally it can be made aggressive straight away or told to attack a chosen target.getReturns the number of rounds in the weapon's current clip, i.e. how many shots are left before reloading. Without a slot it refers to the weapon in hand; with a slot, to the weapon in that inventory slot. On the client it always refers to the weapon in hand.Ped Ammo In Clip getReturns the block and name of the animation a ped is playing (set withPed Animation setPedAnimation). On the client, for peds in this game, it also returns the progress (0-1) and speed of an IFP animation. Returnsfalsewhen the ped is not playing any animation.getReturns a ped's armour (body vest) on a 0-100 scale. Armour absorbs damage before health, so a ped with full armour survives roughly twice as many shots. On the server the value comes from the last state sent by the player's game; on the client it is read straight from the game.Ped Armor getReturns the world position of a chosen skeleton bone of a ped, such as the head or a hand. On the client the position is exact and follows the animation (the bone is read from the game). The server does not know the ped's pose, so it returns an approximation: a fixed bone offset of a standing ped, rotated to match its heading. Bone numbers are the ones fromPed Bone Position getBoneIDs(e.g. 8 head, 25 right hand, 35 left hand); on the client a game bone index also works.getReturns the element an NPC keeps looking at (set withPed Focus setPedFocus) and whether it turns its head too. On the client it returns the local setting first, and the server's one when there is none. Returnsfalsewhen the NPC is not focused on anything.getReturns the vehicle a ped is sitting in (as the driver or a passenger). When the ped is on foot it returnsPed Occupied Vehicle false. It is the simplest way to find out what a player is driving, e.g. to repair or recolour their car.getReturns the seat number a ped occupies: 0 is the driver, 1 the front passenger, 2 and 3 the rear seats (buses and trains also use higher numbers). When the ped is on foot it returnsPed Occupied Vehicle Seat false. Useful when a command should work only for the driver.getReturns a San Andreas stat value for a ped, e.g. weapon skill, stamina, muscle or driving skill. Stats range from 0 to 1000 and affect gameplay (e.g. 69-79 are weapon skills; at 999 a ped dual-wields pistols). On the client, for your own ped the value is read from the game, for others from the server.Ped Stat getReturns all ammo for a weapon (clip plus reserve). Without a slot it refers to the weapon in hand; with a slot, to the weapon in that inventory slot. On the client it always refers to the weapon in hand.Ped Total Ammo getReturns the ID of the weapon a ped is holding (0 = fists), or of the weapon in the given inventory slot. Slots are weapon groups: 0 fists, 1 melee, 2 handguns, 3 shotguns, 4 sub-machine guns, 5 assault rifles, 6 rifles, 7 heavy weapons, 8 grenades, 9 sprays and extinguishers, 10 gifts, 11 goggles and parachute, 12 detonator. On the client it returns only the weapon in hand.Ped Weapon getReturns a list of every valid ped model number, i.e. the skins you can pass toValid Ped Models createPed,setElementModelorspawnPlayer. Numbers with no ped behind them in the game are left out. By default it also includes new ped models added by script withengineRequestModel. Useful for picking a random skin or building a character selection menu.isChecks whether a player or an NPC is damage proof (Ped Damage Proof setPedDamageProof).isChecks whether a player or an NPC is dead, i.e. has zero health or is lying dead waiting to respawn. On the server it uses the state reported by the player's game; on the client it uses the health seen in this game. A dead player comes back only throughPed Dead spawnPlayer.isReturns the value set withPed Doing Gang Driveby setPedDoingGangDriveby.falseby default.isChecks whether a ped is crouching (the crouch key). On the server the state comes from the player's game; on the client straight from the game. A crouching ped is a smaller target and moves slower.Ped Ducked isChecks whether a ped is sitting in any vehicle (in any seat). It also returnsPed In Vehicle falsewhile the ped is still getting in, before it takes the seat. When you need the vehicle itself, usegetPedOccupiedVehicle.isChecks whether a ped is on fire. On the server it returnsPed On Fire truewhen a script set it withsetPedOnFireor when the player's game reports they are really burning (e.g. they walked into fire or got hit by a flamethrower). On the client it reads the state straight from the game.isChecks whether a player is wearing a jetpack. The state comes from the player's game; for 2 seconds afterPed Wearing Jetpack setPedWearingJetpackthe server returns the value it has just set, before the game confirms the change.isChecks whether a model number is a real ped model that can be used inValid Ped Model createPed,setElementModelorspawnPlayer. It accepts the game's models (0-311 except empty numbers) and new peds added withengineRequestModel. Call it before applying a skin a player typed into a command.reloadMakes a ped reload the weapon it is holding, as if the reload key was pressed. On the server the order goes to the player's game; for an NPC it is stored as a reload request. On the client it only works for the local player.Ped Weapon setPlays an animation on a ped. The animation comes from a game animation block (e.g.Ped Animation ped,dancing,smoking) or from an IFP file loaded withengineLoadIFP. Calling it without a block stops the animation. On the server the animation reaches every player. On the client it only runs in this game: for the local player others see it through pose streaming; for a remote player the function returnsfalsebecause their appearance comes from their own game.setSeeks a ped's current animation to a chosen point (0 = start, 1 = end). On the server it applies to the animation set by the server'sPed Animation Progress setPedAnimationand reaches every player. On the client it applies to an IFP file animation playing on a ped in this game, and the animation name must match the current one.setChanges the playback speed of a ped's current animation: 1 = normal, 0.5 = half speed, 0 = paused. On the server it applies to the animation from the server'sPed Animation Speed setPedAnimation; on the client to an IFP file animation on a ped in this game.setMakes a player or an NPC damage proof (or removes it). A player takes no damage from other players (shots, hits, a knife from behind) or from the game (falls, fire, explosions, cars); game damage is undone and health comes back on the player at once. An NPC takes no damage in any game, and the server rejects hits on it. Everyone sees the state (Ped Damage Proof isPedDamageProofon both sides). On the client side it works only on NPCs and only for this player.setTells a ped to get into a vehicle the normal way, walking up and playing the door animation. On the client it only works for the local player: the player walks to a vehicle within 10 m and gets in (other peds givePed Enter Vehicle false). On the server it records the ped's task and sends every client theonClientPedEnterRequestevent (ped, vehicle, seat), which a client script can handle; the ped itself does not walk up yet on the server.setMakes an NPC keep looking at a chosen element: the ped turns its whole body toward it, optionally its head too, and follows it as it moves. On the server everyone sees it. On the client it only works in this game and overrides the server's setting;Ped Focus nilbrings back what the server set. Useful for shopkeepers, guards and NPCs in cutscenes.setSets a ped on fire or puts it out. A player really starts burning in their game: the fire is visible and they lose health until the fire goes out by itself or untilPed On Fire setPedOnFire(player, false). For NPCs the value is stored for scripts.isPedOnFirefor a player shows whether their ped is really burning.setGives a player a jetpack or takes it away. The order goes straight to the player's game, so they can take off immediately. Works only for players (not NPCs); a jetpack cannot be put on while the player is in a vehicle.Ped Wearing Jetpack