本地玩家与车辆 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 ​

公共类型 ​

取得本地玩家 ​

samp.player.local_player() ​

Player Handle 方法 ​