📚 World/Vehicle

载具Vehicle是世界玩法中的关键部分，使用相关API及事件可以高度自定义载具功能。

📒 Event

📘 OnVehicleSpawn( vehicle )

当载具被生成、被调用Respawn()时触发。

📘 OnVehicleExplode( vehicle, reason )

当载具爆炸、被摧毁时触发，有关Reason原因，请参考《世界资源实例汇总——伤害触发类型》，例如通过代码vehicle.Kill()则reason == 0。

📘 OnVehicleEntered( character, vehicle, seat )

当角色进入载具（或切换位置）时触发。

📘 OnVehicleExited( character, vehicle, seat )

当角色离开载具时触发。

📘 OnVehicleDamage( vehicle, damage, from, type, isImmunity, localHitPos )

当载具被尝试造成任何伤害时调用，如果造成伤害，会在OnVehicleHealthChange()后调用。

有关伤害类型Type，请参考《世界资源实例汇总——伤害触发类型》。

function OnVehicleDamage( vehicle: Vehicle, damage: int, from: Entity, type: int, isImmunity: bool, localHitPos: Vector )
/*
	vehicle：载具实例
	damage：伤害值
	from：造成伤害的对象（可能null，例如碰撞）
	type：伤害类型
	isImmunity：是否免疫伤害（如果为true，则表示没有造成伤害，可能被Immunity\Group拦截了）
	localHitPos：受击位置的本地坐标
*/

📘 OnVehicleHealthChange( vehicle, oldHealth, newHealth )

当载具血量发生任何改变时触发。

📒 Property

📘 vehicle.ID

获取载具序列ID（并非载具模型ID），每个实例ID是唯一的。

当之前的实例被销毁后，空闲的靠前ID将会被后续新实例重新使用（对于特殊情况，UUID是更合适的筛选选择）。

vehicle.ID: int

📘 vehicle.UUID

获取载具UUID，这是由一串较长的字符串组成的全局唯一文本ID（实例化时自动赋值，非持久化数据）。

vehicle.UUID: string

📘 vehicle.Model

获取载具模型ID（载具标识）。

vehicle.Model: int

📘 vehicle.Type

获取载具模型类型（如：汽车、船、飞行器等）。

vehicle.Type: int

📘 vehicle.Pos

设定载具位置坐标。

vehicle.Pos = Vector(0, 0, 0); //Vector

📘 vehicle.Forward

获取载具正前方向量。

vehicle.Forward: Vector

📘 vehicle.World

设置载具实例世界ID（不同世界将不可视\不可交互）。

vehicle.World = 0; //int

📘 vehicle.Group

设置载具实例组（这是一个Entity基类通用属性）。

相同组的载具及角色对象等无法造成伤害（包括攻击、撞击等），默认值0表示特殊组（无免伤和分组机制）。

vehicle.Group = 0; //int

📘 vehicle.Angle

设定载具方向角度，而不是三维角度。

vehicle.Angle = 0; //float

📘 vehicle.EulerAngle

设定载具三维角度。

vehicle.EulerAngle = Vector(0, 0, 0); //Vector

📘 vehicle.Health

设定载具生命值损耗。

vehicle.Health = 1000; //Vector

📘 vehicle.BoundSize

获取（只读）载具尺寸大小。

vehicle.BoundSize; //float

📘 vehicle.Immunity

设定载具的免疫属性（可叠加位Flag），同步修改VehicleData，设置为-1自动识别完全免疫（所有Flag相加后的结果）。

vehicle.Immunity = 0; //int
 
//可根据具体需求叠加属性
//示例：无视子弹和爆炸伤害，其他正常
vehicle.Immunity = 2 + 4; //或直接设为6

📘 vehicle.TyreImmunity

设定载具的轮胎受击免疫，激活后不会因常规攻击导致爆胎（vehicle.SetTyre(1)），默认为false。

注意：此属性不会影响vehicle.SetTyre()执行效果。

