Lua API 2 概览
中文 | English
在仓库根目录运行以下命令,用本机 Unity MCP 回放本页示例。
python Docs/Manual/manual/tools/tutorials.py run lua-api2-overview
API 2 提供载具装配完成回调、可自动结束的事件订阅,以及战场查询、雷达、武器和载具状态接口。第一次写脚本时,先完成 Lua Hello World 中的文件导入和挂载,再把下面的脚本挂到测试载具上。
1. 检查版本并等待载具装配
早期客户端的 GAME_API_VERSION 可能为 nil。用 (GAME_API_VERSION or 1) >= 2 判断,并在真正调用 API 2 的入口守住版本分支。当前客户端上,在车库加载这台车时应只看到一次 Ready,进入战斗后新实例会再输出一次。
Behavior()
Property = {}
local MyBehavior = class("MyBehavior")
function MyBehavior:OnStarted()
self.supportsAPI2 = (GAME_API_VERSION or 1) >= 2
if not self.supportsAPI2 then
print("[MyBehavior] This mod needs API 2")
end
end
function MyBehavior:OnVehicleReady(vehicle)
if not self.supportsAPI2 then return end
self.vehicle = vehicle
print("[MyBehavior] Ready: " .. VehicleAPI.GetDisplayName(vehicle))
if VehicleAPI.IsGarage(vehicle) then
self.script:SetUpdateEnabled(false)
return
end
self.script:SetUpdateInterval(0.2)
end
function MyBehavior:OnUpdated(dt)
if not self.vehicle then return end
-- dt 是距上次调用的秒数。把战斗中的定时逻辑放在这里。
end
return MyBehavior
点击展开 MCP 操作点击收起 MCP 操作
[
{
"tool": "invoke",
"arguments": {
"path": "static:ShanghaiWindy.Core.API.GameAPI/GetApiVersion",
"args": []
},
"expect": {
"contains": "(Int32) 2"
}
},
{
"tool": "invoke",
"arguments": {
"path": "static:ShanghaiWindy.Core.AssetBundleManager/LuaEnv/DoString",
"args": [
"local function api2(v) return (v or 1) >= 2 end\nassert(not api2(nil) and not api2(1) and api2(2) and api2(3))\nassert(CS.ShanghaiWindy.Core.API.GameAPI.GetApiVersion() == 2)\nreturn \"API version verified\"\n",
"manual-api-version",
"null"
]
},
"expect": {
"contains": "API version verified"
}
},
{
"tool": "invoke",
"arguments": {
"path": "static:ShanghaiWindy.Core.AssetBundleManager/LuaEnv/DoString",
"args": [
"local function verify(version, garage)\n local GAME_API_VERSION = version\n local function Behavior() end\n local function class() return {} end\n local function print() end\n local vehicle = {}\n local VehicleAPI = {\n GetDisplayName = function(target) assert(target == vehicle); return \"Example\" end,\n IsGarage = function() return garage end,\n }\n local seed = {interval = 0, enabled = true}\n function seed:SetUpdateEnabled(enabled) self.enabled = enabled end\n function seed:SetUpdateInterval(interval) self.interval = interval end\n local object = (function()\nBehavior()\nProperty = {}\n\nlocal MyBehavior = class(\"MyBehavior\")\n\nfunction MyBehavior:OnStarted()\n self.supportsAPI2 = (GAME_API_VERSION or 1) >= 2\n if not self.supportsAPI2 then\n print(\"[MyBehavior] This mod needs API 2\")\n end\nend\n\nfunction MyBehavior:OnVehicleReady(vehicle)\n if not self.supportsAPI2 then return end\n self.vehicle = vehicle\n print(\"[MyBehavior] Ready: \" .. VehicleAPI.GetDisplayName(vehicle))\n if VehicleAPI.IsGarage(vehicle) then\n self.script:SetUpdateEnabled(false)\n return\n end\n self.script:SetUpdateInterval(0.2)\nend\n\nfunction MyBehavior:OnUpdated(dt)\n if not self.vehicle then return end\n -- dt is the time in seconds since the previous call. Run periodic battle logic here.\nend\n\nreturn MyBehavior\n end)()\n object.script = seed\n object:OnStarted()\n object:OnVehicleReady(vehicle)\n object:OnUpdated(0.2)\n assert(object.supportsAPI2 == ((version or 1) >= 2))\n assert(seed.enabled == (not object.supportsAPI2 or not garage))\n assert(seed.interval == ((object.supportsAPI2 and not garage) and 0.2 or 0))\nend\nverify(nil, false)\nverify(1, false)\nverify(2, true)\nverify(3, false)\n\nlocal vehicle, weapon, self = {}, {}, {script = {}}\nlocal ammo, callback = 7\nlocal WeaponAPI = {\n GetWeapon = function(target, index) assert(target == vehicle and index == 0); return weapon end,\n GetTotalAmmo = function(target) assert(target == weapon); return ammo end,\n OnAmmoChanged = function(owner, target, fn)\n assert(owner == self.script and target == weapon)\n callback = fn\n return {IsActive = true}\n end,\n}\nlocal weapon = WeaponAPI.GetWeapon(vehicle, 0)\nif weapon then\n self.ammo = WeaponAPI.GetTotalAmmo(weapon)\n self.ammoSubscription = WeaponAPI.OnAmmoChanged(self.script, weapon, function()\n self.ammo = WeaponAPI.GetTotalAmmo(weapon)\n end)\nend\nassert(self.ammo == 7 and self.ammoSubscription.IsActive)\nammo = 6\ncallback()\nassert(self.ammo == 6)\nreturn \"Lifecycle and ammo examples verified with Lua stubs\"\n",
"manual-api-overview-samples",
"null"
]
},
"expect": {
"contains": "Lifecycle and ammo examples verified with Lua stubs"
}
}
]
2. 选择回调和更新间隔
| 回调 | 触发时机 |
|---|---|
OnStarted() |
脚本实例启动。载具此时可能仍在装配。 |
OnVehicleReady(vehicle) |
所属载具装配完成后触发一次。若脚本启动时载具已经装好,此回调紧接启动流程执行。车库也会触发。独立地图和特效行为没有所属载具时不会收到。 |
OnUpdated(dt) |
默认每帧一次,也可调整间隔。dt 为距上次调用的累计秒数。 |
OnVehicleDestroyed(vehicle) |
所属载具被击毁时,可触发临终动画或清理。 |
OnDestroyed() |
行为实例销毁时,可释放脚本自己管理的资源。随后自动清理以该行为为所有者的订阅。 |
载具数据中的坦克、炮塔和坦克武器 Lua 行为可在 OnStarted 读取注入的 self.vehicle。炮塔行为另有 self.turretController,坦克武器行为另有 self.tankFire,飞机武器行为有 self.flightFire。装配时序见 载具初始化时序。
| 方法 | 用法 |
|---|---|
self.script:GetVehicle() |
获取并缓存所属坦克、飞机或步兵。无所属载具时返回 nil。 |
self.script:SetUpdateInterval(seconds) |
拉长 OnUpdated 间隔。传 0 恢复每帧调用。 |
self.script:SetUpdateEnabled(false) |
停止 OnUpdated,事件回调与 OnGUI 仍可运行。传 true 恢复。 |
3. 订阅状态变化
在 OnVehicleReady 中取得具体武器,再订阅弹药变化。用 OnAmmoChanged 通知 UI 更新,UI 初次显示也主动读取一次弹药。把下面代码接到上面示例的战斗分支,再在 OnGUI 中绘制 self.ammo。
local weapon = WeaponAPI.GetWeapon(vehicle, 0)
if weapon then
self.ammo = WeaponAPI.GetTotalAmmo(weapon)
self.ammoSubscription = WeaponAPI.OnAmmoChanged(self.script, weapon, function()
self.ammo = WeaponAPI.GetTotalAmmo(weapon)
end)
end
self.script是订阅所有者。行为销毁或关联目标载具被移除时,订阅会结束。- 要提前停止,就检查订阅对象是否存在,再调用
sub:Dispose()。重复调用安全。sub.IsActive表示是否仍处于订阅状态。 - 模式脚本或依赖库可以传
nil作为所有者。订阅有目标载具时跟随该目标清理,既没有所有者也没有目标的订阅在退出游戏模式时清理。 - 订阅的回调连续抛错 10 次后停止执行。查看游戏日志里的事件名和脚本上下文,定位出错行。
4. 查接口与处理返回值
| 接口 | 用途和常用方法 |
|---|---|
VehicleAPI |
载具身份、状态、战场查询和事件。GetContext、IsGarage、IsLocalPlayer、IsBot、IsRemote、IsAlive、GetTeam、IsEnemy、GetDisplayName、GetGuid、GetVelocity、GetSpeedKmh、GetAimPoint、CreateQuery、OnVehicleSpawned、OnVehicleKilled。 |
RadarAPI |
地面防空和机载雷达。TryGetRadar、IsActive、GetWorkMode、GetScanAzimuth、GetContactCount、GetContact、GetContactWorldAzimuth、GetLockedTarget、TryLock、Unlock、OnLockChanged、OnThreat。 |
WeaponAPI |
武器、弹种、装填、提前量和事件。GetWeaponCount、GetWeapon、GetAmmo、GetTotalAmmo、IsReloaded、GetReloadProgress、GetReloadTime、GetMuzzle、GetShellSpeed、PredictLead、OnFired、OnAmmoChanged、OnReloaded、OnHit、OnKill。 |
TankAPI |
炮塔和引擎。GetTurretCount、GetTurretTransform、GetGunTransform、GetEngineState。 |
FlightAPI |
飞行和起落架。IsOnGround、IsGearDown、GetAirspeedKmh、GetAltitude、GetThrottle、IsEngineRunning、OnGearChanged。 |
InternalModuleAPI |
模块状态。GetInternalModule、IsDestroyed、GetHitPointRatio、OnStateChanged、OnDamaged、OnRepaired。 |
CameraAPI |
玩家相机。GetCameraMode、IsZoomed、GetLockTarget。 |
TransformAPI |
模型节点查找。FindDeep、FindAllDeep。 |
BuffAPI |
用 CreateValueBuff 创建可修改数值的 buff。 |
TimeAPI |
用 IsPaused 查询是否暂停。 |
在 ShanghaiWindy.Core.API 命名空间下查函数签名,或在 VS Code 安装 EmmyLua 读取 SDK 提示。C# 数组和目标序号从 0 开始。读取 TryGetRadar、GetContact 等带 out 值的方法时,在 Lua 先检查第一个布尔返回值。查询失败时按签名处理 nil、false、0 等值。距离通常用米、角度用度。速度用各接口注明的单位,例如 GetSpeedKmh 返回千米/时。
联机查询会按团队可见性过滤敌方载具。雷达联系人还受探测判定约束。控制雷达时请使用玩家当前控制的载具,并检查 TryLock 等控制方法的返回值。
点击展开 MCP 操作点击收起 MCP 操作
[
{
"tool": "inspect",
"arguments": {
"path": "static:ShanghaiWindy.Core.API.WeaponAPI"
},
"expect": {
"contains": "OnAmmoChanged"
}
},
{
"tool": "inspect",
"arguments": {
"path": "static:ShanghaiWindy.Core.API.VehicleAPI"
},
"expect": {
"contains": "CreateQuery"
}
},
{
"tool": "inspect",
"arguments": {
"path": "static:ShanghaiWindy.Core.API.RadarAPI"
},
"expect": {
"contains": "GetContactWorldAzimuth"
}
},
{
"tool": "inspect",
"arguments": {
"path": "static:ShanghaiWindy.Core.API.GameAPI"
},
"expect": {
"contains": "GetApiVersion"
}
},
{
"tool": "inspect",
"arguments": {
"path": "static:ShanghaiWindy.Core.API.TankAPI"
},
"expect": {
"contains": "GetEngineState"
}
},
{
"tool": "inspect",
"arguments": {
"path": "static:ShanghaiWindy.Core.API.FlightAPI"
},
"expect": {
"contains": "OnGearChanged"
}
},
{
"tool": "inspect",
"arguments": {
"path": "static:ShanghaiWindy.Core.API.InternalModuleAPI"
},
"expect": {
"contains": "OnStateChanged"
}
},
{
"tool": "inspect",
"arguments": {
"path": "static:ShanghaiWindy.Core.API.CameraAPI"
},
"expect": {
"contains": "GetCameraMode"
}
},
{
"tool": "inspect",
"arguments": {
"path": "static:ShanghaiWindy.Core.API.TransformAPI"
},
"expect": {
"contains": "FindAllDeep"
}
},
{
"tool": "inspect",
"arguments": {
"path": "static:ShanghaiWindy.Core.API.BuffAPI"
},
"expect": {
"contains": "CreateValueBuff"
}
},
{
"tool": "inspect",
"arguments": {
"path": "static:ShanghaiWindy.Core.API.TimeAPI"
},
"expect": {
"contains": "IsPaused"
}
},
{
"tool": "invoke",
"arguments": {
"path": "static:ShanghaiWindy.Core.AssetBundleManager/LuaEnv/DoString",
"args": [
"local api = CS.ShanghaiWindy.Core.API\nlocal query = api.VehicleAPI.CreateQuery()\nassert(query:Run(nil) == 0 and query.Count == 0 and query:Get(0) == nil and query:GetDistance(0) == 0)\nassert(api.WeaponAPI.GetWeapon(nil, 0) == nil and api.WeaponAPI.GetTotalAmmo(nil) == 0)\nreturn \"API 2 query and weapon fallbacks verified\"\n",
"manual-api-query-fallbacks",
"null"
]
},
"expect": {
"contains": "API 2 query and weapon fallbacks verified"
}
}
]
5. 从旧实现迁移
在 OnVehicleReady 创建查询并缓存节点。每次更新调用已保留的查询对象 query:Run(vehicle),再用 query:Get(index) 遍历本次结果。高开销初始化动作如 CreateQuery 和 FindAllDeep 只在需要重建缓存时执行。节点不存在时先核对模型名称和层级。把弹药、装填、模块、起落架和雷达锁定交给事件,把状态绘制安排在 OnGUI,其余周期检查通过 SetUpdateInterval 降频。
| 旧写法 | 当前入口 |
|---|---|
GetObjectsInWorld("Rigidbody")、FindObjectsOfType 或 Identity.GlobalTeamList 扫载具 |
复用 VehicleAPI.CreateQuery()。雷达目标用 RadarAPI。旧 GlobalTeamList 在联机里可能漏掉远程玩家。 |
RaycastAll 手算地杂波和仰角限制 |
在 groundAARadarData 配置地面雷达,用 RadarAPI.GetContact 读探测结果。 |
比较 InstanceNetType 字符串、读 GarageManager.inGarage 或比较 GetPlayerVehicle() |
VehicleAPI.IsGarage、IsLocalPlayer、IsBot、IsRemote。 |
Time.timeScale < 0.01 |
TimeAPI.IsPaused()。 |
在 OnUpdated 里循环调用 TryGetTankInitSystem |
在 OnVehicleReady(vehicle) 初始化一次。 |
递归 GetChild 查找 TurretTransform、GunTransform、FFPoint |
用 TankAPI.GetTurretTransform、GetGunTransform 和 WeaponAPI.GetMuzzle。通用节点用 TransformAPI.FindDeep。 |
读取 bulletCountList、simpleReloadNowTime 或反射私有字段 |
WeaponAPI.GetAmmo、GetReloadProgress、GetReloadTime。 |
| 计数已经发射的弹药 | WeaponAPI.OnAmmoChanged 加 GetTotalAmmo。 |
| 每帧反射模块血量 | InternalModuleAPI.OnStateChanged。 |
猜 curRPM 或 engineRPM 字段 |
TankAPI.GetEngineState。 |
遍历 WheelCollider.isGrounded,按节点名推测起落架状态 |
FlightAPI.IsOnGround、IsGearDown、OnGearChanged。 |
| 自己解算带阻力的提前量 | WeaponAPI.PredictLead。 |
每帧 RemoveBuff 后重新添加 |
BuffAPI.CreateValueBuff,之后调用 SetValue。 |
用 Time.frameCount 对帧回调去重 |
SetUpdateInterval,用 OnUpdated(dt) 提供的时间。 |