World and entities

Player characters (peds), objects and vehicles in the game world: create, move and delete them. Positions are in meters, headings in degrees. Provided by the game (or gampeon-server with its placeholder world).

GetPlayerPed

GetPlayerPed(playerSrc) --> integer

A player’s character (ped). Server and client.

On the server, pass the player ID (source). On the client, pass -1 or PlayerId() for your own character; other players follow later. Returns 0 while the player has no character, for example right after joining.

Parameter	Type	Description
playerSrc	string|integer	Server: player ID (source). Client: -1 or PlayerId().

Returns

• integer: Entity handle of the ped, or 0.

RegisterCommand('pos', function(source)
  local ped = GetPlayerPed(source)
  print(GetPlayerName(source) .. ' is at ' .. GetEntityCoords(ped))
end)

Compared to FiveM: Same as in FiveM. Server and client have their own handles for the same entity, so do not send handles in events.

PlayerPedId

PlayerPedId() --> integer

Your own character (ped) on the client. Client only.

Returns

• integer: Entity handle of your ped, or 0 before it spawned.

local coords = GetEntityCoords(PlayerPedId())
print(('I am at %.1f, %.1f, %.1f'):format(coords.x, coords.y, coords.z))

Compared to FiveM: Same as in FiveM.

DoesEntityExist

DoesEntityExist(entity) --> boolean

Check if an entity handle still points to an entity. Server and client.

Parameter	Type	Description
entity	integer	Entity handle, for example from GetPlayerPed. 0 means no entity.

Returns

• boolean: true if the entity exists.

local ped = GetPlayerPed(source)
if DoesEntityExist(ped) then
  print('ped exists')
end

Compared to FiveM: Same as in FiveM.

GetEntityCoords

GetEntityCoords(entity) --> vector3

Position of an entity in meters. Server and client.

Parameter	Type	Description
entity	integer	Entity handle, for example from GetPlayerPed. 0 means no entity.

Returns

• vector3: Position in meters. vector3(0, 0, 0) for unknown entities.

local a = GetEntityCoords(GetPlayerPed(source))
local b = vector3(100.0, 20.0, 1.0)
if #(a - b) < 5.0 then
  print('near the shop')
end

Compared to FiveM: Same as in FiveM: meters, z is up. The axes follow the GAMPEON map, so coordinates from GTA maps do not carry over. Extra arguments (alive) are ignored.

GetEntityHeading

GetEntityHeading(entity) --> number

Direction an entity faces, in degrees. Server and client.

Parameter	Type	Description
entity	integer	Entity handle, for example from GetPlayerPed. 0 means no entity.

Returns

• number: 0 up to 360. 0 faces +x, 90 faces +y. 0 for unknown entities.

Compared to FiveM: Degrees from 0 to 360 like in FiveM, but measured like the Unreal yaw (Rotation Z in the editor): 0 faces +x and the angle grows towards +y. For directions use GetEntityForwardVector instead of GTA heading math.

GetEntityForwardVector

GetEntityForwardVector(entity) --> vector3

Unit vector in the direction an entity faces. Server and client.

Parameter	Type	Description
entity	integer	Entity handle, for example from GetPlayerPed. 0 means no entity.

Returns

• vector3: Length 1, z is 0. Follows GetEntityHeading: heading 0 gives (1, 0, 0), 90 gives (0, 1, 0). (0, 0, 0) for unknown entities.

local ped = GetPlayerPed(source)
local inFront = GetEntityCoords(ped) + GetEntityForwardVector(ped) * 2.0

Compared to FiveM: Same as in FiveM. Use it instead of sin and cos of the heading: GAMPEON headings are measured like the Unreal yaw, so GTA heading math gives other directions.

GetEntityForwardX

GetEntityForwardX(entity) --> number

X part of GetEntityForwardVector. Server and client.

Parameter	Type	Description
entity	integer	Entity handle, for example from GetPlayerPed. 0 means no entity.