vehicle.TyreImmunity = false; //bool

📘 vehicle.DamageMultiplier

设定载具受损（被攻击）伤害倍数，默认为1.0。

vehicle.DamageMultiplier = 1.0; //float

📘 vehicle.Light

设定载具的灯光级别。

vehicle.Light = 0; //int

Type	说明
0	关闭
1	开启灯光
2	全部灯光（远光灯）

📘 vehicle.LightColor

设定载具的主要灯光颜色，此方法会修改当前载具所有灯光颜色。

vehicle.LightColor = Color(255, 255, 255); //Color

📘 vehicle.FlareLight

设定载具的特殊灯光开关（如：出租车头顶灯）。

此选项仅在部分载具生效，具体取决于载具Json是否包含Additions/Type=6项目（如：出租车）。

此选项拥有一个游戏规则vehicle_autoflarelight，可开关载具生成时是否自动激活此属性，默认开启。

vehicle.FlareLight = true; //bool

📘 vehicle.Horn

设定载具的喇叭开关。

vehicle.Horn = false; //bool

📘 vehicle.Alarm

设定载具的警报开关（如：特殊载具警报）。

此选项仅在部分载具生效，具体取决于载具Json是否包含Audios/Alarm!=0声音设定（如：消防车）。

vehicle.Alarm = false; //bool

📘 vehicle.Engine

设置载具引擎启动状态，默认关闭，当有玩家进入驾驶位后自动激活，并且不会在下车时主动取消。

vehicle.Engine = false; //bool

📘 vehicle.Locked

设置载具上锁状态，默认关闭，此属性目前只有逻辑作用，没有实际的功能。

vehicle.Locked = false; //bool

📘 vehicle.Color

设定载具的模型颜色。

此选项仅在支持的载具生效，具体取决于载具Json是否包含Extend/CustomColors颜色替换匹配。

《沙盘引擎》原生载具大多数都配置了此选项，因此可以直接通过代码修改载具颜色。

vehicle.Color = Color(255, 0, 0); //Color

📘 vehicle.PowerState

设置载具引擎驱动状态。

此属性仅用于特殊情况下使用，不建议常规情况下【写入】使用，但可放心用于【只读】判定方向使用。

vehicle.PowerState = 0;

Type	说明
0	无驱动
1	前进驱动
2	后退驱动

📘 vehicle.TurnState

设置载具引擎转向状态。

此属性仅用于特殊情况下使用，不建议常规情况下【写入】使用，但可放心用于【只读】判定方向使用。

vehicle.TurnState = 0;

Type	说明
0	无转向
1	向左转向
2	向右转向

📘 vehicle.Driver

获取载具当前的驾驶员角色（如无则返回null）。

vehicle.Driver: Character

📘 vehicle.Seat

获取载具的最大乘员数量。

vehicle.Seat: int

📘 vehicle.Seated

获取载具当前正在乘坐的乘员数量。

vehicle.Seated: int

📘 vehicle.Velocity

获取载具当前的同步物理速度。

vehicle.Velocity: Vector

📘 vehicle.Speed

获取载具的完整物理速度，并非引擎速度，也可根据此值进行载具速度比例换算。

vehicle.Speed: float

📘 vehicle.FixedSpeed

获取载具的修正后物理速度，与vehicle.Speed的区别在于，不会记录0.2及以下的速度（将自动变为0）。

因为在多数情况下，速度<=0.2时基本已经停止移动了，往往并不需要特别精确的数据。

vehicle.FixedSpeed: float

📘 vehicle.SpeedProgress

获取载具的完整速度百分比（0.0~1.0），取决于当前速度与最大速度。

vehicle.SpeedProgress: float

📘 vehicle.GhostMode

设置载具幽灵穿透模式开关（可穿透其他载具）。

vehicle.GhostMode = false; //bool

📘 vehicle.IsDamaged

