Search Results for

    Show / Hide Table of Contents

    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) 提供的时间。

    示例

    • 导弹挂架
    • 蓄力伤害
    • 防空雷达屏幕
    • 敌机接近告警
    • 模块损毁动画
    • 引擎转速和起落架
    In this article
    Back to top Panzer War Document