UnitsStop

UnitsStop(units) · UnitsStopTracked(units)

Input: units is one owned Object or a dense array. The group cannot be empty, contain invalid or mixed-owner actors, or exceed native packet capacity; duplicates are included once.

Description: Requests one native group stop. Actor validity and intervening human orders are checked again before submission. Read live unit state later to determine whether they stopped.

Output: UnitsStop returns true for queue admission, otherwise false. UnitsStopTracked returns accepted, receipt.

Errors: Wrong Lua argument types raise an argument error. An empty, invalid, mixed-owner, or oversized actor group, missing layout, changed session, or intervening human order can reject. A tracked receipt gives the rejection reason when available.

For example, stop the currently selected owned object from a deliberate script action:

function StopSelectedObject()
    local player = GetAssignedPlayer()
    local selected = player and player:GetSelectedObject()
    if selected == nil then return false end
    local capability = GetApiCapability(UnitsStop)
    if capability.available ~= true then
        LogWarn("Stop unavailable", capability.reason)
        return false
    end
    return UnitsStop(selected)
end

Do not repeatedly stop units from every update. For a group, pass a dense array of fresh objects.