Spring - User contributions [en]

Lua CMDs

2015-09-25T05:56:09Z

Autowar: /* Commands */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

== 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|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 [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.WAIT
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.TIMEWAIT
type [[Lua_CMDs#CMDTYPE.NUMBER|CMDTYPE.NUMBER]]
CMD.DEATHWAIT
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_RECTANGLE|CMDTYPE.ICON_UNIT_OR_RECTANGLE]]
CMD.SQUADWAIT
type [[Lua_CMDs#CMDTYPE.NUMBER|CMDTYPE.NUMBER]]
CMD.GATHERWAIT
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.MOVE
type [[Lua_CMDs#CMDTYPE.ICON_MAP|CMDTYPE.ICON_MAP]]
CMD.PATROL
type [[Lua_CMDs#CMDTYPE.ICON_MAP|CMDTYPE.ICON_MAP]]
CMD.FIGHT
type [[Lua_CMDs#CMDTYPE.ICON_MAP|CMDTYPE.ICON_MAP]]
CMD.ATTACK
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_MAP|CMDTYPE.ICON_UNIT_OR_MAP]]
CMD.AREA_ATTACK
type [[Lua_CMDs#CMDTYPE.ICON_AREA|CMDTYPE.ICON_AREA]]
CMD.GUARD
type [[Lua_CMDs#CMDTYPE.ICON_UNIT|CMDTYPE.ICON_UNIT]]
CMD.AISELECT
type [[Lua_CMDs#CMDTYPE.COMBO_BOX|CMDTYPE.COMBO_BOX]]
CMD.GROUPSELECT
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.GROUPADD
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.GROUPCLEAR
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.REPAIR
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_AREA|CMDTYPE.ICON_UNIT_OR_AREA]]
CMD.FIRE_STATE
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.MOVE_STATE
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.SELFD
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.LOAD_UNITS
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_AREA|CMDTYPE.ICON_UNIT_OR_AREA]]
CMD.LOAD_ONTO
type [[Lua_CMDs#CMDTYPE.ICON_UNIT|CMDTYPE.ICON_UNIT]]
CMD.UNLOAD_UNITS
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_AREA|CMDTYPE.ICON_UNIT_OR_AREA]]
CMD.UNLOAD_UNIT
type [[Lua_CMDs#CMDTYPE.ICON_MAP|CMDTYPE.ICON_MAP]]
CMD.ONOFF
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.RECLAIM
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_FEATURE_OR_AREA|CMDTYPE.ICON_UNIT_FEATURE_OR_AREA]]
CMD.CLOAK
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.STOCKPILE
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.DGUN
type [[Lua_CMDs#CMDTYPE.ICON_MAP|CMDTYPE.ICON_MAP]]
CMD.RESTORE
type [[Lua_CMDs#CMDTYPE.ICON_AREA|CMDTYPE.ICON_AREA]]
CMD.REPEAT
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.TRAJECTORY
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.RESURRECT
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_FEATURE_OR_AREA|CMDTYPE.ICON_UNIT_FEATURE_OR_AREA]]
CMD.CAPTURE
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_AREA|CMDTYPE.ICON_UNIT_OR_AREA]]
CMD.AUTOREPAIRLEVEL
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.LOOPBACKATTACK
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.IDLEMODE
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.SET_WANTED_MAX_SPEED
type [[Lua_CMDs#CMDTYPE.NUMBER|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 the number "0"), or the build order will break.

== 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 [[Lua_ConstGame#Engine|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

[[category: Lua]]

Lua CMDs

2015-09-25T05:54:30Z

Autowar:

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

== 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|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 [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.WAIT
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.TIMEWAIT
type [[Lua_CMDs#CMDTYPE.NUMBER|CMDTYPE.NUMBER]]
CMD.DEATHWAIT
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_RECTANGLE|CMDTYPE.ICON_UNIT_OR_RECTANGLE]]
CMD.SQUADWAIT
type [[Lua_CMDs#CMDTYPE.NUMBER|CMDTYPE.NUMBER]]
CMD.GATHERWAIT
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.MOVE
type [[Lua_CMDs#CMDTYPE.ICON_MAP|CMDTYPE.ICON_MAP]]
CMD.PATROL
type [[Lua_CMDs#CMDTYPE.ICON_MAP|CMDTYPE.ICON_MAP]]
CMD.FIGHT
type [[Lua_CMDs#CMDTYPE.ICON_MAP|CMDTYPE.ICON_MAP]]
CMD.ATTACK
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_MAP|CMDTYPE.ICON_UNIT_OR_MAP]]
CMD.AREA_ATTACK
type [[Lua_CMDs#CMDTYPE.ICON_AREA|CMDTYPE.ICON_AREA]]
CMD.GUARD
type [[Lua_CMDs#CMDTYPE.ICON_UNIT|CMDTYPE.ICON_UNIT]]
CMD.AISELECT
type [[Lua_CMDs#CMDTYPE.COMBO_BOX|CMDTYPE.COMBO_BOX]]
CMD.GROUPSELECT
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.GROUPADD
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.GROUPCLEAR
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.REPAIR
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_AREA|CMDTYPE.ICON_UNIT_OR_AREA]]
CMD.FIRE_STATE
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.MOVE_STATE
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.SELFD
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.LOAD_UNITS
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_AREA|CMDTYPE.ICON_UNIT_OR_AREA]]
CMD.LOAD_ONTO
type [[Lua_CMDs#CMDTYPE.ICON_UNIT|CMDTYPE.ICON_UNIT]]
CMD.UNLOAD_UNITS
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_AREA|CMDTYPE.ICON_UNIT_OR_AREA]]
CMD.UNLOAD_UNIT
type [[Lua_CMDs#CMDTYPE.ICON_MAP|CMDTYPE.ICON_MAP]]
CMD.ONOFF
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.RECLAIM
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_FEATURE_OR_AREA|CMDTYPE.ICON_UNIT_FEATURE_OR_AREA]]
CMD.CLOAK
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.STOCKPILE
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.DGUN
type [[Lua_CMDs#CMDTYPE.ICON_MAP|CMDTYPE.ICON_MAP]]
CMD.RESTORE
type [[Lua_CMDs#CMDTYPE.ICON_AREA|CMDTYPE.ICON_AREA]]
CMD.REPEAT
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.TRAJECTORY
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.RESURRECT
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_FEATURE_OR_AREA|CMDTYPE.ICON_UNIT_FEATURE_OR_AREA]]
CMD.CAPTURE
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_AREA|CMDTYPE.ICON_UNIT_OR_AREA]]
CMD.AUTOREPAIRLEVEL
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.LOOPBACKATTACK
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.IDLEMODE
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.SET_WANTED_MAX_SPEED
type [[Lua_CMDs#CMDTYPE.NUMBER|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 [[Lua_ConstGame#Engine|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

[[category: Lua]]

Lua CMDs

2015-09-25T05:09:17Z

Autowar:

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

== 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|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 [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.WAIT
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.TIMEWAIT
type [[Lua_CMDs#CMDTYPE.NUMBER|CMDTYPE.NUMBER]]
CMD.DEATHWAIT
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_RECTANGLE|CMDTYPE.ICON_UNIT_OR_RECTANGLE]]
CMD.SQUADWAIT
type [[Lua_CMDs#CMDTYPE.NUMBER|CMDTYPE.NUMBER]]
CMD.GATHERWAIT
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.MOVE
type [[Lua_CMDs#CMDTYPE.ICON_MAP|CMDTYPE.ICON_MAP]]
CMD.PATROL
type [[Lua_CMDs#CMDTYPE.ICON_MAP|CMDTYPE.ICON_MAP]]
CMD.FIGHT
type [[Lua_CMDs#CMDTYPE.ICON_MAP|CMDTYPE.ICON_MAP]]
CMD.ATTACK
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_MAP|CMDTYPE.ICON_UNIT_OR_MAP]]
CMD.AREA_ATTACK
type [[Lua_CMDs#CMDTYPE.ICON_AREA|CMDTYPE.ICON_AREA]]
CMD.GUARD
type [[Lua_CMDs#CMDTYPE.ICON_UNIT|CMDTYPE.ICON_UNIT]]
CMD.AISELECT
type [[Lua_CMDs#CMDTYPE.COMBO_BOX|CMDTYPE.COMBO_BOX]]
CMD.GROUPSELECT
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.GROUPADD
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.GROUPCLEAR
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.REPAIR
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_AREA|CMDTYPE.ICON_UNIT_OR_AREA]]
CMD.FIRE_STATE
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.MOVE_STATE
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.SELFD
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.LOAD_UNITS
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_AREA|CMDTYPE.ICON_UNIT_OR_AREA]]
CMD.LOAD_ONTO
type [[Lua_CMDs#CMDTYPE.ICON_UNIT|CMDTYPE.ICON_UNIT]]
CMD.UNLOAD_UNITS
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_AREA|CMDTYPE.ICON_UNIT_OR_AREA]]
CMD.UNLOAD_UNIT
type [[Lua_CMDs#CMDTYPE.ICON_MAP|CMDTYPE.ICON_MAP]]
CMD.ONOFF
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.RECLAIM
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_FEATURE_OR_AREA|CMDTYPE.ICON_UNIT_FEATURE_OR_AREA]]
CMD.CLOAK
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.STOCKPILE
type [[Lua_CMDs#CMDTYPE.ICON|CMDTYPE.ICON]]
CMD.DGUN
type [[Lua_CMDs#CMDTYPE.ICON_MAP|CMDTYPE.ICON_MAP]]
CMD.RESTORE
type [[Lua_CMDs#CMDTYPE.ICON_AREA|CMDTYPE.ICON_AREA]]
CMD.REPEAT
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.TRAJECTORY
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.RESURRECT
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_FEATURE_OR_AREA|CMDTYPE.ICON_UNIT_FEATURE_OR_AREA]]
CMD.CAPTURE
type [[Lua_CMDs#CMDTYPE.ICON_UNIT_OR_AREA|CMDTYPE.ICON_UNIT_OR_AREA]]
CMD.AUTOREPAIRLEVEL
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.LOOPBACKATTACK
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.IDLEMODE
type [[Lua_CMDs#CMDTYPE.ICON_MODE|CMDTYPE.ICON_MODE]]
CMD.SET_WANTED_MAX_SPEED
type [[Lua_CMDs#CMDTYPE.NUMBER|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 integer parameter that controls unit's facing when placed.

== 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 [[Lua_ConstGame#Engine|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

[[category: Lua]]

Animation-LuaCallins

2015-01-14T03:50:08Z

Autowar: To reduce visual confusion for newbies researching scripts, "script." has been added to the beginning of every callin to reflect actual usage in-code.

== Introduction ==

Call-ins are calls from the engine, into the unit script. In other words, these functions are called, if they are defined, when a particular â€œeventâ€ happens.

For Lua unit scripts, a new callin mechanism has been implemented, which is faster than the regular callin mechanism which is used for widgets and gadgets.

Types for arguments are only shown where they're ambiguous. For a number of (common) arguments, the types are:

* unitID: number
* piece: number
* axis: number (1 = x axis, 2 = y axis, 3 = z axis)
* heading/pitch: number (radians)

== Generic ==

'''script.Create''' ( ) -> nil

This is called just after the unit script has been created.

'''script.StartMoving''' ( ) -> nil 
'''script.StopMoving''' ( ) -> nil

These are called whenever the unit starts or stops moving. Typical use for them is to trigger wheels to start spinning, animate treads, or start/stop a walking animation. Since 95.0 they are only run when a unit transitions from zero to non-zero speed or vice versa, and no longer during in-place rotations.

'''script.Killed''' ( number recentDamage, number maxHealth ) -> number corpseType

This is called when the unit is killed. The severity of the kill may be calculated as severity=recentDamage/maxHealth ''(*100 so that it's in percent, no? at least that is how severity was expressed in Cob/bos, I think. Of course there's no reason to emulate that, just pointing it out for people "converting")''. Typically, this function would play a death animation for the unit, and finally return a corpse type.

'''script.WindChanged''' ( number heading, number strength ) -> nil

This is called for wind generators whenever the wind direction or strength changes.

'''script.ExtractionRateChanged''' ( number rate ) -> nil

Called for metal extractors each time their extraction rate (metal per second) changes.

'''script.setSFXoccupy''' ( number curTerrainType ) -> nil

Called when terrain type changes. Terrain type is calculated with the following rules (in this order):

* If unit is being transported -> curTerrainType = 0
* If ground height < -5 and unit is always upright -> curTerrainType = 2
* If ground height < -5 and unit is not always upright -> curTerrainType = 1
* If ground height < 0 and unit is always upright -> curTerrainType = 1
* Otherwise -> curTerrainType = 4

Where is curTerrainType = 3 ? :-)

Candidate to be changed to something saner later on.

'''script.MoveRate''' ( number curRate ) -> nil

Called only for certain types of aircraft (those which use ''CTAAirMoveType''.) The move rate is determined by the following rules (in this order):

* If the aircraft is landing or taking off -> curRate = 1
* Otherwise -> curRate = floor(curSpeed / maxSpeed * 3), clamped to be in the range [0, 2]

'''script.QueryLandingPads''' ( ) -> { number piece1, number piece2, ... }

Called one time for units with landing pads. Should return a table with pieces which should be used as landing pads. The number of pieces returned also determines the number of pads, so for Lua unit scripts there is no QueryLandingPadCount.

'''script.Activate''' ( ) -> nil 
'''script.Deactivate''' ( ) -> nil

Exact situation these are called depends a lot on the unit type. Factories are activated when they open their yard and deactivated when they close it. Aircraft are activated when they take off and deactivated when the land. Any unit that can be turned on or off is activated when it's turned on and deactivated when it's turned off. On ''script.SetUnitValue(COB.ACTIVATION, ...)'' one of these call-ins may be called too.

== Weapons ==

Weapon functions come in two variants.

* Separate function with numeric weapon number suffix. (e.g. ''script.AimWeapon1(heading, pitch)'')
* Combined function which gets weapon number as second argument. (e.g. ''script.AimWeapon(weaponNum, heading, pitch)'')

Only the first variant is listed here, so whenever you see a function whose name ends with a numeric one ("1"), you should either replace it with the actual weapon number, or you can write a single combined function that takes a ''weaponNum'' argument. For each script, all functions should use the same variant. Either all using name suffix, or all using combined functions.

'''script.QueryWeapon1''' ( ) -> number piece 
'''script.AimFromWeapon1''' ( ) -> number piece 
'''script.AimWeapon1''' ( heading, pitch ) -> boolean 
'''script.AimShield1''' ( ) -> boolean

Weapon support. The return value of QueryWeapon and AimFromWeapon determines the pieces which will be used for aiming: typically e.g. the barrel for QueryWeapon and the turret for AimFromWeapon. AimWeapon is then called to allow the script to turn the weapons in the target direction, which is passed as the heading and pitch argument (in radians). Only if AimWeapon returns true, the weapon is actually fired.

TODO: better explanation (?), note about AimWeapon being called very often etc.

'''script.FireWeapon1''' ( ) -> nil 
'''script.Shot1''' ( ) -> nil 
'''script.EndBurst1''' ( ) -> nil

If after aiming the unit actually fires it's weapon, FireWeapon is called once at the beginning of the salvo. Shot is called just before each projectile is fired. RockUnit (see below) is called just after all projectiles for that frame have been fired. At the end of the salvo, EndBurst is called.

Of these call-ins, FireWeapon is the more generic one and Shot and EndBurst are more specialized. FireWeapon is usually used to play a recoil animation or emit some smoke near the weapon's barrel using EmitSfx.

'''script.BlockShot1''' ( targetUnitID, boolean userTarget ) -> boolean

Allows you to block a weapon from shooting. TargetUnitID may be nil: in this case the unit has a ground-attack order.

'''script.TargetWeight1''' ( targetUnitID ) -> number

Allows you to tweak the priority of the target for this particular weapon. The target priority is multiplied by the return value of this function. Lower priority targets are targeted first, so return a value smaller than 1 to prioritize a target, or return a value larger than 1 to avoid a target.

The exact behavior of specific values shouldn't be relied upon.

'''script.RockUnit''' ( x, z ) -> nil

A bit like the weapon-specific FireWeapon function, although this is called after any weapon fires. As argument it gets a two dimensional vector in the direction the unit just fired. This may be used to â€œrockâ€ the unit as a whole a bit as part of the firing animation. Note though that this vector is in world space, so for a truly realistic rock direction it needs to be rotated according to the unit's current heading.

'''script.HitByWeapon''' ( x, z, weaponDefID, damage ) -> nil | number newDamage

This is called if a unit has been hit by a weapon. (x, z) is the direction from which the projectile came in unit space (the reverse direction of the impulse, to be exact.) It also gets the weaponDefID of the weapon which is dealing the damage, and the amount of damage. If HitByWeapon returns a number, this number will replace the damage value calculated by the engine.

Note: Pre Spring 95, this call-in runs just before the LuaRules UnitPreDamaged callin (see also [[LuaCallinReturn]]). If HitByWeapon overrides the damage, UnitPreDamaged will see the new damage value, and may override again the damage value. Starting Spring 95, it is run after UnitPreDamaged.

== Builders and factories ==

'''script.StartBuilding''' ( heading, pitch ) -> nil 
'''script.StartBuilding''' ( ) -> nil 
'''script.StopBuilding''' ( ) -> nil

These notify the script when a builder or factory starts or stops building.

The first variant (with heading and pitch arguments) is called for builders. For factories, the second variant is used. In this case the heading and pitch are not necessary, because the factory script specifies the build location itself using QueryBuildInfo.

BTW, don't forget to set INBUILDSTANCE to 1 to start building! For lua script, that is

<code>
function script.StartBuilding(heading, pitch)

SetUnitValue(COB.INBUILDSTANCE, 1)

end

function script.StopBuilding()
SetUnitValue(COB.INBUILDSTANCE, 0)
end
</code>

'''script.QueryBuildInfo''' ( ) -> number piece

For factories only. Should return the piece to which the unit which is going to be build will be attached while it's being build.

'''script.QueryNanopiece''' ( ) -> number piece

Called each time a nano particle is to be created. Should return the piece at which the particle will be spawned. This may be used to iterate through a few pieces, to simulate the factory/builder having multiple nanolathes.

N.B. As of 92.0 the results are cached and the function is called 31 times only. Deprecated in favour of Spring.SetUnitNanoPieces, which disables this callin when used.

== Transports ==

There are some different code paths inside Spring related to transports, each (unfortunately) also associated with a different set of unit script call-ins.

This table shows for the three different transportUnloadMethods for both air transports and ground transports which callins are used and roughly when and how often they are called. Refer to the documentation below for a description of the call-ins.

The entire behavior around transports should be considered subject to change; it is obvious it is far from a perfect design currently.

{|border="1" style="border-spacing:0px;"
|+
!
!Load
!UnloadLand (0)
!UnloadDrop (1)
!UnloadLandFlood (2)
|-
|
|
|default unload
|fly over and drop unit
|land, then release all units at once
|-
|air
|BeginTransport (each) QueryTransport (each)
|EndTransport (last)
|EndTransport (each)
|StartUnload (first) TransportDrop (each) EndTransport (last)
|-
|ground
|TransportPickup (each)
|TransportDrop (each)
|TransportDrop (each)
|TransportDrop (each) EndTransport (last)
|}

=== Air transports ===

'''script.BeginTransport''' ( passengerID ) -> nil 
'''script.QueryTransport''' ( passengerID ) -> number piece

For an air transport, if any one unit is picked up, these two are called in succession and the passenger is attached to the piece returned by the second one.

'''script.StartUnload''' ( ) -> nil

Only called in UnloadLandFlood behavior. Signals the start of an unload cycle.

'''script.TransportDrop''' ( passengerID, x, y, z ) -> nil

Only called in UnloadLandFlood behavior. Called when a passenger will be unloaded. Contrary to ground transports, Spring will detach the passenger after the call.

'''script.EndTransport''' ( ) -> nil

In UnloadLand and UnloadLandFlood behaviors, these are called one time after all units are unloaded. (The transport is empty.) For the UnloadDrop behavior, this is called for every unit that is unloaded.

=== Ground transports ===

'''script.TransportPickup''' ( passengerID ) -> nil

Called when a passenger should be loaded into the transport. This should eventually call AttachUnit to actually attach the unit. Assuming the transport is in range of the next passenger, this will be called again for the next passenger 16 frames later, ''unless'' the script enters the BUSY state: then Spring will not move on to the next passenger until the script leaves the BUSY state.

'''script.TransportDrop''' ( passengerID, x, y, z ) -> nil

Called when a passenger should be unloaded. This should eventually call DetachUnit to actually detach the unit, ''unless'' the used unload method is UnloadLandFlood, in which case Spring will actually detach the unit after the call.

'''script.EndTransport''' ( ) -> nil

Only called in UnloadLandFlood behavior, after the last unit has been unloaded.

=== Passenger ===

'''script.Falling''' ( ) -> nil

For a unit dropped from an UnloadDrop transport, this is called every frame to inform the script the unit is still falling. It may be used to show a parachute for example.

'''script.Landed''' ( ) -> nil

This is called one time after the unit reached the ground. May be used to hide a parachute for example.

== Internal ==

These call-ins are NOT available to Lua unit scripts. They are called by the engine however, but always 'intercepted' by the framework gadget. For completeness (or if you are poking at the gadget), they are listed here anyway.

'''script.MoveFinished''' ( piece, axis ) -> nil 
'''script.TurnFinished''' ( piece, axis ) -> nil

Called when a move or turn finished. The framework gadget uses this to resume the coroutines which are waiting for the particular move or turn to be finished.

'''script.Destroy''' ( ) -> nil

Called right before the unit's script is destroyed. This may happen if the unit is being destroyed, but also if the unit's script is being replaced by another script. The framework gadget uses this to stop all threads and remove the unit from some internal data structures.

[[Category:Animation]]
[[Category:Lua]]