本地玩家与车辆 API

公共类型

lua

Vector3 = { x = number, y = number, z = number }

返回的位置和速度都是快照。Handle 方法使用冒号调用，例如 player:health()。玩家死亡、重生、断线或会话更换后，旧 Handle 都不能继续使用。

取得本地玩家

`samp.player.local_player()`

需要 game.player.read。玩家不可用时返回 nil，否则返回 Player Handle：

字段	类型	说明
`type`	`"player"`	Handle 类型。
`poolId`	`integer`	当前本地玩家池 ID。
`generation`	`integer`	本地玩家世代。
`sessionId`	`integer`	所属会话。

Player Handle 方法

签名	权限	返回值与约束
`player:is_valid()`	`game.player.read`	返回 `boolean`；Handle 失效时也不会仅因此抛错。
`player:position()`	`game.player.read`	返回 `Vector3`。
`player:health()`	`game.player.read`	返回 `number`。
`player:armor()`	`game.player.read`	返回 `number`。
`player:velocity()`	`game.player.read`	返回 `Vector3`。
`player:vehicle()`	`game.vehicle.read`	返回当前 Vehicle Handle 或 `nil`。
`player:set_health(value)`	`game.player.write`	有限数值 `0..1000`。
`player:set_armor(value)`	`game.player.write`	有限数值 `0..1000`。
`player:set_position(vector)`	`game.player.write`	每个分量为 `-100000..100000` 的有限数值。
`player:set_velocity(vector)`	`game.player.write`	每个分量为 `-1000..1000` 的有限数值。

写入方法无返回值，只能在托管回调中调用，包括事件、定时器、任务和菜单控件回调；入口文件求值阶段不可调用。draw.hud 本身属于事件回调，因此满足托管阶段，但它是每帧热点，不建议在其中进行玩法状态写入。除 is_valid() 外，任何方法在 Handle 失效时都会抛错。

lua

local player = samp.player.local_player()
samp.timer.after(500, function()
    if player ~= nil and player:is_valid() then
        samp.log.info(samp.format.number(player:health(), 1))
    end
end)

Vehicle Handle

player:vehicle() 只表示本地玩家当前乘坐的车辆。玩家离开或更换车辆、玩家世代变化、会话结束时，该 Handle 失效。

字段	类型
`type`	`"vehicle"`
`poolId`	`integer`
`generation`	`integer`
`sessionId`	`integer`

签名	权限	返回值与约束
`vehicle:is_valid()`	`game.vehicle.read`	`boolean`。
`vehicle:position()`	`game.vehicle.read`	`Vector3`。
`vehicle:health()`	`game.vehicle.read`	`number`。
`vehicle:velocity()`	`game.vehicle.read`	`Vector3`。
`vehicle:set_health(value)`	`game.vehicle.write`	有限数值 `0..10000`。
`vehicle:set_position(vector)`	`game.vehicle.write`	分量 `-100000..100000`。
`vehicle:set_velocity(vector)`	`game.vehicle.write`	分量 `-1000..1000`。

车辆写入方法同样只能在托管回调中调用，且无返回值。

API 1.1 玩家与载具快照

玩家 Handle 新增只读快照：

方法	返回值
`player:weapon()`	`{ id, ammo, clipAmmo, state }`；`state` 为 `ready`、`firing`、`reloading`、`out_of_ammo` 或 `melee_contact`。
`player:aim()`	`{ active, cameraMode, direction, position, aimZ, zoom }`；没有有限瞄准快照时返回 `nil`。
`player:motion()`	`{ activity, moveState, onGround, inAir, aiming, firing }`。
`player:skin()`	当前本地模型 ID。
`player:animation()`	当前同步动画编码；`0` 表示没有同步动画。
`player:task()`	`{ category, nativeType, nativeName, type, name }`；category 为 `none`、`driving`、`combat`、`movement`、`animation`、`interaction` 或 `other`。

对应变化由事件页中的 player.weapon_changed、player.aiming_changed、 player.motion_changed、player.skin_changed、player.animation_changed 和 player.task_changed 报告。

player:set_skin(id)、player:set_weapon(id, ammo) 和 player:set_ammo(id, ammo) 需要 game.player.write，只能在托管回调中调用，它们是可能被服务器同步或重生覆盖的一次性本地操作。

当前载具 Handle 新增 vehicle:state()、vehicle:seat() 和 vehicle:occupants()，需要 game.vehicle.read；occupants 只返回人数和容量，不暴露其他乘员对象。

vehicle:state() 返回 { model, heading, engineOn, lightsOn, sirenOn }；引擎无法提供有限朝向时 heading 为 nil。vehicle:seat() 在驾驶位返回 0，乘客位返回 1..n，不再处于该载具时返回 nil。vehicle:occupants() 返回 { driver, passengers, capacity, total }，不会暴露其他乘员对象。

本地玩家与车辆 API ​

公共类型 ​

取得本地玩家 ​

samp.player.local_player() ​

Player Handle 方法 ​

Vehicle Handle ​

API 1.1 玩家与载具快照 ​