Returns

• number: -1 up to 1. 0 for unknown entities.

Compared to FiveM: Same as in FiveM.

GetEntityForwardY

GetEntityForwardY(entity) --> number

Y part of GetEntityForwardVector. Server and client.

Parameter	Type	Description
entity	integer	Entity handle, for example from GetPlayerPed. 0 means no entity.

Returns

• number: -1 up to 1. 0 for unknown entities.

Compared to FiveM: Same as in FiveM.

GetEntityVelocity

GetEntityVelocity(entity) --> vector3

Speed and direction of an entity in meters per second. Server and client.

Parameter	Type	Description
entity	integer	Entity handle, for example from GetPlayerPed. 0 means no entity.

Returns

• vector3: Velocity in meters per second. #velocity is the speed.

local speed = #GetEntityVelocity(GetPlayerPed(source))
print(('%.1f m/s'):format(speed))

Compared to FiveM: Same as in FiveM.

GetEntityType

GetEntityType(entity) --> integer

Kind of entity. Server and client.

Parameter	Type	Description
entity	integer	Entity handle, for example from GetPlayerPed. 0 means no entity.

Returns

• integer: 0 = no entity, 1 = ped, 2 = vehicle, 3 = object.

Compared to FiveM: Same numbers as in FiveM. Peds come from players; objects come from CreateObject. Vehicles need vehicle models, which the game does not have yet.

SetEntityCoords

SetEntityCoords(entity, x, y?, z?)

Teleport an entity to a position in meters. Server only.

The server owns the world, so only server scripts move entities. Players see the new position through the normal replication. Coordinates must be finite and within 1,000,000 meters. For a character the position is the middle of its body, about 0.9 meters above its feet, so add that to the ground height (GetEntityCoords returns the same point).

Parameter	Type	Description
entity	integer	Entity handle, for example from GetPlayerPed. 0 means no entity.
x	number|vector3	x in meters, or a vector3 with x, y and z.
y (optional)	number	y in meters (not needed with a vector3).
z (optional)	number	z in meters (not needed with a vector3).

RegisterCommand('tpspawn', function(source)
  SetEntityCoords(GetPlayerPed(source), vector3(0.0, 0.0, 2.0))
end, true)

Compared to FiveM: Like in FiveM, but server only for now. The flags after z (alive, deadFlag, ragdollFlag, clearArea) are ignored. Unknown handles do nothing.

SetEntityHeading

SetEntityHeading(entity, heading)

Turn an entity to face a direction in degrees. Server only.

Parameter	Type	Description
entity	integer	Entity handle, for example from GetPlayerPed. 0 means no entity.
heading	number	Degrees. Any value works, it is wrapped to 0 up to 360. 0 faces +x, 90 faces +y.

SetEntityHeading(GetPlayerPed(source), 90.0)

Compared to FiveM: Like in FiveM, but server only for now and measured like the Unreal yaw (see GetEntityHeading).

GetEntityModel

GetEntityModel(entity) --> integer

Model of an entity as a hash. Server and client.

Parameter	Type	Description
entity	integer	Entity handle. 0 means no entity.

Returns

• integer: GetHashKey of the model name, 0 for player characters and missing entities.

if GetEntityModel(obj) == GetHashKey('prop_cube') then
  print('a cube')
end

Compared to FiveM: Same as in FiveM, but player characters have no model hash yet (0).

IsModelValid

IsModelValid(model) --> boolean

Check if the game knows a model that CreateObject or CreateVehicle can create. Server and client.

Parameter	Type	Description
model	string|integer	Model name such as “prop_cube” or its hash from GetHashKey.

Returns

• boolean: true if the model exists.

print(IsModelValid('prop_cube'))

Compared to FiveM: Same idea as in FiveM, but GAMPEON has its own models instead of the GTA ones. Built in: prop_cube, prop_sphere, prop_cylinder, prop_cone and prop_plane.

IsModelAVehicle

