服务器实体 API

所有服务器实体读取都需要 game.entity.read。一个实体身份由以下内容共同组成：

sessionId + type + poolId + streamGeneration

池 ID 会被复用，因此不能只凭池 ID 重建 Handle，也不能在 entity.streamed_out 后继续使用旧 Handle。

取得和枚举实体

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

返回该精确身份当前对应的 Entity Handle；已经不在流送范围时返回 nil。 类型、ID 无效或世代不为正数时抛错。

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

返回 { items = EntityHandle[], nextId = integer|nil }。

参数	约束
type	player、vehicle、object、actor、pickup 或 text_label。
startId	扫描起始池 ID，默认 0。
limit	页面扫描上限 1..128，默认 64。
nextId	下一次调用的 startId；为 nil 时枚举结束。

items 可能少于 limit，因为只返回当前已流送且仍有效的实体。调用返回后 Handle 仍可能立即失效。

公共字段和方法

成员	类型	说明
type	string	上述实体类型。
poolId	integer	服务器池 ID。
streamGeneration	integer	当前流送身份世代。
sessionId	integer	所属会话。
handle:is_valid()	function -> boolean	安全检查是否失效。
handle:position()	function -> Vector3	当前坐标；失效时抛错。附着的 3D 文本返回服务器配置的偏移。

下列类型专用方法都不接收参数，Handle 失效或类型不匹配时抛错。

远程玩家

方法	返回值
name()	UTF-8 string。
npc()	boolean。
state()	on_foot、passenger、driver、wasted、spawned、none 或 unknown。
health()	上报的有限 number。
armor()	上报的有限 number。
vehicle_id()	车辆池 ID 或 nil；这不是 Vehicle Handle。

服务器车辆

方法	返回值
model()	模型 ID integer。
health()	有限 number。
velocity()	Vector3。
heading()	有限朝向 number。

服务器物体

方法	返回值
model()	模型 ID。
rotation()	Vector3。
moving()	boolean。
attachment()	{ type = "object" | "vehicle", poolId = integer }或nil。

Actor

方法	返回值
model()	模型 ID。
health()	有限 number。
invulnerable()	boolean。
heading()	有限朝向。

Pickup

方法	返回值
model()	模型 ID。
pickup_type()	拾取物类型 integer。

3D 文本

方法	返回值
text()	UTF-8 string。
color()	0xAARRGGBB 格式的 ARGB 整数。
draw_distance()	有限 number。
test_los()	是否测试视线的 boolean。
attachment()	{ type = "player" | "vehicle", poolId = integer }或nil。