Server entity API

Server entity access requires game.entity.read. A server entity identity is:

sessionId + type + poolId + streamGeneration

Pool IDs are reusable. Never reconstruct a Handle from only a pool ID or use a Handle after entity.streamed_out.

Acquire and enumerate

samp.entity.get(type, poolId, streamGeneration)

Returns the current Entity Handle, or nil when that exact identity is no longer streamed. Invalid types, IDs, or non-positive generations raise an error.

samp.entity.list(type [, startId [, limit]])

Returns { items = EntityHandle[], nextId = integer|nil }.

Argument	Contract
type	player, vehicle, object, actor, pickup, or text_label.
startId	Pool ID at which scanning begins; default 0.
limit	Maximum scan page, 1..128; default 64.
nextId	Pass into the next call; nil means enumeration is complete.

items may contain fewer than limit entries because only currently streamed and valid entities are returned. A Handle may become stale immediately after the call.

Common Handle fields and methods

Member	Type	Contract
type	string	Entity type listed above.
poolId	integer	Server pool ID.
streamGeneration	integer	Generation of this streamed identity.
sessionId	integer	Owning session.
handle:is_valid()	function -> boolean	Safe stale check.
handle:position()	function -> Vector3	Current position; raises if stale. For an attached text label this is its configured offset.

Every type-specific method below takes no arguments and raises if the Handle is stale or of the wrong type.

Remote player

Method	Return
name()	UTF-8 string.
npc()	boolean.
state()	on_foot, passenger, driver, wasted, spawned, none, or unknown.
health()	reported finite number.
armor()	reported finite number.
vehicle_id()	vehicle pool ID or nil. This is an ID, not a Vehicle Handle.

Server vehicle

Method	Return
model()	model ID integer.
health()	finite number.
velocity()	Vector3.
heading()	finite heading number.

Server object

Method	Return
model()	model ID integer.
rotation()	Vector3.
moving()	boolean.
attachment()	{ type = "object" | "vehicle", poolId = integer }ornil.

Actor

Method	Return
model()	model ID integer.
health()	finite number.
invulnerable()	boolean.
heading()	finite heading number.

Pickup

Method	Return
model()	model ID integer.
pickup_type()	pickup type integer.

3D text label

Method	Return
text()	UTF-8 string.
color()	ARGB color integer in 0xAARRGGBB form.
draw_distance()	finite number.
test_los()	line-of-sight test boolean.
attachment()	{ type = "player" | "vehicle", poolId = integer }ornil.