获取载具是否已损毁（vehicle.Health <= 0）。

vehicle.IsDamaged: bool

📘 vehicle.IsInWater

获取载具是否在水中。

vehicle.IsInWater: bool

📘 vehicle.IsOnFire

获取载具是否正在被燃烧。

vehicle.IsOnFire: bool

📘 vehicle.IsDamageFire

获取载具是否正在损毁燃烧（损耗低于最低数值，即将燃烧爆炸）。

vehicle.IsDamageFire: bool

📘 vehicle.PowerTime

获取载具持续动力时间（PowerState 1 || PowerState -1），默认或非动力时值为0。

vehicle.PowerTime: float

📘 vehicle.WheelGrounded

获取载具全部车轮是否在地面上。

vehicle.WheelGrounded: bool

📘 vehicle.WheelLiftOffTime

获取载具上次任意车轮离地时间，即使vehicle.WheelGrounded回到地面，此属性不会重置为0。

vehicle.WheelLiftOffTime: float

📒 Static Function

📘 Vehicle.Create()

生成一个新的载具实例，Type类型样式参考《世界资源实例汇总》。

如果Type参数填写-1，则表示生成一个随机类型的载具。

function Vehicle.Create( type: int, pos: Vector, angle: float = 0, color: Color = null ): Vehicle

//在0点坐标处，建立一个类型为0、红色的载具实例
Vehicle.Create(0, Vector(0, 0, 0), 0, Color(255, 0, 0));

📘 Vehicle.Find()

寻找一个载具实例（通过ID），不存在则返回null。

function Vehicle.Find( id: int ): Vehicle

📘 Vehicle.FindByUUID()

寻找一个载具实例（通过UUID），不存在则返回null。

function Vehicle.FindByUUID( uuid: string ): Vehicle

📘 Vehicle.GetCount()

获取当前所有存在载具数量。

function Vehicle.GetCount(): int

📘 Vehicle.Get()

获取当前存在的指定索引载具，通常搭配GetCount()遍历使用。

function Vehicle.Get( index: int ): Vehicle

📘 Vehicle.SetSourceData()

设置指定型号载具最新数据，可用来修改同一Model载具的全部初始属性（当前场景有效）。

对于一些载具属性的调整，可能需要同时调整多个属性才会达到理想中的效果（例如：提升速度Acceleration的同时最好也提升MaxSpeed）。

注意：尽管此API允许修改任何存在的原生数据KeyPath，但并非所有改动都会生效（例如：轮胎、附件、座位等可能不会生效，也不建议修改，除非知道自己在做什么），此方法更适合修改Handling之类的载具基础属性。

注意：已存在的载具对象不会被更新，适用于执行此代码后创建的所有同类载具，如有更新全部需求可使用ResetSourceData\ResetAllSourceData。

function Vehicle.SetSourceData( model: int, keyPath: string, value: any )

Vehicle.SetSourceData(10, "Handling.Acceleration", 300); //将所有Model==10的载具预设【加速属性】修改为300

补充：更多有关VehicleData属性和节点信息，请参考《游戏载具扩展》内的Json节点。

📘 Vehicle.GetSourceData()

获取指定型号载具最新数据，如果目标节点不存在则返回null。

function Vehicle.GetSourceData( model: int, keyPath: string ): any

📘 Vehicle.ClearSourceData()

清空指定型号载具修改数据，恢复使用引擎\模组内最原始的数据（当前场景有效）。

注意：已存在的载具对象不会被更新，适用于执行此代码后创建的所有同类载具，如有更新全部需求可使用ResetSourceData\ResetAllSourceData。

function Vehicle.ClearSourceData( model: int )

📘 Vehicle.ResetSourceData()

重置刷新指定型号载具最新数据，全部更新使用最新的数据。

注意：通过vehicle.SetData独立修改的载具也会被覆盖更新。

function Vehicle.ResetSourceData( model: int )

