Lua CMDs

Development < Lua Scripting < Lua CMDs

Options

CMD.OPT_ALT
CMD.OPT_CTRL
CMD.OPT_SHIFT
CMD.OPT_RIGHT
CMD.OPT_INTERNAL
CMD.OPT_META

Waitcodes

CMD.WAITCODE_TIME
CMD.WAITCODE_DEATH
CMD.WAITCODE_SQUAD
CMD.WAITCODE_GATHER

Insert/Remove Commands

To get the commandqueue use the following lua-call

CommandQueues

Spring.GetUnitCommands
Spring.GetCommandQueue (Alias)

 ( number unitID, number count = 0 ) -> nil | number commandQueueSize New in version 96
 ( number unitID [, number count = -1] ) 
 -> nil | table commandQueueTable = {
    [1] = {
      "id"      = number,
      "params"  = { [1] = number, ...},
      "options" = {
        "coded"    = number,
        "alt"      = boolean,
        "ctrl"     = boolean,
        "shift"    = boolean,
        "right"    = boolean,
        "internal" = boolean,
        "meta"    = boolean
      }
    }, ...
  }

First, said "tags" aka "id" are unique command identifiers, so each command that gets inserted into a unit's command queue gets its unique "tag" number. (It is used to sync command queue operations, also it makes things much easier.) Editors Note: I fucking hate it when open source devs use the word easy. It is a clear indicator that someone spends a whole day finding out about a well hidden simple concept. Well at least we are on this journey together :)
To look at those "tags" you can do the following:

  local cmdQueue = Spring.GetUnitCommands(unitID);
  if (#cmdQueue>0) then 
     local cmdTag = cmdQueue[1].tag
     Spring.Echo(cmdTag)
     ..
  end

CMD.INSERT

 options.ALT     -> treat param0 as a position instead of a tag 
 options.CONTROL -> use the build queue for factories 
 params[0] = command tag or position (negative numbers to reference
 the back of the queue and 0 the first)
 params[1] = insertCmd id 
 params[2] = insertCmd options (shift,alt,right click,etc.)
 params[3 ... N+2] = insertCmd params[0 ... N-1]

 example:
   Spring.GiveOrderToUnit(unitID,
     CMD.INSERT,
     {-1,CMD.ATTACK,CMD.OPT_SHIFT,unitID2},
     {"alt"}
   );

Command structure dissection:

What to do with the command - in our case insert:

'CMD.INSERT'

Place in the queue to insert:

'-1'

Type of command to insert:

'CMD.ATTACK'

Additional Information:

If the unit is working down a shift queue, add it seemless into it

'CMD.OPT_SHIFT'

TargetID or Position:

'unitID2'

The '-1' is the queue position and not a tag:

'{"alt"}'

 if you insert cmd in pos 2 for example the rest of commands starting
 from 2 will be pushed back. 
 Ilustration: {cmdA, cmdB, cmdC, cmdD} => {cmdA, cmdB, NewCmd, cmdC, cmdD}

 
 Note: If you didn't already notice, the command params and
       the command options are twisted in the array (compared to GiveOrder)!
 
 Note2: The command options in the array/table is a number value!
        You have to use CMD.OPT_* in this case.
 
 Note3: The inserted command doesn't go through allowcommand callins, only CMD.INSERT does.
 

CMD.REMOVE

 options.ALT     -> use the parameters as commandIDs 
 options.CONTROL -> use the build queue for factories 
 params[0 ... N-1] = tags or commandIDs to remove

No clues what the above mean translated, but here is a working example of how to delete a buildorder from a factory:

local facCmds = Spring.GetFactoryCommands(factoryID)

     if facCmds then -- nil check

local cmd = facCmds[1]

        Spring.GiveOrderToUnit(factoryID, CMD.REMOVE, {i,cmd.tag}, {"ctrl"})

     end

Commands

Note, the CMD[] table is bidirectional. That means: CMD[CMD.STOP] := "CMD_STOP"

CMD.STOP

 type CMDTYPE.ICON

CMD.WAIT

 type CMDTYPE.ICON

CMD.TIMEWAIT

 type CMDTYPE.NUMBER

CMD.DEATHWAIT

 type CMDTYPE.ICON_UNIT_OR_RECTANGLE

CMD.SQUADWAIT

 type CMDTYPE.NUMBER

CMD.GATHERWAIT

 type CMDTYPE.ICON

CMD.MOVE

 type CMDTYPE.ICON_MAP

CMD.PATROL

 type CMDTYPE.ICON_MAP

CMD.FIGHT

 type CMDTYPE.ICON_MAP

CMD.ATTACK

 type CMDTYPE.ICON_UNIT_OR_MAP

CMD.AREA_ATTACK

 type CMDTYPE.ICON_AREA

CMD.GUARD

 type CMDTYPE.ICON_UNIT

CMD.AISELECT

 type CMDTYPE.COMBO_BOX

CMD.GROUPSELECT

 type CMDTYPE.ICON

CMD.GROUPADD

 type CMDTYPE.ICON

CMD.GROUPCLEAR

 type CMDTYPE.ICON

CMD.REPAIR

 type CMDTYPE.ICON_UNIT_OR_AREA

CMD.FIRE_STATE

 type CMDTYPE.ICON_MODE

CMD.MOVE_STATE

 type CMDTYPE.ICON_MODE

CMD.SELFD

 type CMDTYPE.ICON

CMD.LOAD_UNITS

 type CMDTYPE.ICON_UNIT_OR_AREA

CMD.LOAD_ONTO

 type CMDTYPE.ICON_UNIT

CMD.UNLOAD_UNITS

 type CMDTYPE.ICON_UNIT_OR_AREA

CMD.UNLOAD_UNIT

 type CMDTYPE.ICON_MAP

CMD.ONOFF

 type CMDTYPE.ICON_MODE

CMD.RECLAIM

 type CMDTYPE.ICON_UNIT_FEATURE_OR_AREA

CMD.CLOAK

 type CMDTYPE.ICON_MODE

CMD.STOCKPILE

 type CMDTYPE.ICON

CMD.DGUN

 type CMDTYPE.ICON_MAP

CMD.RESTORE

 type CMDTYPE.ICON_AREA

CMD.REPEAT

 type CMDTYPE.ICON_MODE

CMD.TRAJECTORY

 type CMDTYPE.ICON_MODE

CMD.RESURRECT

 type CMDTYPE.ICON_UNIT_FEATURE_OR_AREA

CMD.CAPTURE

 type CMDTYPE.ICON_UNIT_OR_AREA

CMD.AUTOREPAIRLEVEL

 type CMDTYPE.ICON_MODE

CMD.LOOPBACKATTACK

 type CMDTYPE.ICON_MODE

CMD.IDLEMODE

 type CMDTYPE.ICON_MODE

CMD.SET_WANTED_MAX_SPEED

 type CMDTYPE.NUMBER

CMD.SETBASE

CMD.INTERNAL

 used in different ways

A negative number means build command
The number is -unitDefID of the unittype that this command orders to be built.

  This means that build orders have no convenient CMD._____ string.
     The command id for build orders must always be a "minus" sign appended to an integer value.
  Spring.GiveOrderToUnit(unitID, -(unitDefID), {x,y,z(,facing)}, {"shift"})
     alternatively:
  Spring.GiveOrderToUnit(unitID, -UnitDefNames["unitname"].id, {x,y,z(,facing)}, {"shift"})
    'facing' is an optional integer parameter that controls unit's facing when placed.
     The values of (x,y,z) must all be number values (like "0"), placeholder symbols such as "_" will break the build order.

CommandTypes

Note, the CMDTYPE[] table is bidirectional. That means: CMDTYPE[CMDTYPE.ICON] := "CMDTYPE_ICON"

CMDTYPE.ICON

 expect 0 parameters in return

CMDTYPE.ICON_MODE

 expect 1 parameter in return (number selected mode)

CMDTYPE.ICON_MAP

 expect 3 parameters in return (mappos)

CMDTYPE.ICON_AREA

 expect 4 parameters in return (mappos+radius)

CMDTYPE.ICON_UNIT

 expect 1 parameters in return (unitid)

CMDTYPE.ICON_UNIT_OR_MAP

 expect 1 parameters in return (unitid) or 3 parameters in return (mappos)

CMDTYPE.ICON_FRONT

 expect 3 or 6 parameters in return (middle and right side of front if a front was defined)

CMDTYPE.COMBO_BOX

 expect 1 parameter in return (number selected option)

CMDTYPE.ICON_UNIT_OR_AREA

 expect 1 parameter in return (unitid) or 4 parameters in return (mappos+radius)

CMDTYPE.ICON_UNIT_FEATURE_OR_AREA

 expect 1 parameter in return (unitid or Game.maxUnits+featureid)
     or 4 parameters in return (mappos+radius)

CMDTYPE.ICON_BUILDING

 expect 3 parameters in return (mappos)

CMDTYPE.ICON_UNIT_OR_RECTANGLE

 expect 1 parameter in return (unitid)
     or 3 parameters in return (mappos)
     or 6 parameters in return (startpos+endpos)

CMDTYPE.NUMBER

 expect 1 parameter in return (number)

CMDTYPE.CUSTOM

 used with CMD_INTERNAL

CMDTYPE.NEXT next command page

 used with CMD_INTERNAL

CMDTYPE.PREV previous command page

 used with CMD_INTERNAL