Legacy api namespace¶

The api table remains available for existing scripts. New scripts must use global command functions and methods on Player, Object, and MapTile.

For example, write UnitsMove(units, destination), not api.moveUnits(...). Use GetAssignedPlayer():GetPlayerObjects() when you need your own objects.

Shortcut queries¶

These shortcuts have no exact global name. Use a Player or Object method when it provides the data that you need.

Legacy call	Preferred approach
`api.localUnits()`	`GetAssignedPlayer():GetPlayerObjects()` for assigned-player objects.
`api.enemyUnits()`	Current enemy list; nil if player enumeration or a required relation is unavailable.
`api.alliedUnits()`	Current allied list; nil if player enumeration or a required relation is unavailable.
`api.gaiaUnits()`	Keep this shortcut when you need the current Gaia list.
`api.unitInfo(object)`	Call the required `Object` methods directly.
`api.halt(object)`	Use `UnitsStop(object)` or `UnitsStop(objects)` for a group.

api.localUnits() and Player:GetPlayerObjects() are not identical filters. Use the smallest query that gives the objects that your script needs.

Command aliases¶

These legacy calls have preferred global command names.

Legacy call	Preferred call
`api.moveUnits`	`UnitsMove`
`api.target`	`UnitsTargetObject`
`api.dropResources`	`DropResources`
`api.makeUnit`, `api.trainUnit`	`TrainUnit`
`api.researchTechnology`	`ResearchTechnology`
`api.build`	`UnitsBuildStructure`
`api.setGatherPoint`	`SetGatherPoint`
`api.ringTownBell`	`RingTownBell`
`api.sendBackToWork`	`SendBackToWork`
`api.sendAllBackToWork`	`SendAllBackToWork`
`api.deleteObjects`	`DeleteUnit` or `DestroyBuilding`
`api.autoScout`	`SetUnitStanceAutoScout`
`api.follow`	`SetUnitStanceFollow`
`api.guard`	`SetUnitStanceGuard`
`api.patrol`	`SetUnitStancePatrol`
`api.attackMove`	`SetUnitStanceAttackMove`
`api.seekShelter`	`SetUnitStanceSeekShelter`
`api.ungarrison`	`SetUnitStanceUngarrison`
`api.gatherInside`	`GatherInside`
`api.setCombatStance`	`SetUnitCombatStance`
`api.setFormation`	`SetUnitFormation`
`api.buyCommodity`	`BuyCommodity`
`api.sellCommodity`	`SellCommodity`
`api.tributeToPlayer`	`TributeToPlayer`
`api.sendFlare`	`SendFlare`
`api.resign`	`Resign`

Unavailable compatibility names¶

Object:GetProductionQueueCount() now returns nil, reason when the building or queue cannot be read. Previously those failures returned zero. Successful reads still return the total remaining quantity, with zero for an empty queue. Scripts should check for nil before comparing the count; using count or 0 would again hide an unavailable observation.

local count, reason = building:GetProductionQueueCount()
if count == nil then
    return -- Wait for a valid observation before making production decisions.
end
if count == 0 then
    -- The queue was observed empty.
end

Some names remain visible only to let older scripts load. They do not perform a useful action. Do not use them in a new script.

The API name index places these names under Unavailable compatibility names. It also lists unavailable methods on Object and GameOptions. The unimplemented API reference labels each placeholder and shows the fixed value it returns.

TrainUnit (including api.makeUnit and api.trainUnit) now rejects fractional or out-of-range type IDs and counts instead of narrowing them. Type IDs must be in 0..32767; counts must be in 1..32767. Invalid calls return false.