Warn when an enemy aircraft approaches
δΈζ | English
Run this command at the repository root to replay the examples through the local Unity MCP.
python Docs/Manual/manual/tools/tutorials.py run lua-api2-air-warning
Click to expand MCP actionsClick to collapse MCP actions
Prepare the teaching sample. The recipe provides ${variables}.
{
"variables": {
"script": "${fixture}/AirThreatWarning.lua",
"prefab": "${fixture}/Tutorial_AirThreatWarning.prefab"
},
"calls": [
{
"tool": "invoke",
"arguments": {
"path": "static:UnityEditor.AssetDatabase/CreateFolder",
"args": [
"${fixtureParent}",
"${folder}"
]
},
"expect": {
"contains": "(String)"
}
}
]
}
This vehicle Lua behaviour logs a warning when an enemy aircraft comes within range of the local player. It can also play an FMOD warning. Start with Lua Hello World if you need help importing and attaching a script.
1. Import and configure the warning
- Create
AirThreatWarning.luaunder the Unity project's assets and copy the script below. In VehicleTextData β Misc β Vehicle Lua behavior, add a row, assign the script, and click Sync Properties. To bind through a prefab, add LuaBehaviorMono to an object in the owning vehicle hierarchy. - Keep
warnDistanceat 3,000 m. Assign an FMOD event GUID tosoundGuid, or leave it empty for the first log-only test. - Save, repack, and test the vehicle. The script creates one query in
OnVehicleReadyand runs it every 0.5 seconds.
| Query field | Value and use |
|---|---|
Kind |
VehicleKind.Flight matches aircraft. Other options include Any, Ground, and Army. |
Relation |
VehicleRelation.Enemy uses the team of the vehicle passed to Run(vehicle). Other values include Any and Friendly. |
MaxDistance |
warnDistance, measured in metres. A value of 0 removes that distance limit. |
MaxCount |
1, so the sorted result contains only the nearest aircraft. The default capacity is 32. |
SortByDistance |
true, so the nearest result comes first. |
Behavior()
Property = {
warnDistance = { type = "number", value = 3000 },
soundGuid = { type = "string", value = "" },
}
local AirThreatWarning = class("AirThreatWarning")
function AirThreatWarning:OnVehicleReady(vehicle)
self.vehicle = vehicle
self.query = VehicleAPI.CreateQuery()
self.query.Kind = VehicleKind.Flight
self.query.Relation = VehicleRelation.Enemy
self.query.MaxDistance = self.warnDistance
self.query.MaxCount = 1
self.query.SortByDistance = true
self.warned = false
self.script:SetUpdateInterval(0.5)
end
function AirThreatWarning:OnUpdated()
if self.query == nil or not VehicleAPI.IsLocalPlayer(self.vehicle) then
return
end
local count = self.query:Run(self.vehicle)
if count == 0 then
self.warned = false
return
end
if self.warned then
return
end
local nearest = self.query:Get(0)
if nearest == nil then
return
end
self.warned = true
print(string.format("[AirWarning] %s at %.0f m",
VehicleAPI.GetDisplayName(nearest), self.query:GetDistance(0)))
if self.soundGuid ~= "" then
SoundAPI.PlayOneShot(self.soundGuid, self.transform.position)
end
end
return AirThreatWarning
Click to expand MCP actionsClick to collapse MCP actions
[
{
"tool": "invoke",
"arguments": {
"path": "static:System.IO.File/Copy",
"args": [
"../../Docs/Manual/tutorials/lua-api2-air-warning/example.lua",
"${script}"
]
},
"expect": {
"contains": "OK:"
}
},
{
"tool": "invoke",
"arguments": {
"path": "static:UnityEditor.AssetDatabase/ImportAsset",
"args": [
"${script}",
"ForceSynchronousImport"
]
},
"expect": {
"contains": "OK:"
}
},
{
"tool": "prefab_edit",
"arguments": {
"json": {
"path": "${prefab}",
"mode": "create",
"component": "ShanghaiWindy.Core.Lua.LuaBehaviorMono",
"children": [],
"references": [
{
"property": "luaBehavior",
"asset": "${script}",
"type": "ShanghaiWindy.Core.Lua.LuaBehaviorScript"
}
],
"values": {
"instanceLuaProperty": {
"numberProperties": [
{
"variableName": "warnDistance",
"value": 3000
}
],
"stringProperties": [
{
"variableName": "soundGuid",
"value": ""
}
]
}
}
}
},
"expect": {
"equals": {
"ok": true
}
}
},
{
"tool": "inspect",
"arguments": {
"path": "asset:${prefab}/LuaBehaviorMono/luaBehavior/name"
},
"expect": {
"contains": "(String) AirThreatWarning"
}
}
]
2. Check when the warning repeats
- Drive the vehicle as the local player in the playground. Bring a visible enemy aircraft into range. Look for
[AirWarning]followed by the nearest aircraft's name and distance. The script reads the first result withGet(0)andGetDistance(0). - The warning should run once while detections remain in range. When the query becomes empty, the next detection can trigger it again. If you added a sound GUID, check that it plays at the vehicle's position.
- Check the local player, teams, and visibility. Online results follow team visibility. For scripts on maps or game modes, use
RunAt(position, team)to query around a point for a chosen team.
Older scripts polled scene rigidbodies and filtered aircraft in Lua. This example keeps one query and performs the filtering and sorting in the game. The MCP replay simulates a target appearing, remaining in range, and leaving. Check the actual sound and online visibility in game.
Click to expand MCP actionsClick to collapse MCP actions
[
{
"tool": "invoke",
"arguments": {
"path": "static:ShanghaiWindy.Core.AssetBundleManager/LuaEnv/DoString",
"args": [
"local E = setmetatable({ Behavior = function() end, class = function() return {} end, print = function() end }, { __index = _G })\nlocal count, played, checks, localPlayer = 0, 0, 0, true\nlocal aircraft = {}\nlocal query = {\n Run = function() checks = checks + 1; return count end,\n Get = function(_, i) assert(i == 0); return aircraft end,\n GetDistance = function(_, i) assert(i == 0); return 500 end,\n}\nE.VehicleKind = { Flight = 2 }\nE.VehicleRelation = { Enemy = 1 }\nE.VehicleAPI = {\n CreateQuery = function() return query end,\n IsLocalPlayer = function() return localPlayer end,\n GetDisplayName = function(v) assert(v == aircraft); return \"Sample\" end,\n}\nE.SoundAPI = { PlayOneShot = function(guid, _) assert(guid == \"sample\"); played = played + 1 end }\n\nlocal B = assert(loadfile('../../Docs/Manual/tutorials/lua-api2-air-warning/example.lua', 't', E))()\nlocal function instance(t) return setmetatable(t, { __index = B }) end\nlocal script = { SetUpdateInterval = function(_, x) assert(x == 0.5) end }\nlocal sample = instance({ script = script, warnDistance = 3000, soundGuid = \"sample\", transform = {} })\nsample:OnUpdated()\nsample:OnVehicleReady({})\nassert(query.Kind == 2 and query.Relation == 1 and query.MaxCount == 1 and query.MaxDistance == 3000)\nsample:OnUpdated()\ncount = 1\nsample:OnUpdated()\nsample:OnUpdated()\nassert(played == 1)\ncount = 0\nsample:OnUpdated()\ncount = 1\nsample:OnUpdated()\nassert(played == 2)\nlocalPlayer = false\nsample:OnUpdated()\nassert(checks == 5)\nlocal api = CS.ShanghaiWindy.Core.API\nlocal real = api.VehicleAPI.CreateQuery()\nreal.Kind = api.VehicleKind.Flight\nreal.Relation = api.VehicleRelation.Enemy\nreal.MaxCount = 1\nassert(real.Run(real, nil) == 0 and real.Count == 0)\nreturn \"Lua example passed\"\n",
"manual-lua-api2-air-warning",
"null"
]
},
"expect": {
"contains": "Lua example passed"
}
}
]