IsModelAVehicle(model) --> boolean

Check if a model is a vehicle model. Server and client.

Parameter	Type	Description
model	string|integer	Model name such as “prop_cube” or its hash from GetHashKey.

Returns

• boolean: true for vehicle models, false for objects and unknown models.

Compared to FiveM: Same as in FiveM.

CreateObject

CreateObject(model, x, y, z, isNetwork?, netMissionEntity?, doorFlag?) --> integer

Create an object in the world for every player. Server only.

The object belongs to your resource and is deleted when the resource stops. It has physics but sleeps until something hits it, like props in FiveM; FreezeEntityPosition holds it in place. A resource may have 1000 entities at once. Unknown models return 0 and write a warning to the log.

Parameter	Type	Description
model	string|integer	Model name such as “prop_cube” or its hash from GetHashKey.
x	number	Position in meters (or a vector3 here and leave out y and z).
y	number	Meters.
z	number	Meters, up.
isNetwork (optional)	boolean	Ignored: objects from the server always exist for every player.
netMissionEntity (optional)	boolean	Ignored.
doorFlag (optional)	boolean	Ignored.

Returns

• integer: Entity handle, 0 if it could not be created.

local c = GetEntityCoords(GetPlayerPed(source))
local box = CreateObject('prop_cube', c.x + 2.0, c.y, c.z, true, true, false)
FreezeEntityPosition(box, true)

Compared to FiveM: Same arguments as in FiveM, but server only for now and with GAMPEON models. The object is not pushed to the ground; it is placed at the position you give.

CreateObjectNoOffset

CreateObjectNoOffset(model, x, y, z, isNetwork?, netMissionEntity?, doorFlag?) --> integer

Same as CreateObject. Server only.

Parameter	Type	Description
model	string|integer	Model name such as “prop_cube” or its hash from GetHashKey.
x	number	Position in meters (or a vector3 here and leave out y and z).
y	number	Meters.
z	number	Meters, up.
isNetwork (optional)	boolean	Ignored.
netMissionEntity (optional)	boolean	Ignored.
doorFlag (optional)	boolean	Ignored.

Returns

• integer: Entity handle, 0 if it could not be created.

Compared to FiveM: In FiveM the two differ in how the position is offset; GAMPEON places both at the exact position.

CreateVehicle

CreateVehicle(model, x, y, z, heading?, isNetwork?, netMissionEntity?) --> integer

Create a vehicle in the world for every player. Server only.

Belongs to your resource and is deleted when it stops. The game has no vehicle models yet, so for now this returns 0 and writes a warning to the log.

Parameter	Type	Description
model	string|integer	Model name such as “prop_cube” or its hash from GetHashKey.
x	number	Position in meters (or a vector3 here and leave out y and z).
y	number	Meters.
z	number	Meters, up.
heading (optional)	number	Degrees, 0 faces +x, 90 faces +y.
isNetwork (optional)	boolean	Ignored: vehicles from the server always exist for every player.
netMissionEntity (optional)	boolean	Ignored.

Returns

• integer: Entity handle, 0 if it could not be created.

Compared to FiveM: Same arguments as in FiveM, but server only for now and with GAMPEON models.

DeleteEntity

DeleteEntity(entity)

Delete an entity that a script created. Server only.

Works for objects and vehicles from CreateObject and CreateVehicle of any resource. Player characters cannot be deleted.

Parameter	Type	Description
entity	integer	Entity handle. 0 does nothing.

DeleteEntity(box)

Compared to FiveM: Same as in FiveM, but server only for now.

FreezeEntityPosition

FreezeEntityPosition(entity, toggle)

Hold an entity in place without physics, or let it move again. Server only.

Parameter	Type	Description
entity	integer	Entity handle.
toggle	boolean	true holds it in place, false turns physics back on.

FreezeEntityPosition(box, true)

Compared to FiveM: Same as in FiveM, but server only for now and only for entities that scripts created.