📘 Vehicle.ResetAllSourceData()

重置刷新全部型号载具最新数据，全部更新使用最新的数据。

注意：通过vehicle.SetData独立修改的载具也会被覆盖更新。

function Vehicle.ResetAllSourceData()

📒 Function

📘 vehicle.Remove()

销毁当前载具实例。

function vehicle.Remove()

📘 vehicle.Damage()

以标准方式攻击当前载具实例，有关Reason原因，请参考《世界资源实例汇总——伤害触发类型》。

function vehicle.Damage( damage: int, from: Entity = null, reason: int = 0, localHitPos: Vector = Vector(0, 0, 0) )

📘 vehicle.AddForce()

增加一个当前对象的物理作用力，默认为本地坐标系（根据参数isLocal）。

function vehicle.AddForce( force: Vector, isLocal: bool = true )

let veh = Vehicle.Create(...);
veh.AddForce( Vector(0, 0.5, 5) ); //载具立即向前冲刺一段距离(z)

📘 vehicle.AddTurnForce()

增加一个当前对象的物理旋转力，默认为本地坐标系（根据参数isLocal）。

function vehicle.AddTurnForce( force: Vector, isLocal: bool = true )

let veh = Vehicle.Create(...);
veh.AddForce( Vector(0, 0.5, 0) ); //将载具抬起一点
veh.AddTurnForce( Vector(0, 10, 0) ); //载具横向旋转

📘 vehicle.SetOccupant()

设定载具指定位置的乘员，也可理解为让某个角色进入载具。

效果等同于character.SetVehicle()。

Vehicle.SetOccupant( instance: Character, seat: int = 0 )

let veh = Vehicle.Create(0, Vector(0, 0, 0));
let chara = Character.Find(0);
 
veh.SetOccupant(chara, 0); //设置玩家进入主驾驶位置（0），如果位置已存在乘员则不执行
veh.SetOccupant(null, 0); //踢出主驾驶位置，不再有角色驾驶（null）

📘 vehicle.GetOccupant()

获取载具某个乘客位置的角色（0表示驾驶员），未找到则返回null。

function vehicle.GetOccupant( seat: int ): Character

📘 vehicle.FindOccupant()

获取指定角色在载具中的位置索引，未找到则返回-1。

function vehicle.FindOccupant( character: Character ): int

📘 vehicle.Fix()

修复当前载具（恢复最大血量），如果载具已经爆炸则自动调用vehicle.Respawn()。

function vehicle.Respawn()

📘 vehicle.Kill()

立即完全破坏当前载具。

function vehicle.Kill()

📘 vehicle.Fire()

开始燃烧当前载具。

如果参数time < 0则表示持续燃烧。

function vehicle.Fire( time: float )

📘 vehicle.FireOver()

停止燃烧当前载具。

function vehicle.FireOver()

📘 vehicle.Respawn()

复活\完全重置当前载具，如果载具上有其他角色将会被弹出。

function vehicle.Respawn()

📘 vehicle.EjectAll()

弹出当前载具所有乘员\驾驶员（离开载具）。

function vehicle.EjectAll()

📘 vehicle.SetTyre()

设置载具某个轮胎的状态（如有轮胎）。

function vehicle.SetTyre( index: int, state: int )

状态	说明
0	默认，轮胎可见
1	爆胎，轮胎偏移（不受`vehicle.TyreImmunity`影响）
2	轮胎消失

📘 vehicle.GetTyre()

获取载具某个轮胎的状态（如有轮胎），如轮胎不存在则返回-1。

function vehicle.GetTyre( index: int )

📘 vehicle.ExistFlag()

获取载具Flags是否已激活指定的Flag。

function vehicle.ExistFlag( flag: int ): bool

vehicle.SetData("Flags", 4);
DLog(vehicle.ExistFlag(4)); //true

📘 vehicle.SetData()

设置当前载具原生数据（独立），可用来修改载具部分属性。