VAOVertex Array Object
++ +
+ +
+ + + +Attachs a VBO to be used as a vertex buffer
+ +Attachs a VBO to be used as an instance buffer
+ +Attachs a VBO to be used as an index buffer
+ ++ +
+ + +glEnum
+ number
+ primitivesMode
+ numVertices
+ number
+
+
+
+ (optional)
+ vertexCount
+ number
+
+
+
+ (optional)
+ vertexFirst
+ number
+
+
+
+ (optional)
+ instanceCount
+ number
+
+
+
+ (optional)
+ instanceFirst
+ number
+
+
+
+ (optional)
+ + +
+ + +glEnum
+ number
+ primitivesMode
+ drawCount
+ number
+
+
+
+ (optional)
+ baseIndex
+ number
+
+
+
+ (optional)
+ instanceCount
+ number
+
+
+
+ (optional)
+ baseVertex
+ number
+
+
+
+ (optional)
+ baseInstance
+ number
+
+
+
+ (optional)
+ + +
+ + +unitIDs
+ number or {number,...}
+
+
+
+ + +
+ + +featureIDs
+ number or {number,...}
+
+
+
+ + +
+ + +unitDefIDs
+ number or {number,...}
+
+
+
+ + +
+ + +featureDefIDs
+ number or {number,...}
+
+
+
+ + +
+ + +index
+ number
+
+
+
+ + +
+ + + +VBOVertex Buffer Object
++ +
+ +
+ + + +Allows you to specify what kind of VBO you will be using.
++ + + It is usually an array of vertex/color/uv data, but can also be an array of + instance uniforms. + + If you want to specify multiple instances of something to render, you will + need to create another VBO, which also specifies the number of instances you + wish to render, and the size of the data passed to each instance. + + If you want say 5 elements, and each element is defined in the layout: + + {id = 0, name = "first", size = 1},{id = 1, name = "second", size = 2}} + + , then the total size of your VBO will be 5 * (1 + 2). + + They will be laid out consecutively: [1,2],[1,2],[1,2],[1,2],[1,2]. + + This is important for when you call VBO:Upload, you need to make sure you + enter your data into the Lua array correctly. + +
+ + +size
+ number
+ the maximum number of elements this VBO can have.
+ attribs
+ number or {{number,number,number,number,number},...}
+
+
+
+When number, the maximum number of elements this VBO can have.
+ +Otherwise, an array of arrays specifying the layout composed of:
+ +id: the location in the vertex shader layout e.g.: layout (location = 0)
+ in vec2 aPos. optional attrib, specifies location in the vertex shader.
+ If not specified the implementation will increment the counter starting from 0.
+ There can be maximum 16 attributes (so id of 15 is max).name: the name for this VBO, only used for debuggingsize: optional, defaults to 4 for VBO. The number of floats that
+ constitute 1 element in this buffer. O.g. for the previous layout
+ (location = 0) in vec2 aPos, it would be size = 2.GL.BYTE,
+ GL.UNSIGNED_BYTE, GL.SHORT, GL.UNSIGNED_SHORT, GL.INT,
+ GL.UNSIGNED_INT, GL.FLOAT. Default is GL.FLOAT.normalized: it's possible to submit say normal without normalizing them
+ first, normalized will make sure data is normalized.
+ Optional attrib, defaults to false.terrainVertexVBO:Define(numPoints, { {id = 0, name = "pos", size = 2}, })+ +
+ + + +Uploads the data (array of floats) into the VBO
++ +
+ + +vboData
+ {number,...}
+ a lua array of values to upload into the
+ VBO
+ attributeIndex
+ number
+ If supplied with non-default value then the
+ data from vboData will only be used to upload the data to this particular
+ attribute.
+ The whole vboData is expected to contain only attributeIndex data.
+ Otherwise all attributes get updated sequentially across attributes and elements.
+ (default -1)
+ elemOffset
+ number
+ which VBO element to start uploading data from Lua array into
+ (default 0)
+ luaStartIndex
+ number
+ start uploading from that element in supplied Lua array
+ (default 0)
+ luaFinishIndex
+ number
+ consider this element the last element in Lua array
+ (optional)
+ vbo:Upload(posArray, 0, 1) +-- 0 is offset into vbo (on GPU) in this case no offset +-- 1 is lua index index into the Lua table, in this case it's same as default +-- Upload will upload from luaOffset to end of lua array
rectInstanceVBO:Upload({1},0)+ +
+ + +attributeIndex
+ number
+ when supplied with non-default value: only data
+ from specified attribute will be downloaded - otherwise all attributes are
+ downloaded
+ (default -1)
+ elementOffset
+ number
+ download data starting from this element
+ (default 0)
+ elementCount
+ number
+ number of elements to download
+ (optional)
+ forceGPURead
+ bool
+ force downloading the data from GPU buffer as opposed
+ to using shadow RAM buffer
+ (default false)
+ Binds engine side vertex or index VBO containing models (units, features) data.
++ + + Also fills in VBO definition data as they're set for engine models (no need to do VBO:Define()). + +
+ + + +Fills in attribute data for each specified unitDefID
++ + + The instance data in that attribute will contain the offset to bind position + matrix in global matrices SSBO and offset to uniform buffer structure in + global per unit/feature uniform SSBO (unused for Unit/FeatureDefs), as + well as some auxiliary data ushc as draw flags and team index. + +
+ + +unitDefIDs
+ number or {number,...}
+
+
+
+ attrID
+ number
+
+
+
+ teamIdOpt
+ number
+
+
+
+ (optional)
+ elementOffset
+ number
+
+
+
+ (optional)
+ Data Layout
+
+SInstanceData:
+ , matOffset{ matOffset_ } // updated during the following draw frames
+ , uniOffset{ uniOffset_ } // updated during the following draw frames
+ , info{ teamIndex, drawFlags, 0, 0 } // not updated during the following draw frames
+ , aux1 { 0u }Fills in attribute data for each specified featureDefID
++ + + The instance data in that attribute will contain the offset to bind position + matrix in global matrices SSBO and offset to uniform buffer structure in + global per unit/feature uniform SSBO (unused for Unit/FeatureDefs), as + well as some auxiliary data ushc as draw flags and team index. + +
+ + +featureDefIDs
+ number or {number,...}
+
+
+
+ attrID
+ number
+
+
+
+ teamIdOpt
+ number
+
+
+
+ (optional)
+ elementOffset
+ number
+
+
+
+ (optional)
+ Data Layout
+
+SInstanceData:
+ , matOffset{ matOffset_ } // updated during the following draw frames
+ , uniOffset{ uniOffset_ } // updated during the following draw frames
+ , info{ teamIndex, drawFlags, 0, 0 } // not updated during the following draw frames
+ , aux1 { 0u }Fills in attribute data for each specified unitID
++ + + The instance data in that attribute will contain the offset to bind position + matrix in global matrices SSBO and offset to uniform buffer structure in + global per unit/feature uniform SSBO (unused for Unit/FeatureDefs), as + well as some auxiliary data ushc as draw flags and team index. + +
+ + +unitIDs
+ number or {number,...}
+
+
+
+ attrID
+ number
+
+
+
+ teamIdOpt
+ number
+
+
+
+ (optional)
+ elementOffset
+ number
+
+
+
+ (optional)
+ Data Layout
+
+SInstanceData:
+ , matOffset{ matOffset_ } // updated during the following draw frames
+ , uniOffset{ uniOffset_ } // updated during the following draw frames
+ , info{ teamIndex, drawFlags, 0, 0 } // not updated during the following draw frames
+ , aux1 { 0u }Fills in attribute data for each specified featureID
++ + + The instance data in that attribute will contain the offset to bind position + matrix in global matrices SSBO and offset to uniform buffer structure in + global per unit/feature uniform SSBO (unused for Unit/FeatureDefs), as + well as some auxiliary data ushc as draw flags and team index. + +
+ + +featureIDs
+ number or {number,...}
+
+
+
+ attrID
+ number
+
+
+
+ teamIdOpt
+ number
+
+
+
+ (optional)
+ elementOffset
+ number
+
+
+
+ (optional)
+ + +
+ + +projectileIDs
+ number or {number,...}
+
+
+
+ attrID
+ number
+
+
+
+ teamIdOpt
+ number
+
+
+
+ (optional)
+ elementOffset
+ number
+
+
+
+ (optional)
+ Bind a range within a buffer object to an indexed buffer target
++ + + Generally mimics + https://registry.khronos.org/OpenGL-Refpages/gl4/html/glBindBufferRange.xhtml + except offset and size are specified in number of elements / element indices. + +
+ + +index
+ number
+ should be in the range between
+ 5 < index < GL_MAX_UNIFORM_BUFFER_BINDINGS value (usually 31)
+ elementOffset
+ number
+
+
+
+ (optional)
+ elementCount
+ number
+
+
+
+ (optional)
+ target
+ number
+ glEnum
+ (optional)
+ + +
+ + +index
+ number
+
+
+
+ elementOffset
+ number
+
+
+
+ (optional)
+ elementCount
+ number
+
+
+
+ (optional)
+ target
+ number
+ glEnum
+ (optional)
+ Logs the definition of the VBO to the console
++ +
+ + + +| SyncedCtrl | +Synced Lua API | +
| UnsyncedCtrl | +Callouts to set state | +
| SyncedRead | +Synced Read | +
| UnsyncedRead | +Callouts to get state | +
| MoveCtrl | +MoveCtrl | +
| LuaHandle | +Callins, functions called by the Engine | +
| LuaHandleSynced | +Callins, functions called by the Engine (Synced) | +
| VFS | +Virtual File System | +
| LuaVAO | ++ + | +
| LuaVBO | ++ + | +
| OpenGL | +Lua OpenGL API | +
| LuaZip | +LuaZip | +
| LuaRules | +Lua Rules | +
| MetalMap | +Metal Map Lua API | +
| Shaders | +Shader creation and management | +
| FBO | +FBO | +
| RBO | +RBO | +
| MathExtra | +math extensions | +
| BitOps | +math bit extensions | +
| Game | +Game constants | +
| Engine | +Engine constants | +
| Platform | +Platform constants | +
| CMD | +Command constants | +
| CMDTYPE | +Command type constants | +
| COB | +COB constants | +
| GL | +OpenGL Constants | +
| VAO | +Vertex Array Object | +
| VBO | +Vertex Buffer Object | +
BitOpsmath bit extensions
++ + +
Note: there are no bit shift. Use those Lua functions instead for 24 bits bitshift + 24 bits because only the 24 bits of the mantissa can be easily used in a 32 bit float + bitshift functions (<<, >> equivalent)
+ + ++-- left shift +local function lsh(value,shift) + return (value*(2^shift)) % 2^24 +end + +-- right shift +local function rsh(value,shift) + return math.floor(value/2^shift) % 2^24 +end ++ +
Returns the bitwise OR of all arguments.
++ Only use up to 24 bit integers. + +
+ + +a1
+ number
+
+
+
+ a2
+ number
+
+
+
+ a3
+ number
+
+
+
+ (optional)
+ an
+ number
+
+
+
+ (optional)
+ Returns the bitwise AND of all arguments.
++ Only use up to 24 bit integers. + +
+ + +a1
+ number
+
+
+
+ a2
+ number
+
+
+
+ a3
+ number
+
+
+
+ (optional)
+ an
+ number
+
+
+
+ (optional)
+ Returns the bitwise XOR of all arguments.
++ Only use up to 24 bit integers. + +
+ + +a1
+ number
+
+
+
+ a2
+ number
+
+
+
+ a3
+ number
+
+
+
+ (optional)
+ an
+ number
+
+
+
+ (optional)
+ Returns the bitwise NOT of the 24 bit integer argument.
++ +
+ + +a1
+ number
+
+
+
+ Set each of the bits of a 24 bit integer.
++ Returns result = result OR (1 << a1) OR (1 << a2) OR ...;) + +
+ + +a1
+ number
+
+
+
+ a2
+ number
+
+
+
+ a3
+ number
+
+
+
+ (optional)
+ an
+ number
+
+
+
+ (optional)
+ CMDCommand constants
++ +
+ +
+ + +FIRESTATE_NONE
+ -1
+ MOVESTATE_NONE
+ -1
+ STOP
+ 0
+ MOVESTATE_HOLDPOS
+ 0
+ FIRESTATE_HOLDFIRE
+ 0
+ INSERT
+ 1
+ MOVESTATE_MANEUVER
+ 1
+ FIRESTATE_RETURNFIRE
+ 1
+ WAITCODE_TIME
+ 1
+ WAITCODE_DEATH
+ 2
+ MOVESTATE_ROAM
+ 2
+ REMOVE
+ 2
+ FIRESTATE_FIREATWILL
+ 2
+ FIRESTATE_FIREATNEUTRAL
+ 3
+ WAITCODE_SQUAD
+ 3
+ OPT_META
+ 4
+ WAITCODE_GATHER
+ 4
+ WAIT
+ 5
+ TIMEWAIT
+ 6
+ DEATHWAIT
+ 7
+ OPT_INTERNAL
+ 8
+ SQUADWAIT
+ 8
+ GATHERWAIT
+ 9
+ MOVE
+ 10
+ PATROL
+ 15
+ FIGHT
+ 16
+ OPT_RIGHT
+ 16
+ LOOPBACKATTACK
+ 20
+ ATTACK
+ 20
+ AREA_ATTACK
+ 21
+ GUARD
+ 25
+ AISELECT
+ 30
+ OPT_SHIFT
+ 32
+ GROUPSELECT
+ 35
+ GROUPADD
+ 36
+ GROUPCLEAR
+ 37
+ REPAIR
+ 40
+ FIRE_STATE
+ 45
+ MOVE_STATE
+ 50
+ SETBASE
+ 55
+ INTERNAL
+ 60
+ OPT_CTRL
+ 64
+ SELFD
+ 65
+ SET_WANTED_MAX_SPEED
+ 70
+ LOAD_UNITS
+ 75
+ LOAD_ONTO
+ 76
+ UNLOAD_UNITS
+ 80
+ UNLOAD_UNIT
+ 81
+ ONOFF
+ 85
+ RECLAIM
+ 90
+ CLOAK
+ 95
+ STOCKPILE
+ 100
+ MANUALFIRE
+ 105
+ DGUN
+ 105
+ RESTORE
+ 110
+ REPEAT
+ 115
+ TRAJECTORY
+ 120
+ RESURRECT
+ 125
+ OPT_ALT
+ 128
+ CAPTURE
+ 130
+ AUTOREPAIRLEVEL
+ 135
+ IDLEMODE
+ 145
+ CMDTYPECommand type constants
++ +
Note, the CMDTYPE[] table is bidirectional.
++ That means: CMDTYPE[CMDTYPE.ICON] := "CMDTYPE_ICON" + +
+ + +ICON
+ number
+ expect 0 parameters in return
+ ICON_MODE
+ number
+ expect 1 parameter in return (number selected mode)
+ ICON_MAP
+ number
+ expect 3 parameters in return (mappos)
+ ICON_AREA
+ number
+ expect 4 parameters in return (mappos+radius)
+ ICON_UNIT
+ number
+ expect 1 parameters in return (unitid)
+ ICON_UNIT_OR_MAP
+ number
+ expect 1 parameters in return (unitid) or 3 parameters in return (mappos)
+ ICON_FRONT
+ number
+ expect 3 or 6 parameters in return (middle and right side of front if a front was defined)
+ COMBO_BOX
+ number
+ expect 1 parameter in return (number selected option)
+ ICON_UNIT_OR_AREA
+ number
+ expect 1 parameter in return (unitid) or 4 parameters in return (mappos+radius)
+ ICON_UNIT_FEATURE_OR_AREA
+ number
+ expect 1 parameter in return (unitid or Game.maxUnits+featureid) or 4 parameters in return (mappos+radius)
+ ICON_BUILDING
+ number
+ expect 3 parameters in return (mappos)
+ ICON_UNIT_OR_RECTANGLE
+ number
+ expect 1 parameter in return (unitid) or 3 parameters in return (mappos) or 6 parameters in return (startpos+endpos)
+ NUMBER
+ number
+ expect 1 parameter in return (number)
+ CUSTOM
+ number
+ used with CMD_INTERNAL
+ NEXT
+ number
+ next command page used with CMD_INTERNAL
+ PREV
+ number
+ previous command page used with CMD_INTERNAL
+ COBCOB constants
++ +
+ +
+ + +ACTIVATION
+ number
+
+
+
+ STANDINGMOVEORDERS
+ number
+
+
+
+ STANDINGFIREORDERS
+ number
+
+
+
+ HEALTH
+ number
+
+
+
+ INBUILDSTANCE
+ number
+
+
+
+ BUSY
+ number
+
+
+
+ PIECE_XZ
+ number
+
+
+
+ PIECE_Y
+ number
+
+
+
+ UNIT_XZ
+ number
+
+
+
+ UNIT_Y
+ number
+
+
+
+ UNIT_HEIGHT
+ number
+
+
+
+ XZ_ATAN
+ number
+
+
+
+ XZ_HYPOT
+ number
+
+
+
+ ATAN
+ number
+
+
+
+ HYPOT
+ number
+
+
+
+ GROUND_HEIGHT
+ number
+
+
+
+ BUILD_PERCENT_LEFT
+ number
+
+
+
+ YARD_OPEN
+ number
+
+
+
+ BUGGER_OFF
+ number
+
+
+
+ ARMORED
+ number
+
+
+
+ IN_WATER
+ number
+
+
+
+ CURRENT_SPEED
+ number
+
+
+
+ VETERAN_LEVEL
+ number
+
+
+
+ ON_ROAD
+ number
+
+
+
+ MAX_ID
+ number
+
+
+
+ MY_ID
+ number
+
+
+
+ UNIT_TEAM
+ number
+
+
+
+ UNIT_BUILD_PERCENT_LEFT
+ number
+
+
+
+ UNIT_ALLIED
+ number
+
+
+
+ MAX_SPEED
+ number
+
+
+
+ CLOAKED
+ number
+
+
+
+ WANT_CLOAK
+ number
+
+
+
+ GROUND_WATER_HEIGHT
+ number
+
+
+
+ UPRIGHT
+ number
+
+
+
+ POW
+ number
+
+
+
+ PRINT
+ number
+
+
+
+ HEADING
+ number
+
+
+
+ TARGET_ID
+ number
+
+
+
+ LAST_ATTACKER_ID
+ number
+
+
+
+ LOS_RADIUS
+ number
+
+
+
+ AIR_LOS_RADIUS
+ number
+
+
+
+ RADAR_RADIUS
+ number
+
+
+
+ JAMMER_RADIUS
+ number
+
+
+
+ SONAR_RADIUS
+ number
+
+
+
+ SONAR_JAM_RADIUS
+ number
+
+
+
+ SEISMIC_RADIUS
+ number
+
+
+
+ DO_SEISMIC_PING
+ number
+
+
+
+ CURRENT_FUEL
+ number
+
+
+
+ TRANSPORT_ID
+ number
+
+
+
+ SHIELD_POWER
+ number
+
+
+
+ STEALTH
+ number
+
+
+
+ CRASHING
+ number
+
+
+
+ CHANGE_TARGET
+ number
+
+
+
+ CEG_DAMAGE
+ number
+
+
+
+ COB_ID
+ number
+
+
+
+ PLAY_SOUND
+ number
+
+
+
+ KILL_UNIT
+ number
+
+
+
+ ALPHA_THRESHOLD
+ number
+
+
+
+ SET_WEAPON_UNIT_TARGET
+ number
+
+
+
+ SET_WEAPON_GROUND_TARGET
+ number
+
+
+
+ SONAR_STEALTH
+ number
+
+
+
+ REVERSING
+ number
+
+
+
+ FLANK_B_MODE
+ number
+
+
+
+ FLANK_B_DIR
+ number
+
+
+
+ FLANK_B_MOBILITY_ADD
+ number
+
+
+
+ FLANK_B_MAX_DAMAGE
+ number
+
+
+
+ FLANK_B_MIN_DAMAGE
+ number
+
+
+
+ WEAPON_RELOADSTATE
+ number
+
+
+
+ WEAPON_RELOADTIME
+ number
+
+
+
+ WEAPON_ACCURACY
+ number
+
+
+
+ WEAPON_SPRAY
+ number
+
+
+
+ WEAPON_RANGE
+ number
+
+
+
+ WEAPON_PROJECTILE_SPEED
+ number
+
+
+
+ MIN
+ number
+
+
+
+ MAX
+ number
+
+
+
+ ABS
+ number
+
+
+
+ GAME_FRAME
+ number
+
+
+
+ Piece Flags for Spring.UnitScript.Explode
++ +
+ + +SHATTER
+ number
+
+
+
+ EXPLODE
+ number
+
+
+
+ EXPLODE_ON_HIT
+ number
+
+
+
+ FALL
+ number
+
+
+
+ SMOKE
+ number
+
+
+
+ FIRE
+ number
+
+
+
+ NONE
+ number
+
+
+
+ NO_CEG_TRAIL
+ number
+
+
+
+ NO_HEATCLOUD
+ number
+
+
+
+ RECURSIVE
+ number
+
+
+
+ For Spring.UnitScript.EmitSfx
++ +
+ + +VTOL
+ number
+
+
+
+ WAKE
+ number
+
+
+
+ REVERSE_WAKE
+ number
+
+
+
+ WHITE_SMOKE
+ number
+
+
+
+ BLACK_SMOKE
+ number
+
+
+
+ BUBBLE
+ number
+
+
+
+ CEG
+ number
+
+
+
+ FIRE_WEAPON
+ number
+
+
+
+ DETONATE_WEAPON
+ number
+
+
+
+ GLOBAL
+ number
+
+
+
+ EngineEngine constants
++ +
Engine specific information
++ +
+ + +version
+ string
+ Returns the same as spring *sync-version, e.g. "92"
+ versionFull
+ string
+
+
+
+ versionPatchSet
+ string
+
+
+
+ buildFlags
+ string
+ (unsynced only) Gets additional engine buildflags, e.g. "OMP" or "MT-Sim DEBUG"
+ wordSize
+ number
+ indicates the build type and is either 32 or 64 (or 0 in synced code)
+ FBOFBO
++ +
GLEW_EXT_framebuffer_blit
+ GLEW_EXT_framebuffer_blit
+ + +
+ + +depth
+ attachment
+
+
+
+ stencil
+ attachment
+
+
+
+ color0
+ attachment
+
+
+
+ color1
+ attachment
+
+
+
+ color2
+ attachment
+
+
+
+ colorn
+ attachment
+
+
+
+ color15
+ attachment
+
+
+
+ drawbuffers
+ table
+ { GL_COLOR_ATTACHMENT0_EXT, GL_COLOR_ATTACHMENT3_EXT, ..}
+ + + This doesn't delete the attached objects! +
+ + +fbo
+ fbo
+
+
+
+ + +
+ + +fbo
+ fbo
+
+
+
+ target
+ number
+
+
+
+ (optional)
+ + +
+ + +fbo
+ fbo
+
+
+
+ target
+ number
+
+
+
+ (optional)
+ identities
+ bool
+
+
+
+ (optional)
+ lua_function
+ func
+
+
+
+ (optional)
+ arg1
+
+
+
+ (optional)
+ arg2
+
+
+
+ (optional)
+ argn
+
+
+
+ (optional)
+ needs `GLEW_EXT_framebuffer_blit`
++ +
+ + +x0Src
+ number
+
+
+
+ y0Src
+ number
+
+
+
+ x1Src
+ number
+
+
+
+ y1Src
+ number
+
+
+
+ x0Dst
+ number
+
+
+
+ y0Dst
+ number
+
+
+
+ x1Dst
+ number
+
+
+
+ y1Dst
+ number
+
+
+
+ mask
+ number
+
+
+
+ (default GL_COLOR_BUFFER_BIT)
+ filter
+ number
+
+
+
+ (default GL_NEAREST)
+ needs `GLEW_EXT_framebuffer_blit`
++ +
+ + +fboSrc
+ fbo
+
+
+
+ x0Src
+ number
+
+
+
+ y0Src
+ number
+
+
+
+ x1Src
+ number
+
+
+
+ y1Src
+ number
+
+
+
+ fboDst
+ fbo
+
+
+
+ x0Dst
+ number
+
+
+
+ y0Dst
+ number
+
+
+
+ x1Dst
+ number
+
+
+
+ y1Dst
+ number
+
+
+
+ mask
+ number
+
+
+
+ (default GL_COLOR_BUFFER_BIT)
+ filter
+ number
+
+
+
+ (default GL_NEAREST)
+ + + attachment ::= luaTex or `RBO.rbo` or nil or { luaTex [, num target [, num level ] ] } +
+ + + + + + +User Data FBO
++ +
+ + +depth
+ attachment
+
+
+
+ stencil
+ attachment
+
+
+
+ color0
+ attachment
+
+
+
+ color1
+ attachment
+
+
+
+ color2
+ attachment
+
+
+
+ colorn
+ attachment
+
+
+
+ color15
+ attachment
+
+
+
+ drawbuffers
+ table
+ { GL_COLOR_ATTACHMENT0_EXT, GL_COLOR_ATTACHMENT3_EXT, ..}
+ readbuffer
+ table
+ GL_COLOR_ATTACHMENT0_EXT
+ GLOpenGL Constants
++ +
+ +
+ + +POINTS
+ number
+
+
+
+ LINES
+ number
+
+
+
+ LINE_LOOP
+ number
+
+
+
+ LINE_STRIP
+ number
+
+
+
+ TRIANGLES
+ number
+
+
+
+ TRIANGLE_STRIP
+ number
+
+
+
+ TRIANGLE_FAN
+ number
+
+
+
+ QUADS
+ number
+
+
+
+ QUAD_STRIP
+ number
+
+
+
+ POLYGON
+ number
+
+
+
+ PATCHES
+ number
+
+
+
+ + +
+ + +ZERO
+ number
+
+
+
+ ONE
+ number
+
+
+
+ SRC_COLOR
+ number
+
+
+
+ ONE_MINUS_SRC_COLOR
+ number
+
+
+
+ SRC_ALPHA
+ number
+
+
+
+ ONE_MINUS_SRC_ALPHA
+ number
+
+
+
+ DST_ALPHA
+ number
+
+
+
+ ONE_MINUS_DST_ALPHA
+ number
+
+
+
+ + +
+ + +ZERO
+ number
+
+
+
+ ONE
+ number
+
+
+
+ SRC_COLOR
+ number
+
+
+
+ ONE_MINUS_SRC_COLOR
+ number
+
+
+
+ SRC_ALPHA
+ number
+
+
+
+ ONE_MINUS_SRC_ALPHA
+ number
+
+
+
+ DST_ALPHA
+ number
+
+
+
+ ONE_MINUS_DST_ALPHA
+ number
+
+
+
+ DST_COLOR
+ number
+
+
+
+ ONE_MINUS_DST_COLOR
+ number
+
+
+
+ SRC_ALPHA_SATURATE
+ number
+
+
+
+ FUNC_ADD
+ number
+
+
+
+ FUNC_SUBTRACT
+ number
+
+
+
+ FUNC_REVERSE_SUBTRACT
+ number
+
+
+
+ MIN
+ number
+
+
+
+ MAX
+ number
+
+
+
+ + +
+ + +NEVER
+ number
+
+
+
+ LESS
+ number
+
+
+
+ EQUAL
+ number
+
+
+
+ LEQUAL
+ number
+
+
+
+ GREATER
+ number
+
+
+
+ NOTEQUAL
+ number
+
+
+
+ GEQUAL
+ number
+
+
+
+ ALWAYS
+ number
+
+
+
+ + +
+ + +CLEAR
+ number
+
+
+
+ AND
+ number
+
+
+
+ AND_REVERSE
+ number
+
+
+
+ COPY
+ number
+
+
+
+ AND_INVERTED
+ number
+
+
+
+ NOOP
+ number
+
+
+
+ XOR
+ number
+
+
+
+ OR
+ number
+
+
+
+ NOR
+ number
+
+
+
+ EQUIV
+ number
+
+
+
+ INVERT
+ number
+
+
+
+ OR_REVERSE
+ number
+
+
+
+ COPY_INVERTED
+ number
+
+
+
+ OR_INVERTED
+ number
+
+
+
+ NAND
+ number
+
+
+
+ SET
+ number
+
+
+
+ + +
+ + +BACK
+ number
+
+
+
+ FRONT
+ number
+
+
+
+ FRONT_AND_BACK
+ number
+
+
+
+ + +
+ + +POINT
+ number
+
+
+
+ LINE
+ number
+
+
+
+ FILL
+ number
+
+
+
+ + +
+ + +DEPTH_BUFFER_BIT
+ number
+
+
+
+ ACCUM_BUFFER_BIT
+ number
+
+
+
+ STENCIL_BUFFER_BIT
+ number
+
+
+
+ COLOR_BUFFER_BIT
+ number
+
+
+
+ + +
+ + +FLAT
+ number
+
+
+
+ SMOOTH
+ number
+
+
+
+ + +
+ + +MODELVIEW
+ number
+
+
+
+ PROJECTION
+ number
+
+
+
+ TEXTURE
+ number
+
+
+
+ + +
+ + +NEAREST
+ number
+
+
+
+ LINEAR
+ number
+
+
+
+ NEAREST_MIPMAP_NEAREST
+ number
+
+
+
+ LINEAR_MIPMAP_NEAREST
+ number
+
+
+
+ NEAREST_MIPMAP_LINEAR
+ number
+
+
+
+ LINEAR_MIPMAP_LINEAR
+ number
+
+
+
+ + +
+ + +REPEAT
+ number
+
+
+
+ MIRRORED_REPEAT
+ number
+
+
+
+ CLAMP
+ number
+
+
+
+ CLAMP_TO_EDGE
+ number
+
+
+
+ CLAMP_TO_BORDER
+ number
+
+
+
+ + +
+ + +TEXTURE_ENV
+ number
+
+
+
+ TEXTURE_ENV_MODE
+ number
+
+
+
+ TEXTURE_ENV_COLOR
+ number
+
+
+
+ MODULATE
+ number
+
+
+
+ DECAL
+ number
+
+
+
+ BLEND
+ number
+
+
+
+ REPLACE
+ number
+
+
+
+ + +
+ + +GL_TEXTURE_FILTER_CONTROL
+
+
+
+ + +
+ + +GL_TEXTURE_LOD_BIAS
+
+
+
+ + +
+ + +TEXTURE_GEN_MODE
+ number
+
+
+
+ EYE_PLANE
+ number
+
+
+
+ OBJECT_PLANE
+ number
+
+
+
+ EYE_LINEAR
+ number
+
+
+
+ OBJECT_LINEAR
+ number
+
+
+
+ SPHERE_MAP
+ number
+
+
+
+ NORMAL_MAP
+ number
+
+
+
+ REFLECTION_MAP
+ number
+
+
+
+ S
+ number
+
+
+
+ T
+ number
+
+
+
+ R
+ number
+
+
+
+ Q
+ number
+
+
+
+ + +
+ + +CURRENT_BIT
+ number
+
+
+
+ POINT_BIT
+ number
+
+
+
+ LINE_BIT
+ number
+
+
+
+ POLYGON_BIT
+ number
+
+
+
+ POLYGON_STIPPLE_BIT
+ number
+
+
+
+ PIXEL_MODE_BIT
+ number
+
+
+
+ LIGHTING_BIT
+ number
+
+
+
+ FOG_BIT
+ number
+
+
+
+ DEPTH_BUFFER_BIT
+ number
+
+
+
+ ACCUM_BUFFER_BIT
+ number
+
+
+
+ STENCIL_BUFFER_BIT
+ number
+
+
+
+ VIEWPORT_BIT
+ number
+
+
+
+ TRANSFORM_BIT
+ number
+
+
+
+ ENABLE_BIT
+ number
+
+
+
+ COLOR_BUFFER_BIT
+ number
+
+
+
+ HINT_BIT
+ number
+
+
+
+ EVAL_BIT
+ number
+
+
+
+ LIST_BIT
+ number
+
+
+
+ TEXTURE_BIT
+ number
+
+
+
+ SCISSOR_BIT
+ number
+
+
+
+ ALL_ATTRIB_BITS
+ number
+
+
+
+ + +
+ + +FOG_HINT
+ number
+
+
+
+ LINE_SMOOTH_HINT
+ number
+
+
+
+ POINT_SMOOTH_HINT
+ number
+
+
+
+ POLYGON_SMOOTH_HINT
+ number
+
+
+
+ PERSPECTIVE_CORRECTION_HINT
+ number
+
+
+
+ + +
+ + +DONT_CARE
+ number
+
+
+
+ FASTEST
+ number
+
+
+
+ NICEST
+ number
+
+
+
+ + +
+ + +AMBIENT
+ number
+
+
+
+ DIFFUSE
+ number
+
+
+
+ SPECULAR
+ number
+
+
+
+ POSITION
+ number
+
+
+
+ SPOT_DIRECTION
+ number
+
+
+
+ SPOT_EXPONENT
+ number
+
+
+
+ SPOT_CUTOFF
+ number
+
+
+
+ CONSTANT_ATTENUATION
+ number
+
+
+
+ LINEAR_ATTENUATION
+ number
+
+
+
+ QUADRATIC_ATTENUATION
+ number
+
+
+
+ + +
+ + +VERTEX_SHADER
+ number
+
+
+
+ TESS_CONTROL_SHADER
+ number
+
+
+
+ TESS_EVALUATION_SHADER
+ number
+
+
+
+ GEOMETRY_SHADER
+ number
+
+
+
+ FRAGMENT_SHADER
+ number
+
+
+
+ + +
+ + +GEOMETRY_INPUT_TYPE
+ number
+
+
+
+ GEOMETRY_OUTPUT_TYPE
+ number
+
+
+
+ GEOMETRY_VERTICES_OUT
+ number
+
+
+
+ + +
+ + +PATCH_VERTICES
+ number
+
+
+
+ PATCH_DEFAULT_OUTER_LEVEL
+ number
+
+
+
+ PATCH_DEFAULT_INNER_LEVEL
+ number
+
+
+
+ + +
+ + +BYTE
+ number
+
+
+
+ UNSIGNED_BYTE
+ number
+
+
+
+ SHORT
+ number
+
+
+
+ UNSIGNED_SHORT
+ number
+
+
+
+ INT
+ number
+
+
+
+ UNSIGNED_INT
+ number
+
+
+
+ FLOAT
+ number
+
+
+
+ FLOAT_VEC4
+ number
+
+
+
+ INT_VEC4
+ number
+
+
+
+ UNSIGNED_INT_VEC4
+ number
+
+
+
+ FLOAT_MAT4
+ number
+
+
+
+ + +
+ + +ELEMENT_ARRAY_BUFFER
+ number
+
+
+
+ ARRAY_BUFFER
+ number
+
+
+
+ UNIFORM_BUFFER
+ number
+
+
+
+ SHADER_STORAGE_BUFFER
+ number
+
+
+
+ + +
+ +
+ + +GL_COLOR_ATTACHMENT0_EXT
+ 0x8CE0
+ + +
+ + +GL_COLOR_ATTACHMENT1_EXT
+ 0x8CE1
+ + +
+ + +GL_COLOR_ATTACHMENT2_EXT
+ 0x8CE2
+ + +
+ + +GL_COLOR_ATTACHMENT3_EXT
+ 0x8CE3
+ + +
+ + +GL_COLOR_ATTACHMENT4_EXT
+ 0x8CE4
+ + +
+ + +GL_COLOR_ATTACHMENT5_EXT
+ 0x8CE5
+ + +
+ + +GL_COLOR_ATTACHMENT6_EXT
+ 0x8CE6
+ + +
+ + +GL_COLOR_ATTACHMENT7_EXT
+ 0x8CE7
+ + +
+ + +GL_COLOR_ATTACHMENT8_EXT
+ 0x8CE8
+ + +
+ + +GL_COLOR_ATTACHMENT9_EXT
+ 0x8CE9
+ + +
+ + +GL_COLOR_ATTACHMENT10_EXT
+ 0x8CEA
+ + +
+ + +GL_COLOR_ATTACHMENT11_EXT
+ 0x8CEB
+ + +
+ + +GL_COLOR_ATTACHMENT12_EXT
+ 0x8CEC
+ + +
+ + +GL_COLOR_ATTACHMENT13_EXT
+ 0x8CED
+ + +
+ + +GL_COLOR_ATTACHMENT14_EXT
+ 0x8CEE
+ + +
+ + +GL_COLOR_ATTACHMENT15_EXT
+ 0x8CEF
+ + +
+ + +GL_DEPTH_ATTACHMENT_EXT
+ 0x8D00
+ + +
+ + +GL_STENCIL_ATTACHMENT_EXT
+ 0x8D20
+ + +
+ +
+ + +GL_RGBA16F_ARB
+ 0x881A
+ + +
+ + +GL_RGBA32F_ARB
+ 0x8814
+ + +
+ + +GL_DEPTH_COMPONENT
+ 0x1902
+ + +
+ +
+ + +GL_RGB
+ 0x1907
+ + +
+ + +GL_RGBA
+ 0x1908
+ + +
+ + +GL_DEPTH_COMPONENT
+ 0x1902
+ + +
+ + +GL_STENCIL_INDEX
+ 0x1901
+ + +
+ +
+ + +GL_FRAMEBUFFER_EXT
+ 0x8D40
+ + +
+ + +GL_READ_FRAMEBUFFER_EXT
+ 0x8CA8
+ + +
+ + +GL_DRAW_FRAMEBUFFER_EXT
+ 0x8CA9
+ + +
+ +
+ + +GL_FRAMEBUFFER_COMPLETE_EXT
+ 0x8CD5
+ + +
+ + +GL_FRAMEBUFFER_INCOMPLETE_ATTACHMENT_EXT
+ 0x8CD6
+ + +
+ + +GL_FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT_EXT
+ 0x8CD7
+ + +
+ + +GL_FRAMEBUFFER_INCOMPLETE_DUPLICATE_ATTACHMENT_EXT
+ 0x8CD8
+ + +
+ + +GL_FRAMEBUFFER_INCOMPLETE_DIMENSIONS_EXT
+ 0x8CD9
+ + +
+ + +GL_FRAMEBUFFER_INCOMPLETE_FORMATS_EXT
+ 0x8CDA
+ + +
+ + +GL_FRAMEBUFFER_INCOMPLETE_DRAW_BUFFER_EXT
+ 0x8CDB
+ + +
+ + +GL_FRAMEBUFFER_INCOMPLETE_READ_BUFFER_EXT
+ 0x8CDC
+ + +
+ + +GL_FRAMEBUFFER_UNSUPPORTED_EXT
+ 0x8CDD
+ + +
+ + +GL_FRAMEBUFFER_STATUS_ERROR_EXT
+ 0x8CDE
+ GameGame constants
++ +
Game specific information
++ +
+ + +maxUnits
+ number
+
+
+
+ maxTeams
+ number
+
+
+
+ maxPlayers
+ number
+
+
+
+ squareSize
+ number
+ Divide Game.mapSizeX or Game.mapSizeZ by this to get engine's "mapDims" coordinates. The resolution of height, yard and type maps.
+ metalMapSquareSize
+ number
+ The resolution of metalmap (for use in API such as Spring.GetMetalAmount etc.)
+ gameSpeed
+ number
+
+
+
+ startPosType
+ number
+
+
+
+ ghostedBuildings
+ bool
+
+
+
+ mapChecksum
+ string
+
+
+
+ modChecksum
+ string
+
+
+
+ mapDamage
+ bool
+
+
+
+ mapName
+ string
+
+
+
+ mapDescription
+ string
+ = string Game.mapHumanName
+ mapHardness
+ number
+
+
+
+ mapX
+ number
+
+
+
+ mapY
+ number
+
+
+
+ mapSizeX
+ number
+ in worldspace/opengl coords. Divide by Game.squareSize to get engine's "mapDims" coordinates
+ mapSizeZ
+ number
+ in worldspace/opengl coords. Divide by Game.squareSize to get engine's "mapDims" coordinates
+ gravity
+ number
+
+
+
+ tidal
+ number
+
+
+
+ windMin
+ number
+
+
+
+ windMax
+ number
+
+
+
+ extractorRadius
+ number
+
+
+
+ waterDamage
+ number
+
+
+
+ envDamageTypes
+ table
+ Containing {def}IDs of environmental-damage sources
+ gameName
+ string
+
+
+
+ gameShortName
+ string
+
+
+
+ gameVersion
+ string
+
+
+
+ gameMutator
+ string
+
+
+
+ gameDesc
+ string
+
+
+
+ requireSonarUnderWater
+ bool
+
+
+
+ transportAir
+ number
+
+
+
+ transportShip
+ number
+
+
+
+ transportHover
+ number
+
+
+
+ transportGround
+ number
+
+
+
+ fireAtKilled
+ number
+
+
+
+ fireAtCrashing
+ number
+
+
+
+ constructionDecay
+ bool
+
+
+
+ reclaimAllowEnemies
+ bool
+
+
+
+ reclaimAllowAllies
+ bool
+
+
+
+ constructionDecayTime
+ number
+
+
+
+ constructionDecaySpeed
+ number
+
+
+
+ multiReclaim
+ number
+
+
+
+ reclaimMethod
+ number
+
+
+
+ reclaimUnitMethod
+ number
+
+
+
+ reclaimUnitEnergyCostFactor
+ number
+
+
+
+ reclaimUnitEfficiency
+ number
+
+
+
+ reclaimFeatureEnergyCostFactor
+ number
+
+
+
+ repairEnergyCostFactor
+ number
+
+
+
+ resurrectEnergyCostFactor
+ number
+
+
+
+ captureEnergyCostFactor
+ number
+
+
+
+ springCategories
+ table
+
+
+ example: {
+ ["vtol"] = 0, ["special"] = 1, ["noweapon"] = 2,
+ ["notair"] = 3, ["notsub"] = 4, ["all"] = 5,
+ ["weapon"] = 6, ["notship"] = 7, ["notland"] = 8,
+ ["mobile"] = 9, ["kbot"] = 10, ["antigator"] = 11,
+ ["tank"] = 12, ["plant"] = 13, ["ship"] = 14,
+ ["antiemg"] = 15, ["antilaser"] = 16, ["antiflame"] = 17,
+ ["underwater"] = 18, ["hover"] = 19, ["phib"] = 20,
+ ["constr"] = 21, ["strategic"] = 22, ["commander"] = 23,
+ ["paral"] = 24, ["jam"] = 25, ["mine"] = 26,
+ ["kamikaze"] = 27, ["minelayer"] = 28, ["notstructure"] = 29,
+ ["air"] = 30
+ }
+armorTypes
+ table
+
+(bidirectional)
+ example: {
+ [1] = amphibious, [2] = anniddm, [3] = antibomber,
+ [4] = antifighter, [5] = antiraider, [6] = atl,
+ [7] = blackhydra, [8] = bombers, [9] = commanders,
+ [10] = crawlingbombs, ...
+
+ ["amphibious"] = 1, ["anniddm"] = 2, ["antibomber"] = 3
+ ["antifighter"] = 4, ["antiraider"] = 5, ["atl"] = 6
+ ["blackhydra"] = 7, ["bombers"] = 8, ["commanders"] = 9
+ ["crawlingbombs"]= 10, ...
+ }
+LuaHandleCallins, functions called by the Engine
++ + +
This page is future looking to unified widget/gadget (aka "addon") handler, which may yet be some way off, c.f. the changelog.
+ +Related Sourcecode: LuaHandle.cpp
+ +For now, to use these addons in a widget, prepend widget: and, for a gadget, prepend gadget:. For example,
+ + ++function widget:UnitCreated(unitID, unitDefID, unitTeam, builderID) + ... +end ++ +
Some functions may differ between (synced) gadget and widgets; those are in the Synced - Unsynced Shared section. Essentially the reason is that all information should be available to synced (game logic controlling) gadgets, but restricted to unsynced gadget/widget (e.g. information about an enemy unit only detected via radar and not yet in LOS). In such cases the full (synced) param list is documented.
+ +Attention: some callins will only work on the unsynced portion of the gadget. Due to the type-unsafe nature of lua parsing, those callins not firing up might be hard to trace. This document will be continuously updated to properly alert about those situations.
+ +Spring.KillTeam).
+ Spring.SendLuaRulesMsg or Spring.SendLuaUIMsg.
+ AllowCommand returns true.
+ Spring.SetExperienceGrade.
+ Spring.SetMapShader (convenient for setting uniforms).
+ Spring.SetMapShader (convenient for setting uniforms).
+ Spring.IsAbove returns true.
+ + +
Called when a team dies (see `Spring.KillTeam`).
++ +
+ + +teamID
+ number
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ Called whenever a player's status changes e.g.
++ becoming a spectator. + +
+ + +playerID
+ number
+
+
+
+ Called whenever a new player joins the game.
++ +
+ + +playerID
+ number
+
+
+
+ Called whenever a player is removed from the game.
+ ++ +
Called when the projectile is created.
++ + + Note that weaponDefID is missing if the projectile is spawned as part of a burst, but `Spring.GetProjectileDefID` and `Spring.GetProjectileName` still work in callin scope using proID. + +
+ + +proID
+ number
+
+
+
+ proOwnerID
+ number
+
+
+
+ weaponDefID
+ number
+
+
+
+ Called when the projectile is destroyed.
++ +
+ + +proID
+ number
+
+
+
+ ownerID
+ number
+
+
+
+ proWeaponDefID
+ number
+
+
+
+ Called when an explosion occurs.
++ +
+ + +weaponDefID
+ number
+
+
+
+ px
+ number
+
+
+
+ py
+ number
+
+
+
+ pz
+ number
+
+
+
+ attackerID
+ number
+
+
+
+ projectileID
+ number
+
+
+
+ Called when a units stockpile of weapons increases or decreases.
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ weaponNum
+ number
+
+
+
+ oldCount
+ number
+
+
+
+ newCount
+ number
+
+
+
+ Receives messages from unsynced sent via `Spring.SendLuaRulesMsg` or `Spring.SendLuaUIMsg`.
+ +Called when a chat command '/save' or '/savegame' is received.
++ +
+ + +zip
+ table
+ a userdatum representing the savegame zip file. See Lua_SaveLoad.
+ Called when the unsynced copy of the height-map is altered.
++ +
+ + + +Called for every draw frame (including when the game is paused) and at least once per sim frame except when catching up.
++ +
+ + +dt
+ number
+ the time since the last update.
+ Called whenever the window is resized.
++ +
+ + +viewSizeX
+ number
+
+
+
+ viewSizeY
+ number
+
+
+
+ + +
+ + + + + + +Used to set the default command when a unit is selected.
++ First parameter is the type of the object pointed at (either "unit or "feature") and the second is its unitID or featureID respectively. + +
+ + +type
+ string
+ "unit" | "feature"
+ id
+ int
+ unitID | featureID
+ + +
Called when a feature is created.
++ +
+ + +featureID
+ number
+
+
+
+ allyTeamID
+ number
+
+
+
+ Called when a feature is destroyed.
++ +
+ + +featureID
+ number
+
+
+
+ allyTeamID
+ number
+
+
+
+ Called when a feature is damaged.
++ +
+ + +featureID
+ number
+
+
+
+ featureDefID
+ number
+
+
+
+ featureTeam
+ number
+
+
+
+ damage
+ number
+
+
+
+ weaponDefID
+ number
+
+
+
+ projectileID
+ number
+
+
+
+ attackerID
+ number
+
+
+
+ attackerDefID
+ number
+
+
+
+ attackerTeam
+ number
+
+
+
+ + +
Called when the addon is (re)loaded.
++ +
+ + + + + + +Called when the game is (re)loaded.
++ +
+ + + + + + +Called when the addon or the game is shutdown.
++ +
+ + + +Called when a player issues a UI command e.g.
++ types /foo or /luarules foo. + +
+ + +msg
+ string
+
+
+
+ playerID
+ number
+
+
+
+ Called after `GamePreload` and before `GameStart`.
+ +Called before the 0 gameframe.
++ + + Is not called when a saved game is loaded. + +
+ + + + + + +Called upon the start of the game.
++ + + Is not called when a saved game is loaded. + +
+ + + + + + +Called when the game ends
++ +
+ + +winningAllyTeams
+ {number,...}
+ list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).
+ Called when the game is paused.
++ +
+ + +playerID
+ number
+
+
+
+ paused
+ bool
+
+
+
+ Called for every game simulation frame (30 per second).
++ +
+ + +frame
+ number
+ Starts at frame 1
+ Called once to deliver the gameID
+ +Called at the moment the unit is created.
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ builderID
+ number
+
+
+
+ (optional)
+ Called at the moment the unit is completed.
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ Called when a factory finishes construction of a unit.
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ factID
+ number
+
+
+
+ factDefID
+ number
+
+
+
+ userOrders
+ bool
+
+
+
+ Called when a living unit becomes a nanoframe again.
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ Called when a unit is destroyed.
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ attackerID
+ number
+
+
+
+ attackerDefID
+ number
+
+
+
+ attackerTeam
+ number
+
+
+
+ Called when a unit is transferred between teams.
++ This is called before `UnitGiven` and in that moment unit is still assigned to the oldTeam. + +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ oldTeam
+ number
+
+
+
+ newTeam
+ number
+
+
+
+ Called when a unit is transferred between teams.
++ This is called after `UnitTaken` and in that moment unit is assigned to the newTeam. + +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ oldTeam
+ number
+
+
+
+ newTeam
+ number
+
+
+
+ Called when a unit is idle (empty command queue).
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ Called after when a unit accepts a command, after `AllowCommand` returns true.
++ +
+ + +Called when a unit completes a command.
++ +
+ + +Called when a unit is damaged (after UnitPreDamaged).
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ damage
+ number
+
+
+
+ paralyzer
+ number
+
+
+
+ weaponDefID
+ number
+
+
+
+ projectileID
+ number
+
+
+
+ attackerID
+ number
+
+
+
+ attackerDefID
+ number
+
+
+
+ attackerTeam
+ number
+
+
+
+ Called when a unit changes its stun status.
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ stunned
+ bool
+
+
+
+ Called when a unit gains experience greater or equal to the minimum limit set by calling `Spring.SetExperienceGrade`.
++ + + Should be called more reliably with small values of experience grade. + +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ experience
+ number
+
+
+
+ oldExperience
+ number
+
+
+
+ Called when a unit's harvestStorage is full (according to its unitDef's entry).
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ Called when a unit emits a seismic ping.
++ + + See `seismicSignature`. + +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ strength
+ number
+
+
+
+ allyTeam
+ number
+
+
+
+ unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ Called when a unit enters radar of an allyteam.
++ + + Also called when a unit enters LOS without any radar coverage. + +
+ + +unitID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ allyTeam
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ Called when a unit enters LOS of an allyteam.
++ + + Its called after the unit is in LOS, so you can query that unit. + +
+ + +unitID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ allyTeam
+ number
+ who's LOS the unit entered.
+ unitDefID
+ number
+
+
+
+ Called when a unit leaves radar of an allyteam.
++ + + Also called when a unit leaves LOS without any radar coverage. + For widgets, this is called just after a unit leaves radar coverage, so widgets cannot get the position of units that left their radar. + +
+ + +unitID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ allyTeam
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ Called when a unit leaves LOS of an allyteam.
++ + + For widgets, this one is called just before the unit leaves los, so you can still get the position of a unit that left los. + +
+ + +unitID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ allyTeam
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ + +
Called when a unit is loaded by a transport.
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ transportID
+ number
+
+
+
+ transportTeam
+ number
+
+
+
+ Called when a unit is unloaded by a transport.
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ transportID
+ number
+
+
+
+ transportTeam
+ number
+
+
+
+ + +
+ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ Called when a unit cloaks.
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ Called when a unit decloaks.
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ Called when two units collide.
++ + + Both units must be registered with `Script.SetWatchUnit`. + +
+ + +colliderID
+ number
+
+
+
+ collideeID
+ number
+
+
+
+ Called when a unit collides with a feature.
++ + + The unit must be registered with `Script.SetWatchUnit` and the feature registered with `Script.SetWatchFeature`. + +
+ + +colliderID
+ number
+
+
+
+ collideeID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ Called just before a unit is invalid, after it finishes its death animation.
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ Inside the Draw* functions, you can use the Lua OpenGL Api to draw graphics.
+ +Avoid doing heavy calculations inside these callins; ideally, do the calculations elsewhere and use Draw callins only for drawing.
+Use this callin to update textures, shaders, etc.
++ + + Doesn't render to screen! + Also available to LuaMenu. +
+ + + + + + +Spring draws command queues, 'map stuff', and map marks.
++ +
+ + + + + + +Spring draws units, features, some water types, cloaked units, and the sun.
++ +
+ + + + + + +Called before decals are drawn
++ +
+ + + + + + ++ +
+ + + + + + ++ +
+ + + + + + +Invoked after semi-transparent shadows pass is about to conclude
++ + + This callin has depth and color buffer of shadowmap bound via FBO as well as the FFP state to do "semi-transparent" shadows pass (traditionally only used to draw shadows of shadow casting semi-transparent particles). Can be used to draw nice colored shadows. +
+ + + + + + ++ +
+ + + + + + ++ +
+ + + + + + ++ +
+ + + + + + +Runs at the start of the forward pass when a custom map shader has been assigned via `Spring.SetMapShader` (convenient for setting uniforms).
++ +
+ + + + + + ++ +
+ + + + + + +Runs at the start of the deferred pass when a custom map shader has been assigned via `Spring.SetMapShader` (convenient for setting uniforms).
++ +
+ + + + + + ++ +
+ + + + + + +This runs at the end of its respective deferred pass.
++ + + Allows proper frame compositing (with ground flashes/decals/foliage/etc, which are drawn between it and `DrawWorldPreUnit`) via `gl.CopyToTexture`. +
+ + + + + + +Runs at the end of the unit deferred pass.
++ + + Informs Lua code it should make use of the $model_gbuffer_* textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and DrawWorld via gl.CopyToTexture). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled. +
+ + + + + + +Runs at the end of the feature deferred pass to inform Lua code it should make use of the $model_gbuffer_* textures before another pass overwrites them (and to allow proper blending with e.g.
++ cloaked objects which are drawn between these events and DrawWorld via gl.CopyToTexture). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled. + +
+ + + + + + ++ +
+ + + + + + ++ +
+ + + + + + +Also available to LuaMenu.
++ +
+ + +viewSizeX
+ number
+
+
+
+ viewSizeY
+ number
+
+
+
+ + +
+ + +viewSizeX
+ number
+
+
+
+ viewSizeY
+ number
+
+
+
+ Similar to DrawScreenEffects, this can be used to alter the contents of a frame after it has been completely rendered (i.e.
++ World, MiniMap, Menu, UI). + +
+ + +viewSizeX
+ number
+
+
+
+ viewSizeY
+ number
+
+
+
+ + +
+ + +sx
+ number
+ relative to the minimap's position and scale.
+ sy
+ number
+ relative to the minimap's position and scale.
+ + +
+ + +sx
+ number
+ relative to the minimap's position and scale.
+ sy
+ number
+ relative to the minimap's position and scale.
+ Called every 60 frames, calculating delta between `GameFrame` and `GameProgress`.
++ + + Can give an ETA about catching up with simulation for mid-game join players. + +
+ + +serverFrameNum
+ int
+
+
+
+ Called when the keymap changes
++ + + Can be caused due to a change in language or keyboard +
+ + + + + + +Key Modifier Params
++ +
+ + +right
+ bool
+ Right mouse key pressed
+ alt
+ bool
+ Alt key pressed
+ ctrl
+ bool
+ Ctrl key pressed
+ shift
+ bool
+ Shift key pressed
+ Called repeatedly when a key is pressed down.
++ + + Return true if you don't want other callins or the engine to also receive this keypress. A list of key codes can be seen at the SDL wiki. + +
+ + +keyCode
+ number
+
+
+
+ mods
+ mods
+
+
+
+ isRepeat
+ bool
+ If you want an action to occur only once check for isRepeat == false.
+ label
+ bool
+ the name of the key
+ utf32char
+ number
+ (deprecated) always 0
+ scanCode
+ number
+
+
+
+ actionList
+ table
+ the list of actions for this keypress
+ Called when the key is released.
++ +
+ + +keyCode
+ number
+
+
+
+ mods
+ mods
+
+
+
+ label
+ bool
+ the name of the key
+ utf32char
+ number
+ (deprecated) always 0
+ scanCode
+ number
+
+
+
+ actionList
+ table
+ the list of actions for this keyrelease
+ Called whenever a key press results in text input.
+ ++ +
+ + +utf8
+ string
+
+
+
+ start
+ number
+
+
+
+ length
+ number
+
+
+
+ Called when a mouse button is pressed.
++ + + The button parameter supports up to 7 buttons. Must return true for `MouseRelease` and other functions to be called. + +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ button
+ number
+
+
+
+ Called when a mouse button is released.
++ + + Please note that in order to have Spring call `Spring.MouseRelease`, you need to have a `Spring.MousePress` call-in in the same addon that returns true. + +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ button
+ number
+
+
+
+ Called when the mouse is moved.
++ +
+ + +x
+ number
+ final x position
+ y
+ number
+ final y position
+ dx
+ number
+ distance travelled in x
+ dy
+ number
+ distance travelled in y
+ button
+ number
+
+
+
+ Called when the mouse wheel is moved.
++ +
+ + +up
+ bool
+ the direction
+ value
+ number
+ the amount travelled
+ Called every `Update`.
++ + + Must return true for `Mouse*` events and `Spring.GetToolTip` to be called. + +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ Called when `Spring.IsAbove` returns true.
++ +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ Parameters for command options
++ +
+ + +coded
+ int
+
+
+
+ alt
+ bool
+
+
+
+ ctrl
+ bool
+
+
+
+ shift
+ bool
+
+
+
+ right
+ bool
+
+
+
+ meta
+ bool
+
+
+
+ internal
+ bool
+
+
+
+ Called when a command is issued.
++ +
+ + +Called when text is entered into the console (e.g.
++ `Spring.Echo`). + +
+ + +msg
+ string
+
+
+
+ priority
+ int
+
+
+
+ Called when a unit is added to or removed from a control group.
++ +
+ + +groupID
+ number
+
+
+
+ + +
+ + +ttType
+ string
+ "unit" | "feature" | "ground" | "selection"
+ data1
+ number
+ unitID | featureID | posX
+ data2
+ number
+ posY
+ (optional)
+ data3
+ number
+ posZ
+ (optional)
+ + +
+ + +playerID
+ number
+
+
+
+ type
+ string
+ "point" | "line" | "erase"
+ posX
+ number
+
+
+
+ posY
+ number
+
+
+
+ posZ
+ number
+
+
+
+ data4
+ string or number
+ point: label, erase: radius, line: pos2X
+ pos2Y
+ number
+ when type is line
+ (optional)
+ pos2Z
+ number
+ when type is line
+ (optional)
+ + +
+ + +Called when a Pr-downloader download is queued
++ +
+ + +Called when a Pr-downloader download is started via VFS.DownloadArchive.
++ +
+ + +id
+ number
+
+
+
+ Called when a Pr-downloader download finishes successfully.
++ +
+ + +id
+ number
+
+
+
+ Called when a Pr-downloader download fails to complete.
++ +
+ + +id
+ number
+
+
+
+ errorID
+ number
+
+
+
+ Called incrementally during a Pr-downloader download.
++ +
+ + +id
+ number
+
+
+
+ downloaded
+ number
+
+
+
+ total
+ number
+
+
+
+ LuaHandleSyncedCallins, functions called by the Engine (Synced)
++ +
+SendToUnsynced callout.
+ + +
Receives data sent via `SendToUnsynced` callout.
++ +
+ + +arg1
+ any
+
+
+
+ arg2
+ any
+
+
+
+ argn
+ any
+
+
+
+ For the following calls drawMode can be one of the following, notDrawing = 0, normalDraw = 1, shadowDraw = 2, reflectionDraw = 3, refractionDraw = 4, and finally gameDeferredDraw = 5 which was added in 102.0.
+For custom rendering of units
++ +
+ + +unitID
+ number
+
+
+
+ drawMode
+ number
+
+
+
+ For custom rendering of features
++ +
+ + +featureID
+ number
+
+
+
+ drawMode
+ number
+
+
+
+ For custom rendering of shields.
++ +
+ + +featureID
+ number
+
+
+
+ weaponID
+ number
+
+
+
+ drawMode
+ number
+
+
+
+ For custom rendering of weapon (& other) projectiles
++ +
+ + +projectileID
+ number
+
+
+
+ drawMode
+ number
+
+
+
+ + +
+ + +uuid
+ number
+
+
+
+ drawMode
+ number
+
+
+
+ Called when the unit reaches an unknown command in its queue (i.e.
++ one not handled by the engine). + +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ cmdID
+ number
+
+
+
+ cmdParams
+ {number,...}
+
+
+
+ cmdOptions
+ cmdOptions
+
+
+
+ cmdTag
+ number
+
+
+
+ Called when the command is given, before the unit's queue is altered.
++ + + The queue remains untouched when a command is blocked, whether it would be queued or replace the queue. + +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ cmdID
+ number
+
+
+
+ cmdParams
+ {number,...}
+
+
+
+ cmdOptions
+ cmdOptions
+
+
+
+ cmdTag
+ number
+
+
+
+ synced
+ bool
+
+
+
+ fromLua
+ bool
+
+
+
+ Called just before unit is created.
++ +
+ + +unitDefID
+ number
+
+
+
+ builderID
+ number
+
+
+
+ builderTeam
+ number
+
+
+
+ x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ facing
+ number
+
+
+
+ Called just before a unit is transferred to a different team.
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ oldTeam
+ number
+
+
+
+ newTeam
+ number
+
+
+
+ capture
+ bool
+
+
+
+ Called just before a unit progresses its build percentage.
++ +
+ + +builderID
+ number
+
+
+
+ builderTeam
+ number
+
+
+
+ unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ part
+ number
+
+
+
+ + +
+ + +builderID
+ number
+
+
+
+ builderTeam
+ number
+
+
+
+ unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ part
+ number
+
+
+
+ + +
+ + +transporterID
+ number
+
+
+
+ transporterUnitDefID
+ number
+
+
+
+ transporterTeam
+ number
+
+
+
+ transporteeID
+ number
+
+
+
+ transporteeUnitDefID
+ number
+
+
+
+ transporteeTeam
+ number
+
+
+
+ + +
+ + +transporterID
+ number
+
+
+
+ transporterUnitDefID
+ number
+
+
+
+ transporterTeam
+ number
+
+
+
+ transporteeID
+ number
+
+
+
+ transporteeUnitDefID
+ number
+
+
+
+ transporteeTeam
+ number
+
+
+
+ x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ + +
+ + +transporterID
+ number
+
+
+
+ transporterUnitDefID
+ number
+
+
+
+ transporterTeam
+ number
+
+
+
+ transporteeID
+ number
+
+
+
+ transporteeUnitDefID
+ number
+
+
+
+ transporteeTeam
+ number
+
+
+
+ x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ enemyID
+ number
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ objectID
+ number
+
+
+
+ (optional)
+ weaponNum
+ number
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ targetID
+ number
+
+
+
+ Called just before feature is created.
++ +
+ + +featureDefID
+ number
+
+
+
+ teamID
+ number
+
+
+
+ x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ Called just before a feature changes its build percentage.
++ + + Note that this is also called for resurrecting features, and for refilling features with resources before resurrection. + On reclaim the part values are negative, and on refill and ressurect they are positive. + Part is the percentage the feature be built or reclaimed per frame. + Eg. for a 30 workertime builder, that's a build power of 1 per frame. + For a 50 buildtime feature reclaimed by this builder, part will be 100/-50(/1) = -2%, or -0.02 numerically. + +
+ + +builderID
+ number
+
+
+
+ builderTeam
+ number
+
+
+
+ featureID
+ number
+
+
+
+ featureDefID
+ number
+
+
+
+ part
+ number
+
+
+
+ Called when a team sets the sharing level of a resource.
++ +
+ + +teamID
+ number
+
+
+
+ res
+ string
+
+
+
+ level
+ number
+
+
+
+ Called just before resources are transferred between players.
++ +
+ + +oldTeamID
+ number
+
+
+
+ newTeamID
+ number
+
+
+
+ res
+ string
+
+
+
+ amount
+ number
+
+
+
+ Determines if this unit can be controlled directly in FPS view.
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ playerID
+ number
+
+
+
+ Called when a construction unit wants to "use his nano beams".
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ action
+ number
+ one of following:
+
+-1 Build + CMD.REPAIR Repair + CMD.RECLAIM Reclaim + CMD.RESTORE Restore + CMD.RESURRECT Resurrect + CMD.CAPTURE Capture +
Whether a start position should be allowed
++ + + clamped{X,Y,Z} are the coordinates clamped into start-boxes, raw is where player tried to place their marker. + + The readyState can be any one of: + + 0 - player picked a position, + 1 - player clicked ready, + 2 - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or + 3 - the player failed to load. + The default 'failed to choose' start-position is the north-west point of their startbox, or (0,0,0) if they do not have a startbox. + + NB: The order of the parameters changed with the addition of teamID in 104.0. Previouly it was: clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ + +
+ + +playerID
+ number
+
+
+
+ teamID
+ number
+
+
+
+ readyState
+ number
+
+
+
+ clampedX
+ number
+
+
+
+ clampedY
+ number
+
+
+
+ clampedZ
+ number
+
+
+
+ rawX
+ number
+
+
+
+ rawY
+ number
+
+
+
+ rawZ
+ number
+
+
+
+ Enable both Spring.MoveCtrl.SetCollideStop and Spring.MoveCtrl.SetTrackGround to enable this call-in.
++ +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ data
+ number
+ was supposed to indicate the type of notification but currently never has a value other than 1 ("unit hit the ground").
+ Called when pre-building terrain levelling terraforms are completed (c.f.
++ levelGround) + +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ buildUnitID
+ number
+
+
+
+ buildUnitDefID
+ number
+
+
+
+ buildUnitTeam
+ number
+
+
+
+ Called before damage is applied to the unit, allows fine control over how much damage and impulse is applied.
++ + + Called after every damage modification (even `HitByWeaponId`) but before the damage is applied + + expects two numbers returned by lua code: + 1st is stored under *newDamage if newDamage != NULL + 2nd is stored under *impulseMult if impulseMult != NULL + +
+ + +unitID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ unitTeam
+ number
+
+
+
+ damage
+ number
+
+
+
+ paralyzer
+ bool
+
+
+
+ weaponDefID
+ number
+ Synced Only
+ (optional)
+ projectileID
+ number
+ Synced Only
+ (optional)
+ attackerID
+ number
+ Synced Only
+ (optional)
+ attackerDefID
+ number
+ Synced Only
+ (optional)
+ attackerTeam
+ number
+ Synced Only
+ (optional)
+ Called before damage is applied to the feature.
++ + + Allows fine control over how much damage and impulse is applied. + +
+ + +featureID
+ number
+
+
+
+ featureDefID
+ number
+
+
+
+ featureTeam
+ number
+
+
+
+ damage
+ number
+
+
+
+ weaponDefID
+ number
+
+
+
+ projectileID
+ number
+
+
+
+ attackerID
+ number
+
+
+
+ attackerDefID
+ number
+
+
+
+ attackerTeam
+ number
+
+
+
+ Called before any engine shield-vs-projectile logic executes.
++ + + If the weapon is a hitscan type (BeamLaser or LightningCanon) then proID is nil and beamEmitterWeaponNum and beamEmitterUnitID are populated instead. + +
+ + +projectileID
+ number
+
+
+
+ projectileOwnerID
+ number
+
+
+
+ shieldWeaponNum
+ number
+
+
+
+ shieldCarrierID
+ number
+
+
+
+ bounceProjectile
+ bool
+
+
+
+ beamEmitterWeaponNum
+ number
+
+
+
+ beamEmitterUnitID
+ number
+
+
+
+ startX
+ number
+
+
+
+ startY
+ number
+
+
+
+ startZ
+ number
+
+
+
+ hitX
+ number
+
+
+
+ hitY
+ number
+
+
+
+ hitZ
+ number
+
+
+
+ Determines if this weapon can automatically generate targets itself.
++ See also commandFire weaponDef tag. + +
+ + +attackerID
+ number
+
+
+
+ attackerWeaponNum
+ number
+
+
+
+ attackerWeaponDefID
+ number
+
+
+
+ Controls blocking of a specific target from being considered during a weapon's periodic auto-targeting sweep.
++ +
+ + +attackerID
+ number
+
+
+
+ targetID
+ number
+
+
+
+ attackerWeaponNum
+ number
+
+
+
+ attackerWeaponDefID
+ number
+
+
+
+ defPriority
+ number
+
+
+
+ Controls blocking of a specific intercept target from being considered during an interceptor weapon's periodic auto-targeting sweep.
++ + + Only called for weaponDefIDs registered via Script.SetWatchWeapon. + +
+ + +interceptorUnitID
+ number
+
+
+
+ interceptorWeaponID
+ number
+
+
+
+ targetProjectileID
+ number
+
+
+
+ LuaRulesLua Rules
++ +
LuaVAO+ +
++ +
+ +
+ + + +local myVAO = gl.GetVAO() +if myVAO == nil then Spring.Echo("Failed to get VAO") end
LuaVBO+ +
++ +
+ +
+ + +bufferType
+ number
+ one of [GL.ARRAY_BUFFER,
+ GL.ELEMENT_ARRAY_BUFFER, GL.UNIFORM_BUFFER, GL.SHADER_STORAGE_BUFFER].
+
+ Defaults to GL.ARRAY_BUFFER, which you should use for vertex data, and
+ GL.ELEMENT_ARRAY_BUFFER should be used for vertex indices.
+ (default GL.ARRAY_BUFFER)
+
freqUpdated
+ bool
+ whether should be updated frequently, when false
+ will be updated only once
+ (default true)
+ local myVBO = gl.GetVBO() +if myVBO == nil then Spring.Echo("Failed to get VBO") end
LuaZipLuaZip
++ +
MathExtramath extensions
++ +
Returns the length of hypotenuse of right angle triangle with sides x and y, equivalent to sqrt(x*x + y*y), but has better numerical stability and internally handles intermediate overflows/underflows, but is also slower.
++ +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ Returns the length of the diagonal of an n-dimensional box (or the length of an n-component vector).
++ Rather quick method that does not handle intermediate overflows/underflows nor is made for numerical stability. + +
+ + +x1
+ number
+
+
+
+ x2
+ number
+
+
+
+ (optional)
+ x3
+ number
+
+
+
+ (optional)
+ xn
+ number
+ and so on
+ (optional)
+ Returns x clamped to min and max boundaries.
++ ( number x, number min, number max ) +
+ + + +Returns 0 if x == 0, 1 if x > 0, -1 if x < 0
++ +
+ + +x
+ number
+
+
+
+ Returns linear interpolation between x and y with ratio a (x+(y-x)*a).
++ +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ a
+ number
+
+
+
+ Returns x rounded to n decimals, if n is omitted or <=0, rounds to nearest integer.
++ Note that Spring's Lua interpreter uses 32-bit floats for all numbers so max. precision is ~7 decimal digits. + +
+ + +x
+ number
+
+
+
+ decimals
+ number
+
+
+
+ Returns erf(x), the Gauss error function, between -1 and 1.
++ +
+ + +x
+ number
+
+
+
+ Applies the smoothstep function
++ + Clamps and rescales v to a value between [0; 1] based on the edges and then applies the smoothstep function. + For example math.smoothstep(10, 25, 15) is 0.259, because 15 is 0.333 of the way from 10 to 25, and smoothstep(0.333) is 0.259 +
+ + +edge0
+ number
+
+
+
+ edge1
+ number
+
+
+
+ v
+ number
+
+
+
+ MetalMapMetal Map Lua API
++ +
+ +
+ + +x
+ number
+ in worldspace/16.
+ z
+ number
+ in worldspace/16.
+ metalAmount
+ number
+ must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua).
+ MoveCtrlMoveCtrl
++ +
OpenGLLua OpenGL API
++ +
+ +
+ +
+ + +text
+ string
+
+
+
+ x
+ number
+
+
+
+ y
+ number
+
+
+
+ size
+ number
+
+
+
+ options
+ string
+
+concatenated string of option characters.
+ ++ +
+ +
+ + +r
+ number or {number,number,number,number}
+ red when number, rgba
+ quadruple or rgb triple otherwise
+ g
+ number
+
+
+
+ (optional)
+ b
+ number
+
+
+
+ (optional)
+ a
+ number
+
+
+
+ (optional)
+ PlatformPlatform constants
++ +
Platform specific information
++ +
+ + +gpu
+ string
+ full GPU device name
+ gpuVendor
+ string
+ one of "Nvidia", "Intel", "ATI", "Mesa", "Unknown"
+ glVersionShort
+ string
+ major.minor.buildNumber
+ glslVersionShort
+ string
+ major.minor
+ glVersion
+ string
+ full version
+ glVendor
+ string
+
+
+
+ glRenderer
+ string
+
+
+
+ glslVersion
+ string
+ full version
+ glewVersion
+ string
+
+
+
+ osName
+ string
+ full name of the OS
+ osFamily
+ string
+ one of "Windows", "Linux", "MacOSX", "FreeBSD", "Unknown"
+ numDisplays
+ number
+
+
+
+ gpuMemorySize
+ number
+ size of total GPU memory in MBs; only available for "Nvidia", (rest are 0)
+ sdlVersionCompiledMajor
+ number
+
+
+
+ sdlVersionCompiledMinor
+ number
+
+
+
+ sdlVersionCompiledPatch
+ number
+
+
+
+ sdlVersionLinkedMajor
+ number
+
+
+
+ sdlVersionLinkedMinor
+ number
+
+
+
+ sdlVersionLinkedPatch
+ number
+
+
+
+ glSupportNonPowerOfTwoTex
+ bool
+
+
+
+ glSupportTextureQueryLOD
+ bool
+
+
+
+ glSupport24bitDepthBuffer
+ bool
+
+
+
+ glSupportRestartPrimitive
+ bool
+
+
+
+ glSupportClipSpaceControl
+ bool
+
+
+
+ glSupportFragDepthLayout
+ bool
+
+
+
+ RBORBO
++ +
+ +
+ + +xsize
+ number
+
+
+
+ ysize
+ number
+
+
+
+ target
+ number
+ GL_RENDERBUFFER_EXT
+ format
+ number
+ GL_RGBA
+ samples
+ number
+ any number here will result in creation of multisampled RBO
+ (optional)
+ User Data RBO
++ +
+ + +target
+ number
+
+
+
+ format
+ number
+
+
+
+ xsize
+ number
+
+
+
+ ysize
+ number
+
+
+
+ valid
+ bool
+
+
+
+ samples
+ number
+ will return globalRendering->msaaLevel for multisampled RBO or 0 otherwise
+ ShadersShader creation and management
++ + +
These functions are ONLY available if the graphics adapter supports GLSL. + Please test in your scripts if one of them exists before you use them. In headless mode, the gl. callouts are nil.
+ +Returns the shader compilation error log.
++ This is empty if the shader linking failed, in that case, check your in/out blocks and ensure they match. + +
+ + + +Create a shader from shaderParams table:
++ ( table shaderParams ) +
+ + +shaderParams
+ table
+
+
+
+ shaderID
+ +({[ vertex = "glsl code" ,]
+ [ tcs = "glsl code" ,]
+ [ tes = "glsl code" ,]
+ [ geometry = "glsl code" ,]
+ [ fragment = "glsl code" ,]
+ [ uniform = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays)
+ [ uniformInt = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays)
+ [ uniformFloat = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays)
+ [ uniformMatrix = { uniformName = number value, ...} ,]
+ [ geoInputType = number inType,]
+ [ geoOutputType = number outType,]
+ [ geoOutputVerts = number maxVerts,]
+ [ definitions = "string of shader #defines", ]
+})
+uniform float frame;The engine will automatically fill in an appropriately named uniform for team colour if it is declared;
+ +uniform vec4 teamColor;
+Deletes a shader identified by shaderID
++ +
+ + +shaderID
+ number
+
+
+
+ Binds a shader program identified by shaderID.
++ Pass 0 to disable the shader. Returns wether the shader was successfully bound. + +
+ + +shaderID
+ number
+
+
+
+ Binds a shader program identified by shaderID, and calls the Lua func with the specified arguments.
++ + + Can be used in NON-drawing events (to update uniforms etc.)! + +
+ + +shaderID
+ number
+
+
+
+ func
+ func
+
+
+
+ arg1
+ any
+
+
+
+ (optional)
+ arg2
+ any
+
+
+
+ (optional)
+ argn
+ any
+
+
+
+ (optional)
+ Query the active (actually used) uniforms of a shader and identify their names, types (float, int, uint) and sizes (float, vec4, ...).
++ +
+ + +shaderID
+ number
+
+
+
+ ActiveUniforms = { { name = "name", type = "type", length = number length, size = number size }, ...}Returns the locationID of a shaders uniform.
++ Needed for changing uniform values with @function gl.Uniform. + +
+ + +shaderID
+ number
+
+
+
+ name
+ string
+
+
+
+ Sets the uniform float value at the locationID for the currently active shader.
++ Shader must be activated before setting uniforms. + +
+ + +locationID
+ number
+
+
+
+ f1
+ number
+
+
+
+ f2
+ number
+
+
+
+ (optional)
+ f3
+ number
+
+
+
+ (optional)
+ f4
+ number
+
+
+
+ (optional)
+ Sets the uniform int value at the locationID for the currently active shader.
++ Shader must be activated before setting uniforms. + +
+ + +locationID
+ number
+
+
+
+ int1
+ number
+
+
+
+ int2
+ number
+
+
+
+ (optional)
+ int3
+ number
+
+
+
+ (optional)
+ int4
+ number
+
+
+
+ (optional)
+ Sets the an array of uniform values at the locationID for the currently active shader.
++ Shader must be activated before setting uniforms. Type can be one of {1 = int, 2 = float, 3 = float matrix}. In 104.0 the maximum length of the uniforms table increased from 32 entries to 1024. + +
+ + +locationID
+ number
+
+
+
+ type
+ number
+
+
+
+ uniforms
+ table
+
+
+
+ Sets the a uniform mat4 locationID for the currently active shader.
++ Shader must be activated before setting uniforms. Can set one one common matrix like shadow, or by passing 16 additional numbers for the matrix. + +
+ + +locationID
+ number
+
+
+
+ m1
+ string or number
+ "shadows" | "camera" | "caminv" | "camprj"
+ m2
+ number
+
+
+
+ (optional)
+ mn
+ number
+
+
+
+ (optional)
+ m16
+ number
+
+
+
+ (optional)
+ Sets the Geometry shader parameters for shaderID.
++ Needed by geometry shader programs (check the opengl GL_ARB_geometry_shader4 extension for glProgramParameteri) + +
+ + +shaderID
+ number
+
+
+
+ param
+ number
+
+
+
+ number
+ number
+
+
+
+ Sets the tesselation shader parameters for shaderID.
++ + + Needed by tesselation shader programs (check the opengl GL_ARB_tessellation_shader extension for glProgramParameteri) + +
+ + +param
+ number
+
+
+
+ number
+ number
+
+
+
+ SyncedCtrlSynced Lua API
++ +
+Please note the explosion defaults to 1 damage regardless of what it's defined in the weaponDef. +
Callins.UnitExperience will be called.
+ + +
Changes the value of the (one-sided) alliance between: firstAllyTeamID -> secondAllyTeamID.
++ +
+ + +firstAllyTeamID
+ number
+
+
+
+ secondAllyTeamID
+ number
+
+
+
+ ally
+ bool
+
+
+
+ Changes the start box position of an allyTeam.
++ +
+ + +allyTeamID
+ number
+
+
+
+ xMin
+ number
+ left start box boundary (elmos)
+ zMin
+ number
+ top start box boundary (elmos)
+ xMax
+ number
+ right start box boundary (elmos)
+ zMax
+ number
+ bottom start box boundary (elmos)
+ Assigns a player to a team.
++ +
+ + +playerID
+ number
+
+
+
+ teamID
+ number
+
+
+
+ Changes access to global line of sight for a team and its allies.
++ +
+ + +allyTeamID
+ number
+
+
+
+ globallos
+ bool
+
+
+
+ Will declare a team to be dead (no further orders can be assigned to such teams units).
++ + + Gaia team cannot be killed. + +
+ + +teamID
+ number
+
+
+
+ Will declare game over.
++ + + A list of winning allyteams can be passed, if undecided (like when dropped from the host) it should be empty (no winner), in the case of a draw with multiple winners, all should be listed. + +
+ + +allyTeamID1
+ number
+
+
+
+ (optional)
+ allyTeamID2
+ number
+
+
+
+ (optional)
+ allyTeamIDn
+ number
+
+
+
+ (optional)
+ Set tidal strength
++ +
+ + +strength
+ number
+
+
+
+ Set wind strength
++ +
+ + +minStrength
+ number
+
+
+
+ maxStrength
+ number
+
+
+
+ Adds metal or energy resources to the specified team.
++ +
+ + +teamID
+ number
+
+
+
+ type
+ string
+ "metal" | "energy"
+ amount
+ number
+
+
+
+ Consumes metal and/or energy resources of the specified team.
++ +
+ + +teamID
+ number
+
+
+
+ type
+ string
+ "metal" | "energy"
+ amount
+ number or table
+ { metal = number amount, energy = number amount }
+ + +
+ + +teamID
+ number
+
+
+
+ res
+ string
+ "m" = metal "e" = energy "ms" = metal storage "es" = energy storage
+ amount
+ number
+
+
+
+ Changes the resource amount for a team beyond which resources aren't stored but transferred to other allied teams if possible.
++ +
+ + +teamID
+ number
+
+
+
+ type
+ string
+ "metal" | "energy"
+ amount
+ number
+
+
+
+ Transfers resources between two teams.
++ +
+ + +teamID_src
+ number
+
+
+
+ teamID_recv
+ number
+
+
+
+ type
+ string
+ "metal" | "energy"
+ amount
+ number
+
+
+
+ + +
Parameters for los access
++ + If one condition is fulfilled all beneath it are too (e.g. if an unit is in LOS it can read params with `inradar=true` even if the param has `inlos=false`) + All GameRulesParam are public, TeamRulesParams can just be `private`,`allied` and/or `public` + You can read RulesParams from any Lua enviroments! With those losAccess policies you can limit their access. + +
+ + +private
+ bool
+ only readable by the ally (default)
+ (optional)
+ allied
+ bool
+ readable by ally + ingame allied
+ (optional)
+ inlos
+ bool
+ readable if the unit is in LOS
+ (optional)
+ inradar
+ bool
+ readable if the unit is in AirLOS
+ (optional)
+ public
+ bool
+ readable by all
+ (optional)
+ + +
+ + +paramName
+ string
+
+
+
+ paramValue
+ number or string
+ numeric paramValues in quotes will be converted to number.
+ losAccess
+ losAccess
+
+
+
+ (optional)
+ + +
+ + +teamID
+ number
+
+
+
+ paramName
+ string
+
+
+
+ paramValue
+ number or string
+ numeric paramValues in quotes will be converted to number.
+ losAccess
+ losAccess
+
+
+
+ (optional)
+ + +
+ + +playerID
+ number
+
+
+
+ paramName
+ string
+
+
+
+ paramValue
+ number or string
+ numeric paramValues in quotes will be converted to number.
+ losAccess
+ losAccess
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ paramName
+ string
+
+
+
+ paramValue
+ number or string
+ numeric paramValues in quotes will be converted to number.
+ losAccess
+ losAccess
+
+
+
+ (optional)
+ + +
+ + +featureID
+ number
+
+
+
+ paramName
+ string
+
+
+
+ paramValue
+ number or string
+ numeric paramValues in quotes will be converted to number.
+ losAccess
+ losAccess
+
+
+
+ (optional)
+ + +
+ +
+ + +unitID
+ number
+
+
+
+ funcName
+ number or string
+
+
+
+ retArgs
+ number
+
+
+
+ COBArg1
+
+
+
+ (optional)
+ COBArg2
+
+
+
+ (optional)
+ COBArgn
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ funcName
+ string
+
+
+
+ + +
+ + + Offmap positions are clamped! Use MoveCtrl to move to such positions. + +
+ + +unitDefName
+ string or number
+ or unitDefID
+ x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ facing
+ string or number
+ possible values for facing are: "south" | "s" | 0, "east" | "e" | 1, "north" | "n" | 2, "west" | "w" | 3
+ teamID
+ number
+
+
+
+ build
+ bool
+ the unit is created in "being built" state with buildProgress = 0
+ (default false)
+ flattenGround
+ bool
+ the unit flattens ground, if it normally does so
+ (default true)
+ unitID
+ number
+ requests specific unitID
+ (optional)
+ builderID
+ number
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ selfd
+ bool
+ makes the unit act like it self-destructed.
+ (default false)
+ reclaimed
+ bool
+ don't show any DeathSequences, don't leave a wreckage. This does not give back the resources to the team!
+ (default false)
+ attackerID
+ number
+
+
+
+ (optional)
+ cleanupImmediately
+ bool
+ stronger version of reclaimed, removes the unit unconditionally and makes its ID available for immediate reuse (otherwise it takes a few frames)
+ (default false)
+ + +
+ + +unitID
+ number
+
+
+
+ newTeamID
+ number
+
+
+
+ given
+ bool
+ if false, the unit is captured.
+ (default true)
+ + +
+ +
+ + +unitID
+ number
+
+
+
+ where
+ {[number]=number,...}
+ keys and values are, respectively and in this order: buildTime=amount, metalCost=amount, energyCost=amount
+ + +
+ + +unitID
+ number
+
+
+
+ res
+ string
+
+
+
+ amount
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ res
+ {[string]=number,...}
+ keys are: "[u|c][u|m][m|e]" unconditional | conditional, use | make, metal | energy. Values are amounts
+ + +
+ + +unitID
+ number
+
+
+
+ tooltip
+ string
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ health
+ number or {[string]=number,...}
+ where keys can be one of health|capture|paralyze|build and values are amounts
+ + +
+ + +unitID
+ number
+
+
+
+ maxHealth
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ stockpile
+ number
+
+
+
+ (optional)
+ buildPercent
+ number
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ forceUseWeapons
+ number
+
+
+
+ (optional)
+ allowUseWeapons
+ number
+
+
+
+ (optional)
+ Parameter for weapon states
++ +
+ + +reloadState
+ number
+
+
+
+ reloadFrame
+ number
+ synonym for reloadState!
+ reloadTime
+ number
+
+
+
+ accuracy
+ number
+
+
+
+ sprayAngle
+ number
+
+
+
+ range
+ number
+ if you change the range of a weapon with dynamic damage make sure you use SetUnitWeaponDamages to change dynDamageRange as well.
+ projectileSpeed
+ number
+
+
+
+ burst
+ number
+
+
+
+ burstRate
+ number
+
+
+
+ projectiles
+ number
+
+
+
+ salvoLeft
+ number
+
+
+
+ nextSalvo
+ number
+
+
+
+ aimReady
+ number
+ (<>0.0f := true)
+ + +
+ + +unitID
+ number
+
+
+
+ weaponNum
+ number
+
+
+
+ states
+ states
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ weaponNum
+ number
+
+
+
+ key
+ string
+
+
+
+ value
+ number
+
+
+
+ Parameters for damage
++ +
+ + +paralyzeDamageTime
+ number
+
+
+
+ impulseFactor
+ number
+
+
+
+ impulseBoost
+ number
+
+
+
+ craterMult
+ number
+
+
+
+ craterBoost
+ number
+
+
+
+ dynDamageExp
+ number
+
+
+
+ dynDamageMin
+ number
+
+
+
+ dynDamageRange
+ number
+
+
+
+ dynDamageInverted
+ number
+ (<>0.0f := true)
+ craterAreaOfEffect
+ number
+
+
+
+ damageAreaOfEffect
+ number
+
+
+
+ edgeEffectiveness
+ number
+
+
+
+ explosionSpeed
+ number
+
+
+
+ armorType
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ weaponNum
+ number or string
+ "selfDestruct" | "explode"
+ damages
+ damages
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ weaponNum
+ number or string
+ "selfDestruct" | "explode"
+ key
+ string
+
+
+
+ value
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ maxRange
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ experience
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ deltaExperience
+ number
+ Can be negative to subtract, but the unit will never have negative total afterwards
+ + +
+ + +unitID
+ number
+
+
+
+ armored
+ bool
+
+
+
+ (optional)
+ armorMultiple
+ number
+
+
+
+ (optional)
+ + +
+ + + The 3rd argument is either the bit-and combination of the following numbers: + + LOS_INLOS = 1 + LOS_INRADAR = 2 + LOS_PREVLOS = 4 + LOS_CONTRADAR = 8 + + or a table of the following form: + + losTypes = { + [los = boolean,] + [radar = boolean,] + [prevLos = boolean,] + [contRadar = boolean] + } + +
+ + +unitID
+ number
+
+
+
+ allyTeam
+ number
+
+
+
+ losTypes
+ number or table
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ allyTeam
+ number
+
+
+
+ los
+ number or table
+
+
+
+ + + + If the 2nd argument is a number, the value works like this: + 1:=normal cloak + 2:=for free cloak (cost no E) + 3:=for free + no decloaking (except the unit is stunned) + 4:=ultimative cloak (no ecost, no decloaking, no stunned decloak) + + The decloak distance is only changed: + - if the 3th argument is a number or a boolean. + - if the boolean is false it takes the default decloak distance for that unitdef, + - if the boolean is true it takes the absolute value of it. + +
+ + +unitID
+ number
+
+
+
+ cloak
+ bool or number
+
+
+
+ cloakArg
+ bool or number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ stealth
+ bool
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ sonarStealth
+ bool
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ seismicSignature
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ alwaysVisible
+ bool
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ useAirLos
+ bool
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ depth
+ number
+ corresponds to metal extraction rate
+ range
+ number
+ similar to "extractsMetal" in unitDefs.
+ (optional)
+ See also harvestStorage UnitDef tag.
++ +
+ + +unitID
+ number
+
+
+
+ metal
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ paramName
+ string
+ one of buildRange|buildDistance|buildRange3D
+ bool
+ number
+ value bool when paramName is buildRange3D, number otherwise
+ + +
+ + +builderID
+ number
+
+
+
+ buildSpeed
+ number
+
+
+
+ repairSpeed
+ number
+
+
+
+ (optional)
+ reclaimSpeed
+ number
+
+
+
+ (optional)
+ captureSpeed
+ number
+
+
+
+ (optional)
+ terraformSpeed
+ number
+
+
+
+ (optional)
+ + + + This saves a lot of engine calls, by replacing: function script.QueryNanoPiece() return currentpiece end + Use it! + +
+ + +builderID
+ number
+
+
+
+ pieces
+ table
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ isblocking
+ bool
+
+
+
+ isSolidObjectCollidable
+ bool
+
+
+
+ isProjectileCollidable
+ bool
+
+
+
+ isRaySegmentCollidable
+ bool
+
+
+
+ crushable
+ bool
+
+
+
+ blockEnemyPushing
+ bool
+
+
+
+ blockHeightChanges
+ bool
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ crashing
+ bool
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ weaponID
+ number
+
+
+
+ (default -1)
+ enabled
+ bool
+
+
+
+ (optional)
+ power
+ number
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ weaponID
+ number
+ (optional if the unit only has one shield)
+ (optional)
+ rechargeTime
+ number
+ (in seconds; emulates a regular hit if nil)
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ type
+ string
+ "dir"|"minDamage"|"maxDamage"|"moveFactor"|"mode"
+ arg1
+ number
+ x|minDamage|maxDamage|moveFactor|mode
+ y
+ number
+ only when type is "dir"
+ (optional)
+ z
+ number
+ only when type is "dir"
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ neutral
+ bool
+
+
+
+ Defines a unit's target.
++ +
+ + +unitID
+ number
+
+
+
+ enemyUnitID
+ number
+ when nil drops the units current target.
+ (optional)
+ dgun
+ bool
+
+
+
+ (default false)
+ userTarget
+ bool
+
+
+
+ (default false)
+ weaponNum
+ number
+
+
+
+ (default -1)
+ + +
+ + +unitID
+ number
+
+
+
+ x
+ number
+ when nil or not passed it will drop target and ignore other parameters
+ (optional)
+ y
+ number
+
+
+
+ (optional)
+ z
+ number
+
+
+
+ (optional)
+ dgun
+ bool
+
+
+
+ (default false)
+ userTarget
+ bool
+
+
+
+ (default false)
+ weaponNum
+ number
+
+
+
+ (default -1)
+ + +
+ + +unitID
+ number
+
+
+
+ mpX
+ number
+ new middle positionX of unit
+ mpY
+ number
+ new middle positionY of unit
+ mpZ
+ number
+ new middle positionZ of unit
+ apX
+ number
+ new positionX that enemies aim at on this unit
+ apY
+ number
+ new positionY that enemies aim at on this unit
+ apZ
+ number
+ new positionZ that enemies aim at on this unit
+ relative
+ bool
+ are the new coordinates relative to world (false) or unit (true) coordinates? Also, note that apy is inverted!
+ (default false)
+ + +
+ + +unitID
+ number
+
+
+
+ radius
+ number
+
+
+
+ height
+ number
+
+
+
+ Changes the pieces hierarchy of a unit by attaching a piece to a new parent.
++ +
+ + +unitID
+ number
+
+
+
+ AlteredPiece
+ number
+
+
+
+ ParentPiece
+ number
+
+
+
+ Sets the local (i.e.
++ parent-relative) matrix of the given piece. + + + If any of the first three elements are non-zero, and also blocks all script animations from modifying it until {0, 0, 0} is passed. + +
+ + +unitID
+ number
+
+
+
+ pieceNum
+ number
+
+
+
+ matrix
+ {number,...}
+ an array of 16 floats
+ + +
+ + +unitID
+ number
+
+
+
+ scaleX
+ number
+
+
+
+ scaleY
+ number
+
+
+
+ scaleZ
+ number
+
+
+
+ offsetX
+ number
+
+
+
+ offsetY
+ number
+
+
+
+ offsetZ
+ number
+
+
+
+ vType
+ number
+
+
+
+ tType
+ number
+
+
+
+ Axis
+ number
+
+
+
+ enum COLVOL_TYPES {
+ COLVOL_TYPE_DISABLED = -1,
+ COLVOL_TYPE_ELLIPSOID = 0,
+ COLVOL_TYPE_CYLINDER,
+ COLVOL_TYPE_BOX,
+ COLVOL_TYPE_SPHERE,
+ COLVOL_NUM_TYPES // number of non-disabled collision volume types
+};
+enum COLVOL_TESTS {
+ COLVOL_TEST_DISC = 0,
+ COLVOL_TEST_CONT = 1,
+ COLVOL_NUM_TESTS = 2 // number of tests
+};
+enum COLVOL_AXES {
+ COLVOL_AXIS_X = 0,
+ COLVOL_AXIS_Y = 1,
+ COLVOL_AXIS_Z = 2,
+ COLVOL_NUM_AXES = 3 // number of collision volume axes
+};
++ +
+ + +unitID
+ number
+
+
+
+ pieceIndex
+ number
+
+
+
+ enable
+ bool
+
+
+
+ scaleX
+ number
+
+
+
+ scaleY
+ number
+
+
+
+ scaleZ
+ number
+
+
+
+ offsetX
+ number
+
+
+
+ offsetY
+ number
+
+
+
+ offsetZ
+ number
+
+
+
+ volumeType
+ number
+
+
+
+ (optional)
+ primaryAxis
+ number
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ pieceIndex
+ number
+
+
+
+ visible
+ bool
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ type
+ string
+ "los" | "airLos" | "radar" | "sonar" | "seismic" | "radarJammer" | "sonarJammer"
+ + +
+ + +unitID
+ number
+
+
+
+ posErrorVectorX
+ number
+
+
+
+ posErrorVectorY
+ number
+
+
+
+ posErrorVectorZ
+ number
+
+
+
+ posErrorDeltaX
+ number
+
+
+
+ posErrorDeltaY
+ number
+
+
+
+ posErrorDeltaZ
+ number
+
+
+
+ nextPosErrorUpdate
+ number
+
+
+
+ (optional)
+ Used by default commands to get in build-, attackrange etc.
++ +
+ + +unitID
+ number
+
+
+
+ goalX
+ number
+
+
+
+ goalY
+ number
+
+
+
+ goalZ
+ number
+
+
+
+ goalRadius
+ number
+
+
+
+ (optional)
+ moveSpeed
+ number
+
+
+
+ (optional)
+ moveRaw
+ bool
+
+
+
+ (optional)
+ Used in conjunction with Spring.UnitAttach et al.
++ to re-implement old airbase & fuel system in Lua. + +
+ + +unitID
+ number
+
+
+
+ goalX
+ number
+
+
+
+ goalY
+ number
+
+
+
+ goalZ
+ number
+
+
+
+ goalRadius
+ number
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ posX
+ number
+
+
+
+ posY
+ number
+
+
+
+ posZ
+ number
+
+
+
+ velX
+ number
+
+
+
+ velY
+ number
+
+
+
+ velZ
+ number
+
+
+
+ rotX
+ number
+
+
+
+ rotY
+ number
+
+
+
+ rotZ
+ number
+
+
+
+ dragX
+ number
+
+
+
+ dragY
+ number
+
+
+
+ dragZ
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ mass
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ x
+ number
+
+
+
+ z
+ number
+
+
+
+ alwaysAboveSea
+ bool
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ yaw
+ number
+
+
+
+ pitch
+ number
+
+
+
+ roll
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ + + Use this call to set up unit direction in a robust way. Heading (-32768 to 32767) represents a 2D (xz plane) unit orientation if unit was completely upright, new {upx,upy,upz} direction will be used as new "up" vector, the rotation set by "heading" will remain preserved. +
+ + +unitID
+ number
+
+
+
+ heading
+ number
+
+
+
+ upx
+ number
+
+
+
+ upy
+ number
+
+
+
+ upz
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ velX
+ number
+
+
+
+ velY
+ number
+
+
+
+ velZ
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ buggerOff
+ bool
+
+
+
+ (optional)
+ offset
+ number
+
+
+
+ (optional)
+ radius
+ number
+
+
+
+ (optional)
+ relHeading
+ number
+
+
+
+ (optional)
+ spherical
+ bool
+
+
+
+ (optional)
+ forced
+ bool
+
+
+
+ (optional)
+ + +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+ uses ground height when unspecified
+ (optional)
+ radius
+ number
+
+
+
+ teamID
+ number
+
+
+
+ spherical
+ bool
+
+
+
+ (default true)
+ forced
+ bool
+
+
+
+ (default true)
+ excludeUnitID
+ number
+
+
+
+ (optional)
+ excludeUnitDefIDs
+ {[number],...}
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ damage
+ number
+
+
+
+ paralyze
+ number
+ equals to the paralyzetime in the WeaponDef.
+ (default 0)
+ attackerID
+ number
+
+
+
+ (default -1)
+ weaponID
+ number
+
+
+
+ (default -1)
+ impulseX
+ number
+
+
+
+ (optional)
+ impulseY
+ number
+
+
+
+ (optional)
+ impulseZ
+ number
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ decayRate
+ number
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ pindSize
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ resource
+ string
+ "m" | "e"
+ amount
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ resource
+ string
+ "m" | "e"
+ amount
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ resources
+ {[string]=number,...}
+ where keys are one of "m"|"metal"|"e"|"energy" and values are amounts
+ + +
+ +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ + +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ + +
+ +
+ + +featureDef
+ string or number
+ name or id
+ x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ heading
+ number
+
+
+
+ (optional)
+ AllyTeamID
+ number
+
+
+
+ (optional)
+ featureID
+ number
+
+
+
+ (optional)
+ + +
+ + +featureDefID
+ number
+
+
+
+ Feature Control
++ +
+ + +featureDefID
+ number
+
+
+
+ teamID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ enable
+ bool
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ useAirLos
+ bool
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ health
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ maxHealth
+ number
+ minimum 0.1
+ + +
+ + +featureID
+ number
+
+
+
+ reclaimLeft
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ metal
+ number
+
+
+
+ energy
+ number
+
+
+
+ reclaimTime
+ number
+
+
+
+ (optional)
+ reclaimLeft
+ number
+
+
+
+ (optional)
+ featureDefMetal
+ number
+
+
+
+ (optional)
+ featureDefEnergy
+ number
+
+
+
+ (optional)
+ + + + Second param can now be a number id instead of a string name, this also allows cancelling ressurection by passing -1. + The level of progress can now be set via the additional 4th param. + Possible values for facing are: + "south" | "s" | 0 + "east" | "e" | 1 + "north" | "n" | 2 + "west" | "w" | 3 + +
+ + +featureID
+ number
+
+
+
+ unitDef
+ string or number
+ id or name
+ facing
+ string or number
+
+
+
+ (optional)
+ progress
+ number
+
+
+
+ (optional)
+ + + + Use this callout to control feature movement. The arg* arguments are parsed as follows and all optional: + + If enable is true: + [, velVector(x,y,z) * initial velocity for feature + [, accVector(x,y,z) * acceleration added every frame]] + + If enable is false: + [, velocityMask(x,y,z) * dimensions in which velocity is allowed to build when not using MoveCtrl + [, impulseMask(x,y,z) * dimensions in which impulse is allowed to apply when not using MoveCtrl + [, movementMask(x,y,z) * dimensions in which feature is allowed to move when not using MoveCtrl]]] + + It is necessary to unlock feature movement on x,z axis before changing feature physics. + + For example use `Spring.SetFeatureMoveCtrl(featureID,false,1,1,1,1,1,1,1,1,1)` to unlock all movement prior to making `Spring.SetFeatureVelocity` calls. + +
+ + +featureID
+ number
+
+
+
+ enable
+ bool
+
+
+
+ (optional)
+ arg1
+ number
+
+
+
+ (optional)
+ arg2
+ number
+
+
+
+ (optional)
+ argn
+ number
+
+
+
+ (optional)
+ + +
+ + +featureID
+ number
+
+
+
+ posX
+ number
+
+
+
+ posY
+ number
+
+
+
+ posZ
+ number
+
+
+
+ velX
+ number
+
+
+
+ velY
+ number
+
+
+
+ velZ
+ number
+
+
+
+ rotX
+ number
+
+
+
+ rotY
+ number
+
+
+
+ rotZ
+ number
+
+
+
+ dragX
+ number
+
+
+
+ dragY
+ number
+
+
+
+ dragZ
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ mass
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ snapToGround
+ bool
+
+
+
+ (optional)
+ + +
+ + +featureID
+ number
+
+
+
+ rotX
+ number
+
+
+
+ rotY
+ number
+
+
+
+ rotZ
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ dirX
+ number
+
+
+
+ dirY
+ number
+
+
+
+ dirZ
+ number
+
+
+
+ + + Use this call to set up feature direction in a robust way. Heading (-32768 to 32767) represents a 2D (xz plane) feature orientation if feature was completely upright, new {upx,upy,upz} direction will be used as new "up" vector, the rotation set by "heading" will remain preserved. +
+ + +featureID
+ number
+
+
+
+ heading
+ number
+
+
+
+ upx
+ number
+
+
+
+ upy
+ number
+
+
+
+ upz
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ velX
+ number
+
+
+
+ velY
+ number
+
+
+
+ velZ
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ isBlocking
+ bool
+
+
+
+ isSolidObjectCollidable
+ bool
+
+
+
+ isProjectileCollidable
+ bool
+
+
+
+ isRaySegmentCollidable
+ bool
+
+
+
+ crushable
+ bool
+
+
+
+ blockEnemyPushing
+ bool
+
+
+
+ blockHeightChanges
+ bool
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ noSelect
+ bool
+
+
+
+ + + + Check `Spring.SetUnitMidAndAimPos` for further explanation of the arguments. + +
+ + +featureID
+ number
+
+
+
+ mpX
+ number
+
+
+
+ mpY
+ number
+
+
+
+ mpZ
+ number
+
+
+
+ apX
+ number
+
+
+
+ apY
+ number
+
+
+
+ apZ
+ number
+
+
+
+ relative
+ bool
+
+
+
+ (optional)
+ + +
+ + +featureID
+ number
+
+
+
+ radius
+ number
+
+
+
+ height
+ number
+
+
+
+ + + + Check `Spring.SetUnitCollisionVolumeData` for further explanation of the arguments. + +
+ + +featureID
+ number
+
+
+
+ scaleX
+ number
+
+
+
+ scaleY
+ number
+
+
+
+ scaleZ
+ number
+
+
+
+ offsetX
+ number
+
+
+
+ offsetY
+ number
+
+
+
+ offsetZ
+ number
+
+
+
+ vType
+ number
+
+
+
+ tType
+ number
+
+
+
+ Axis
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ pieceIndex
+ number
+
+
+
+ enable
+ bool
+
+
+
+ scaleX
+ number
+
+
+
+ scaleY
+ number
+
+
+
+ scaleZ
+ number
+
+
+
+ offsetX
+ number
+
+
+
+ offsetY
+ number
+
+
+
+ offsetZ
+ number
+
+
+
+ Axis
+ number
+
+
+
+ volumeType
+ number
+
+
+
+ primaryAxis
+ number
+
+
+
+ (optional)
+ + +
+ + +featureID
+ number
+
+
+
+ pieceIndex
+ number
+
+
+
+ visible
+ bool
+
+
+
+ + +
+ +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ owner
+ number
+
+
+
+ team
+ number
+
+
+
+ ttl
+ number
+
+
+
+ gravity
+ number
+
+
+
+ tracking
+ number
+
+
+
+ maxRange
+ number
+
+
+
+ startAlpha
+ number
+
+
+
+ endAlpha
+ number
+
+
+
+ model
+ string
+
+
+
+ cegTag
+ string
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ alwaysVisible
+ bool
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ useAirLos
+ bool
+
+
+
+ Disables engine movecontrol, so lua can fully control the physics.
++ +
+ + +projectileID
+ number
+
+
+
+ enable
+ bool
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ posX
+ number
+
+
+
+ (default 0)
+ posY
+ number
+
+
+
+ (default 0)
+ posZ
+ number
+
+
+
+ (default 0)
+ + +
+ + +projectileID
+ number
+
+
+
+ velX
+ number
+
+
+
+ (default 0)
+ velY
+ number
+
+
+
+ (default 0)
+ velZ
+ number
+
+
+
+ (default 0)
+ + +
+ + +projectileID
+ number
+
+
+
+ + + + targetTypeStr can be one of: + 'u' - unit + 'f' - feature + 'p' - projectile + while targetTypeInt is one of: + string.byte('g') := GROUND + string.byte('u') := UNIT + string.byte('f') := FEATURE + string.byte('p') := PROJECTILE + +
+ + +projectileID
+ number
+
+
+
+ arg1
+ number
+ targetID or posX
+ (default 0)
+ arg2
+ number
+ targetType or posY
+ (default 0)
+ posZ
+ number
+
+
+
+ (default 0)
+ + +
+ + +projectileID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ weaponNum
+ number
+
+
+
+ key
+ string
+
+
+
+ value
+ number
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ ignore
+ bool
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ grav
+ number
+
+
+
+ (default 0)
+ + +
+ + +projectileID
+ number
+
+
+
+ explosionFlags
+ number
+
+
+
+ (optional)
+ spinAngle
+ number
+
+
+
+ (optional)
+ spinSpeed
+ number
+
+
+
+ (optional)
+ spinVectorX
+ number
+
+
+
+ (optional)
+ spinVectorY
+ number
+
+
+
+ (optional)
+ spinVectorZ
+ number
+
+
+
+ (optional)
+ Options can also be a bitmask; e.g. 0 instead of an empty table (can avoid performance hit on table creation)
+ See Constants.CMD for relevant constants.
Command Options params
++ +
+ + +right
+ bool
+ Right mouse key pressed
+ alt
+ bool
+ Alt key pressed
+ ctrl
+ bool
+ Ctrl key pressed
+ shift
+ bool
+ Shift key pressed
+ Command spec
++ + + Used when assigning multiple commands at once + +
+ + +cmdID
+ number
+
+
+
+ params
+ {number,...}
+
+
+
+ options
+ cmdOpts
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ cmdID
+ number
+
+
+
+ params
+ {number,...}
+
+
+
+ cmdOpts
+ cmdOpts
+
+
+
+ + +
+ + +unitMap
+ {[number]=table,...}
+ table with unitIDs as keys
+ cmdID
+ number
+
+
+
+ params
+ {number,...}
+
+
+
+ cmdOpts
+ cmdOpts
+
+
+
+ + +
+ + +unitIDs
+ {number,...}
+
+
+
+ cmdID
+ number
+
+
+
+ params
+ {number,...}
+
+
+
+ cmdOpts
+ cmdOpts
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ cmdArray
+ {cmdSpec,...}
+
+
+
+ + +
+ + +unitMap
+ {[number]=table}
+ table with unitIDs as keys
+ orderArray
+ {cmdSpec,...}
+
+
+
+ + +
+ + +unitArray
+ {number,...}
+ containing unitIDs
+ orderArray
+ {cmdSpec,...}
+
+
+
+ + +
Note that x & z coords are in worldspace (Game.mapSizeX/Z), still the heightmap resolution is Game.squareSize.
+Set a certain height to a point or rectangle area on the world
++ +
+ + +x1
+ number
+
+
+
+ z1
+ number
+
+
+
+ x2_height
+ number
+ if y2 and height are nil then this parameter is the height
+ z2
+ number
+
+
+
+ (optional)
+ height
+ number
+
+
+
+ (optional)
+ Add a certain height to a point or rectangle area on the world
++ +
+ + +x1
+ number
+
+
+
+ y1
+ number
+
+
+
+ x2_height
+ number
+ if y2 and height are nil then this parameter is the height
+ y2
+ number
+
+
+
+ (optional)
+ height
+ number
+
+
+
+ (optional)
+ Restore original map height to a point or rectangle area on the world
++ +
+ + +x1
+ number
+
+
+
+ y1
+ number
+
+
+
+ x2_factor
+ number
+ if y2 and factor are nil then this parameter is the factor
+ y2
+ number
+
+
+
+ (optional)
+ factor
+ number
+
+
+
+ (optional)
+ Can only be called in `Spring.SetHeightMapFunc`
++ +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ height
+ number
+
+
+
+ + + + Can only be called in `Spring.SetHeightMapFunc`. The terraform argument is + +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ height
+ number
+
+
+
+ terraform
+ number
+ a scaling factor.
+ (default 1)
+ + + + Example code: + + function Spring.SetHeightMapFunc(function() + for z=0,Game.mapSizeZ, Game.squareSize do + for x=0,Game.mapSizeX, Game.squareSize do + Spring.SetHeightMap( x, z, 200 + 20 * math.cos((x + z) / 90) ) + end + end + end) + +
+ + +lua_function
+ func
+
+
+
+ arg1
+
+
+
+ (optional)
+ arg2
+
+
+
+ (optional)
+ argn
+
+
+
+ (optional)
+ + +
Set a height to a point or rectangle area to the original map height cache
++ +
+ + +x1
+ number
+
+
+
+ y1
+ number
+
+
+
+ x2_height
+ number
+ if y2 and height are nil then this parameter is the height
+ y2
+ number
+
+
+
+ (optional)
+ height
+ number
+
+
+
+ (optional)
+ Add height to a point or rectangle area to the original map height cache
++ +
+ + +x1
+ number
+
+
+
+ y1
+ number
+
+
+
+ x2_height
+ number
+ if y2 and height are nil then this parameter is the height
+ y2
+ number
+
+
+
+ (optional)
+ height
+ number
+
+
+
+ (optional)
+ Restore original map height cache to a point or rectangle area on the world
++ +
+ + +x1
+ number
+
+
+
+ y1
+ number
+
+
+
+ x2_factor
+ number
+ if y2 and factor are nil then this parameter is the factor
+ y2
+ number
+
+
+
+ (optional)
+ factor
+ number
+
+
+
+ (optional)
+ + + + Can only be called in `Spring.SetOriginalHeightMapFunc` + +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ height
+ number
+
+
+
+ + + + Can only be called in `Spring.SetOriginalHeightMapFunc` + +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ height
+ number
+
+
+
+ factor
+ number
+
+
+
+ (optional)
+ + + + Cannot recurse on itself + +
+ + +heightMapFunc
+ func
+
+
+
+ + +
+ + +x1
+ number
+
+
+
+ z1
+ number
+
+
+
+ x2
+ number
+
+
+
+ (optional)
+ z2
+ number
+
+
+
+ (optional)
+ height
+ number
+
+
+
+ + +
+ + +x1
+ number
+
+
+
+ z1
+ number
+
+
+
+ x2
+ number
+
+
+
+ (optional)
+ z2
+ number
+
+
+
+ (optional)
+ height
+ number
+
+
+
+ + +
+ + +x1
+ number
+
+
+
+ z1
+ number
+
+
+
+ x2
+ number
+
+
+
+ (optional)
+ z2
+ number
+
+
+
+ (optional)
+ origFactor
+ number
+
+
+
+ Can only be called in `Spring.SetSmoothMeshFunc`.
++ +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ height
+ number
+
+
+
+ Can only be called in `Spring.SetSmoothMeshFunc`.
++ +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ height
+ number
+
+
+
+ terraform
+ number
+
+
+
+ (default 1)
+ + +
+ + +lua_function
+ func
+
+
+
+ arg1
+ [opt]
+ arg2
+ [opt]
+ argn
+ [opt]
+ + +
+ +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ newType
+ number
+
+
+
+ + +
+ + +typeIndex
+ number
+
+
+
+ speedTanks
+ number
+
+
+
+ (default nil)
+ speedKBOts
+ number
+
+
+
+ (default nil)
+ speedHovers
+ number
+
+
+
+ (default nil)
+ speedShips
+ number
+
+
+
+ (default nil)
+ + +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ mask
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ weaponID
+ number
+
+
+
+ + +
+ + +transporterID
+ number
+
+
+
+ passengerID
+ number
+
+
+
+ pieceNum
+ number
+
+
+
+ + +
+ + +passengerID
+ number
+
+
+
+ + +
+ + +passengerID
+ number
+
+
+
+ Disables collisions between the two units to allow colvol intersection during the approach.
++ +
+ + +passengerID
+ number
+
+
+
+ transportID
+ number
+
+
+
+ + +
+ + +weaponDefID
+ number
+
+
+
+ projectileParams
+ projectileParams
+
+
+
+ Silently removes projectiles (no explosion).
++ +
+ + +projectileID
+ number
+
+
+
+ Parameters for explosion + + Please note the explosion defaults to 1 damage regardless of what it's defined in the weaponDef.
++ + The weapondefID is only used for visuals and for passing into callins like UnitDamaged. + +
+ + +weaponDef
+ number
+
+
+
+ owner
+ number
+
+
+
+ hitUnit
+ number
+
+
+
+ hitFeature
+ number
+
+
+
+ craterAreaOfEffect
+ number
+
+
+
+ damageAreaOfEffect
+ number
+
+
+
+ edgeEffectiveness
+ number
+
+
+
+ explosionSpeed
+ number
+
+
+
+ gfxMod
+ number
+
+
+
+ impactOnly
+ bool
+
+
+
+ ignoreOwner
+ bool
+
+
+
+ damageGround
+ bool
+
+
+
+ + +
+ + +posX
+ number
+
+
+
+ (default 0)
+ posY
+ number
+
+
+
+ (default 0)
+ posZ
+ number
+
+
+
+ (default 0)
+ dirX
+ number
+
+
+
+ (default 0)
+ dirY
+ number
+
+
+
+ (default 0)
+ dirZ
+ number
+
+
+
+ (default 0)
+ explosionParams
+ explosionParams
+
+
+
+ + +
+ + +cegname
+ string
+
+
+
+ posX
+ number
+
+
+
+ (default 0)
+ posY
+ number
+
+
+
+ (default 0)
+ posZ
+ number
+
+
+
+ (default 0)
+ dirX
+ number
+
+
+
+ (default 0)
+ dirY
+ number
+
+
+
+ (default 0)
+ dirZ
+ number
+
+
+
+ (default 0)
+ radius
+ number
+
+
+
+ (default 0)
+ damage
+ number
+
+
+
+ (default 0)
+ Equal to the UnitScript versions of EmitSFX, but takes position and direction arguments (in either unit- or piece-space) instead of a piece index.
++ +
+ + +unitID
+ number
+
+
+
+ (default 0)
+ sfxID
+ number
+
+
+
+ (default 0)
+ posX
+ number
+
+
+
+ (default 0)
+ posY
+ number
+
+
+
+ (default 0)
+ posZ
+ number
+
+
+
+ (default 0)
+ dirX
+ number
+
+
+
+ (default 0)
+ dirY
+ number
+
+
+
+ (default 0)
+ dirZ
+ number
+
+
+
+ (default 0)
+ radius
+ number
+
+
+
+ (default 0)
+ damage
+ number
+
+
+
+ (default 0)
+ absolute
+ bool
+
+
+
+ (optional)
+ + +
+ +
+ + +noPause
+ bool
+
+
+
+ Defines how often `Callins.UnitExperience` will be called.
++ +
+ + +expGrade
+ number
+
+
+
+ ExpPowerScale
+ number
+
+
+
+ (optional)
+ ExpHealthScale
+ number
+
+
+
+ (optional)
+ ExpReloadScale
+ number
+
+
+
+ (optional)
+ + +
+ + +allyTeamID
+ number
+
+
+
+ allyteamErrorSize
+ number
+
+
+
+ baseErrorSize
+ number
+
+
+
+ (optional)
+ baseErrorMult
+ number
+
+
+
+ (optional)
+ + +
Doesn't work in unsynced code!
++ +
+ + +unitID
+ number
+
+
+
+ cmdDescID
+ number
+
+
+
+ cmdArray
+ table
+
+structure of cmdArray:
+ {
+ [ id = int ],
+ [ type = int ],
+ [ name = string ],
+ [ action = string ],
+ [ tooltip = string ],
+ [ texture = string ],
+ [ cursor = string ],
+ [ queueing = boolean ],
+ [ hidden = boolean ],
+ [ disabled = boolean ],
+ [ showUnique = boolean ],
+ [ onlyTexture = boolean ],
+ [ params = { string = string, ... } ]
+ }
++ +
+ + +unitID
+ number
+
+
+
+ cmdDescID
+ number
+
+
+
+ (optional)
+ cmdArray
+ table
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ cmdDescID
+ number
+
+
+
+ (optional)
+ SyncedReadSynced Read
++ +
+ +
+ +
+ + + ++ +
+ + +allyID
+ number
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ Cartesian triple (XYZ)
++ +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ + +
+ + + ++ +
+ + +allyTeamID
+ number
+ to filter teams belonging to when >= 0
+ (default -1)
+ + +
+ + +teamID
+ number
+ to filter by when >= 0
+ (default -1)
+ active
+ bool
+ whether to filter only active teams
+ (default false)
+ + +
+ + +teamID
+ number
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ resource
+ string
+ one of "m(etal)?|e(nergy)?"
+ + +
+ + +teamID
+ number
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ resource
+ string
+ one of "m(etal)?|e(nergy)?"
+ + +
+ + +time
+ number
+
+
+
+ frame
+ number
+
+
+
+ metalUsed
+ number
+
+
+
+ metalProduced
+ number
+
+
+
+ metalExcess
+ number
+
+
+
+ metalReceived
+ number
+
+
+
+ metalSent
+ number
+
+
+
+ energyUsed
+ number
+
+
+
+ energyProduced
+ number
+
+
+
+ energyExcess
+ number
+
+
+
+ energyReceived
+ number
+
+
+
+ energySent
+ number
+
+
+
+ damageDealt
+ number
+
+
+
+ damageReceived
+ number
+
+
+
+ unitsProduced
+ number
+
+
+
+ unitsDied
+ number
+
+
+
+ unitsReceived
+ number
+
+
+
+ unitsSent
+ number
+
+
+
+ unitsCaptured
+ number
+
+
+
+ unitsOutCaptured
+ number
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ startIndex
+ number
+ when not specified return the number of history entries
+ (optional)
+ endIndex
+ number
+
+
+
+ (default startIndex)
+ + +
+ + +playerID
+ number
+
+
+
+ Returns unit controlled by player on FPS mode
++ +
+ + +playerID
+ number
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ + +
+ + +allyTeamID
+ number
+
+
+
+ + +
+ + +teamID1
+ number
+
+
+
+ teamID2
+ number
+
+
+
+ + +
+ + +playerID1
+ number
+
+
+
+ playerID2
+ number
+
+
+
+ + +
+ +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID1
+ number
+
+
+
+ unitID2
+ number
+
+
+
+ direction
+ bool
+ to subtract from, default unitID1 - unitID2
+ (default false)
+ subtractRadii
+ bool
+ whether units radii should be subtracted from the total
+ (default false)
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitDefID
+ number
+
+
+
+ + +
+ + + + + + ++ +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + + + + + ++ +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + + + + + ++ +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID1
+ number
+
+
+
+ featureID2
+ number
+
+
+
+ direction
+ bool
+ to subtract from, default featureID1 - featureID2
+ (default false)
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +allyTeamID
+ number
+
+
+
+ + +
+ +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ + +teamID
+ number
+
+
+
+ (optional)
+ + +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ +
+ + + ++ +
+ + + ++ +
+ +
+ + + ++ +
+ + + ++ + +
The following functions allow to save data per game, team and unit. + The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!)
++ +
+ + + ++ +
+ + +teamID
+ number
+
+
+
+ + +
+ + +playerID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +ruleRef
+ number or string
+ the rule index or name
+ + +
+ + +teamID
+ number
+
+
+
+ ruleRef
+ number or string
+ the rule index or name
+ + +
+ + +playerID
+ number
+
+
+
+ ruleRef
+ number or string
+ the rule index or name
+ + +
+ + +unitID
+ number
+
+
+
+ ruleRef
+ number or string
+ the rule index or name
+ + +
+ + +featureID
+ number
+
+
+
+ ruleRef
+ number or string
+ the rule index or name
+ + + +
Warning: boolean values are not transfered from C to Lua correctly. + For this reason the respective option has to be converted to a number + and checked accordingly via an IF statement as shown below:
+ + if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end
+The following check therefore is insufficient!
+ + if (Spring.GetModOptions.exampleOption) then...end
++ +
+ + + ++ +
+ + + ++ +
+ +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ + +
+ + +heading
+ number
+
+
+
+ + +
+ + +heading
+ number
+
+
+
+ + +
+ + +facing
+ number
+
+
+
+ + +
Side spec
++ + + Used when returning arrays of side specifications, is itself an array with + positional values as below: + +
+ + ++ +
+ + +sideID
+ number
+
+
+
+ + +
Get a list of all unitIDs
++ + + Note that when called from a widget, this also returns units that are only + radar blips. + + For units that are radar blips, you may want to check if they are in los, + as GetUnitDefID() will still return true if they have previously been seen. + +
+ + + ++ +
+ + +teamID
+ number
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ unitDefIDs
+ number or {number,...}
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ + + +
For the allegiance parameters: AllUnits = -1, MyUnits = -2, AllyUnits = -3, EnemyUnits = -4
++ +
+ + +xmin
+ number
+
+
+
+ zmin
+ number
+
+
+
+ xmax
+ number
+
+
+
+ zmax
+ number
+
+
+
+ allegiance
+ number
+
+
+
+ (optional)
+ + +
+ + +xmin
+ number
+
+
+
+ ymin
+ number
+
+
+
+ zmin
+ number
+
+
+
+ xmax
+ number
+
+
+
+ ymax
+ number
+
+
+
+ zmax
+ number
+
+
+
+ allegiance
+ number
+
+
+
+ (optional)
+ + +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ radius
+ number
+
+
+
+ + +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ radius
+ number
+
+
+
+ + +
+ + +normalVecX
+ number
+
+
+
+ normalVecY
+ number
+
+
+
+ normalVecZ
+ number
+
+
+
+ d
+ number
+
+
+
+ + + + Plane normals point towards accepted space, so the acceptance criteria for each plane is: + + radius = unit radius + px, py, pz = unit position + [(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0 + +
+ + +planes
+ {planeSpec,...}
+
+
+
+ allegiance
+ number
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ range
+ number
+
+
+
+ (default 1.0e9f)
+ + +
+ + +unitID
+ number
+
+
+
+ range
+ number
+
+
+
+ (default 1.0e9f)
+ useLOS
+ bool
+
+
+
+ (default true)
+ + +
+ +
+ + +xmin
+ number
+
+
+
+ zmin
+ number
+
+
+
+ xmax
+ number
+
+
+
+ zmax
+ number
+
+
+
+ + +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ radius
+ number
+
+
+
+ + +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ radius
+ number
+
+
+
+ allegiance
+ number
+
+
+
+ (optional)
+ + +
+ + +xmin
+ number
+
+
+
+ zmin
+ number
+
+
+
+ xmax
+ number
+
+
+
+ zmax
+ number
+
+
+
+ excludeWeaponProjectiles
+ bool
+
+
+
+ (default false)
+ excludePieceProjectiles
+ bool
+
+
+
+ (default false)
+ + +
+ +
+ + +unitID
+ number
+
+
+
+ + +
+ + +firestate
+ number
+
+
+
+ movestate
+ number
+
+
+
+ repeat
+ bool
+
+
+
+ cloak
+ bool
+
+
+
+ active
+ bool
+
+
+
+ trajectory
+ bool
+
+
+
+ autoland
+ bool
+ optional
+ autorepairlevel
+ number
+ optional
+ loopbackattack
+ bool
+ optional
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ type
+ string
+ one of los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
+ + +
+ + +unitID
+ number
+
+
+
+ allyTeamID
+ number
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ Checks if a unit is neutral (NOT Gaia!)
++ + + Note that a "neutral" unit can belong to any ally-team (ally, enemy, Gaia). + To check if a unit is Gaia, check its owner team. + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ midPos
+ bool
+ return midpoint as well
+ (default false)
+ aimPos
+ bool
+ return aimpoint as well
+ (default false)
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ Checks whether a unit is currently building another (NOT for checking if it's a structure)
++ + + Works for both mobile builders and factories. + +
+ + +unitID
+ number
+
+
+
+ Checks a builder's current task
++ + + Checks what a builder is currently doing. This is not the same as `Spring.GetUnitCurrentCommand`, + because you can have a command at the front of the queue and not be doing it (for example because + the target is still too far away), and on the other hand you can also be doing a task despite not + having it in front of the queue (for example you're Guarding another builder who does). Also, it + resolves the Repair command into either actual repair, or construction assist (in which case it + returns the appropriate "build" command). Only build-related commands are returned (no Move or any + custom commands). + + The possible commands returned are repair, reclaim, resurrect, capture, restore, + and build commands (negative buildee unitDefID). + +
+ + +unitID
+ number
+
+
+
+ + + Useful for setting move goals manually. +
+ + +unitID
+ number
+
+
+
+ buildeeDefID
+ number
+ or nil
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ +
+ + +projectileID
+ number
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ + + + Using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName + +
+ + +projectileID
+ number
+
+
+
+ + +
+ + +projectileID
+ number
+
+
+
+ tag
+ string
+
+one of:
+ "paralyzeDamageTime"
+ "impulseFactor"
+ "impulseBoost"
+ "craterMult"
+ "craterBoost"
+ "dynDamageExp"
+ "dynDamageMin"
+ "dynDamageRange"
+ "dynDamageInverted"
+ "craterAreaOfEffect"
+ "damageAreaOfEffect"
+ "edgeEffectiveness"
+ "explosionSpeed"
+ - or -
+ an armor type index to get the damage against it.
++ + + It is recommended to rather use GetProjectileDefID for indexing purposes. + +
+ + +projectileID
+ number
+
+
+
+ + +
+ +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ + +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ + +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ + +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ smoothed
+ bool
+ raw or smoothed center normal
+ (default false)
+ + +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ + +
+ + + + + + ++ +
+ + + ++ +
+ + +terrainTypeInfo
+ number
+
+
+
+ + +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ + +
+ + +x
+ number
+
+
+
+ z
+ number
+
+
+
+ + +
+ +
+ + +unitDefID
+ number
+
+
+
+ testTerrain
+ bool
+
+
+
+ (default true)
+ testObjects
+ bool
+
+
+
+ (default true)
+ centerOnly
+ bool
+
+
+
+ (default false)
+ + +
+ + +unitDefID
+ number
+
+
+
+ x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ facing
+ number or string
+ one of: 0-s,1-e,2-n,3-w
+ Snaps a position to the building grid
++ +
+ + +unitDefID
+ number
+
+
+
+ posX
+ number
+
+
+
+ posY
+ number
+
+
+
+ posZ
+ number
+
+
+
+ buildFacing
+ number
+ one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3
+ (default 0)
+ + +
+ + +teamID
+ number
+
+
+
+ unitDefID
+ number
+
+
+
+ posX
+ number
+
+
+
+ posY
+ number
+
+
+
+ posZ
+ number
+
+
+
+ searchRadius
+ number
+
+
+
+ minDistance
+ number
+
+
+
+ buildFacing
+ number
+ one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3
+ + +
+ +
+ + +posX
+ number
+
+
+
+ posY
+ number
+
+
+
+ posZ
+ number
+
+
+
+ allyTeamID
+ number
+
+
+
+ (optional)
+ + +
+ + +posX
+ number
+
+
+
+ posY
+ number
+
+
+
+ posZ
+ number
+
+
+
+ allyTeamID
+ number
+
+
+
+ (optional)
+ + +
+ + +posX
+ number
+
+
+
+ posY
+ number
+
+
+
+ posZ
+ number
+
+
+
+ allyTeamID
+ number
+
+
+
+ (optional)
+ + +
+ + +posX
+ number
+
+
+
+ posY
+ number
+
+
+
+ posZ
+ number
+
+
+
+ allyTeamID
+ number
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ allyTeamID
+ number
+
+
+
+ (optional)
+ raw
+ bool
+
+
+
+ (default false)
+ Raw is only available in gadgets and when raw parameter is true.
+ +RAW returns an bitmask integer, where the bits are: + 1: LOSINLOS, the unit is currently in the los of the allyteam, + 2: LOSINRADAR the unit is currently in radar from the allyteam, + 4: LOSPREVLOS the unit has previously been in los from the allyteam, + 8: LOSCONTRADAR the unit has continuously been in radar since it was last inlos by the allyteam
+ +
+ + +unitID
+ number
+
+
+
+ allyTeamID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ allyTeamID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ allyTeamID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ allyTeamID
+ number
+
+
+
+ + +
Piece spec
++ +
+ + +name
+ string
+
+
+
+ parent
+ string
+
+
+
+ children
+ {[string],...}
+ names
+ empty
+ bool
+
+
+
+ min
+ {number,number,number}
+ (x,y,z)
+ max
+ {number,number,number}
+ (x,y,z)
+ offset
+ {number,number,number}
+ (x,y,z)
+ + +
+ + +modelName
+ string
+
+
+
+ + +
+ + +modelName
+ string
+
+
+
+ + +
+ + +modelName
+ string
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ pieceIndex
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ pieceIndex
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ pieceIndex
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ pieceIndex
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ pieceIndex
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ pieceIndex
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ pieceIndex
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ pieceIndex
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ scriptPiece
+ number
+
+
+
+ (optional)
+ + +
+ + +unitID
+ number
+
+
+
+ UnsyncedCtrlCallouts to set state
++ +
gamedata/sounds.lua.
+ Color triple (RGB)
++ +
+ + +r
+ number
+
+
+
+ g
+ number
+
+
+
+ b
+ number
+
+
+
+ Color quadruple (RGBA)
++ +
+ + +r
+ number
+
+
+
+ g
+ number
+
+
+
+ b
+ number
+
+
+
+ a
+ number
+
+
+
+ + +
+ +
+ + + ++ +
+ + +decalIndex
+ number
+
+
+
+ + +
+ + +decalIndex
+ number
+
+
+
+ posX
+ number
+
+
+
+ posY
+ number
+
+
+
+ posZ
+ number
+
+
+
+ + +
+ + +decalIndex
+ number
+
+
+
+ sizeX
+ number
+
+
+
+ sizeY
+ number
+
+
+
+ + +
+ + +decalIndex
+ number
+
+
+
+ rot
+ number
+ in radians
+ + +
+ + +decalIndex
+ number
+
+
+
+ textureName
+ string
+
+
+
+ + +
+ + +decalIndex
+ number
+
+
+
+ alpha
+ number
+
+
+
+ Options can also be a bitmask; e.g. 0 instead of an empty table (can avoid performance hit on table creation)
+ See Constants.CMD for relevant constants.
Command Options params
++ + + Can be specified as a table, or as an array containing any of the keys + below. + +
+ + +right
+ bool
+ Right mouse key pressed
+ alt
+ bool
+ Alt key pressed
+ ctrl
+ bool
+ Ctrl key pressed
+ shift
+ bool
+ Shift key pressed
+ meta
+ bool
+ Meta (windows/mac/mod4) key pressed
+ + +
+ + ++ +
+ + +unitID
+ number
+
+
+
+ cmdID
+ number
+
+
+
+ params
+ table
+
+
+
+ options
+ cmdOpts
+
+
+
+ + +
+ + +unitMap
+ table
+ { [unitID] = arg1, ... }
+ cmdID
+ number
+
+
+
+ params
+ table
+
+
+
+ options
+ cmdOpts
+
+
+
+ + +
+ + +unitArray
+ {number,...}
+ array of unit ids
+ cmdID
+ number
+
+
+
+ params
+ table
+
+
+
+ options
+ cmdOpts
+
+
+
+ Command spec
++ + + Used when assigning multiple commands at once + +
+ + ++ +
+ + +unitID
+ number
+
+
+
+ cmdArray
+ {cmdSpec,...}
+
+
+
+ + +
+ + +unitMap
+ table
+ { [unitID] = arg1, ... }
+ cmdArray
+ {cmdSpec,...}
+
+
+
+ + +
+ + +unitArray
+ {number,...}
+ array of unit ids
+ cmdArray
+ {cmdSpec,...}
+
+
+
+ pairwise
+ bool
+ When false, assign all commands to each unit.
+
+When true, assign commands according to index between units and cmds arrays.
+ +If len(unitArray) < len(cmdArray) only the first len(unitArray) commands + will be assigned, and vice-versa. + (default false) +
+ +
+ + +spacing
+ number
+
+
+
+ + +
+ + +facing
+ number
+
+
+
+ + +
Send a ping request to the server
++ +
+ + +pingTag
+ number
+
+
+
+ Useful for debugging.
++ +
+ + +arg1
+
+
+
+ arg2
+
+
+
+ (optional)
+ argn
+ Prints values in the spring chat console.
+ Hint: the default print() writes to STDOUT.
+ (optional)
+ + +
+ + +section
+ string
+
+
+
+ logLevel
+ number or string
+
+
+Possible values for logLevel are:
+"debug" | LOG.DEBUG
+"info" | LOG.INFO
+"notice" | LOG.NOTICE (engine default) (new in Version 97)
+"warning" | LOG.WARNING
+"error" | LOG.ERROR
+"fatal" | LOG.FATAL
+logMessage1
+ string
+
+
+
+ logMessage2
+ string
+
+
+
+ (optional)
+ logMessagen
+ string
+
+
+
+ (optional)
+ + +
+ + ++ + + The ID's must refer to valid programs returned by `gl.CreateShader`. + Passing in a value of 0 will cause the respective shader to revert back to its engine default. + Custom map shaders that declare a uniform ivec2 named "texSquare" can sample from the default diffuse texture(s), which are always bound to TU 0. + +
+ + +standardShaderID
+ number
+
+
+
+ deferredShaderID
+ number
+
+
+
+ + +
+ + +texSqrX
+ number
+
+
+
+ texSqrY
+ number
+
+
+
+ luaTexName
+ string
+
+
+
+ + +
+ + +Spring.SetMapShadingTexture("$ssmf_specular", "name_of_my_shiny_texture")
+ +
+ +
+ + +message
+ string
+ <PLAYER#> (with # being a playerid) inside the string will be replaced with the players name - i.e. : Spring.SendMessage ("<PLAYER1> did something") might display as "ProRusher did something"
+ + +
+ + +playerID
+ number
+
+
+
+ message
+ string
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ message
+ string
+
+
+
+ + +
+ + +allyID
+ number
+
+
+
+ message
+ string
+
+
+
+ + +
Loads a SoundDefs file, the format is the same as in `gamedata/sounds.lua`.
++ +
+ + +soundfile
+ string
+
+
+
+ + +
+ + +soundfile
+ string
+
+
+
+ volume
+ number
+
+
+
+ (default 1.0)
+ posx
+ number
+
+
+
+ (optional)
+ posy
+ number
+
+
+
+ (optional)
+ posz
+ number
+
+
+
+ (optional)
+ speedx
+ number
+
+
+
+ (optional)
+ speedy
+ number
+
+
+
+ (optional)
+ speedz
+ number
+
+
+
+ (optional)
+ channel
+ number or string
+
+
+Possible arguments for channel argument:
+"general" || 0 || nil (default)
+"battle" || "sfx" | 1
+"unitreply" || "voice" || 2
+"userinterface" || "ui" || 3
+Allows to play an Ogg Vorbis (.OGG) and mp3 compressed sound file.
++ + + Multiple sound streams may be played at once. + +
+ + +oggfile
+ string
+
+
+
+ volume
+ number
+
+
+
+ (default 1.0)
+ enqueue
+ bool
+
+
+
+ (optional)
+ Terminates any SoundStream currently running.
++ +
+ + + +Pause any SoundStream currently running.
++ +
+ + + +Set volume for SoundStream
++ +
+ + +volume
+ number
+
+
+
+ + +
+ + + + + + ++ +
+ + +cmdID
+ number
+
+
+
+ posX
+ number
+
+
+
+ posY
+ number
+
+
+
+ posZ
+ number
+
+
+
+ + +
+ + +text
+ string
+
+
+
+ posX
+ number
+
+
+
+ posY
+ number
+
+
+
+ posZ
+ number
+
+
+
+ + +
+ + +unitDefID
+ number
+
+
+
+ posX
+ number
+
+
+
+ posY
+ number
+
+
+
+ posZ
+ number
+
+
+
+ teamID
+ number
+
+
+
+ facing
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +units
+ table
+ array of unit ids
+ tableOrArray
+ bool
+ [opt=false] when true units is interpreted as a table in the format { [unitID] = arg1, ... }
+ + +
Parameters for camera state
++ + + Highly dependent on the type of the current camera controller + +
+ + +name
+ string
+ "ta"|"spring"|"rot"|"ov"|"free"|"fps"|"dummy"
+ mode
+ number
+ the camera mode: 0 (fps), 1 (ta), 2 (spring), 3 (rot), 4 (free), 5 (ov), 6 (dummy)
+ fov
+ number
+
+
+
+ px
+ number
+ Position X of the ground point in screen center
+ py
+ number
+ Position Y of the ground point in screen center
+ pz
+ number
+ Position Z of the ground point in screen center
+ dx
+ number
+ Camera direction vector X
+ dy
+ number
+ Camera direction vector Y
+ dz
+ number
+ Camera direction vector Z
+ rx
+ number
+ Camera rotation angle on X axis (spring)
+ ry
+ number
+ Camera rotation angle on Y axis (spring)
+ rz
+ number
+ Camera rotation angle on Z axis (spring)
+ angle
+ number
+ Camera rotation angle on X axis (aka tilt/pitch) (ta)
+ flipped
+ number
+ -1 for when south is down, 1 for when north is down (ta)
+ dist
+ number
+ Camera distance from the ground (spring)
+ height
+ number
+ Camera distance from the ground (ta)
+ oldHeight
+ number
+ Camera distance from the ground, cannot be changed (rot)
+ For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.
++ +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ transTime
+ number
+
+
+
+ (optional)
+ + +
+ + +px
+ number
+ [opt=0]
+ py
+ number
+ [opt=0]
+ pz
+ number
+ [opt=0]
+ tx
+ number
+ [opt=0]
+ ty
+ number
+ [opt=0]
+ tz
+ number
+ [opt=0]
+ Sets camera state
++ + + The fields in `camState` must be consistent with the name/mode and current/new camera mode + +
+ + +camState
+ camState
+
+
+
+ transitionTime
+ number
+ in nanoseconds
+ (default 0)
+ transitionTimeFactor
+ number
+ multiplicative factor applied to this and all subsequent transition times for
+ this camera mode.
+
+Defaults to "CamTimeFactor" springsetting unless set previously. + (optional) +
transitionTimeExponent
+ number
+ tween factor applied to this and all subsequent transitions for this camera
+ mode.
+
+Defaults to "CamTimeExponent" springsetting unless set previously. + (optional) +
+ +
Selects a single unit
++ +
+ + +unitID
+ number
+ or nil
+ append
+ bool
+ append to current selection
+ (default false)
+ + +
+ + +unitID
+ number
+
+
+
+ Deselects multiple units.
++ Accepts a table with unitIDs as values + +
+ + +unitID
+ {[any]
+ , ...} unitIDs
+ Deselects multiple units.
++ Accepts a table with unitIDs as keys + +
+ + +any
+ {[unitID]
+ , ...} unitMap where keys are unitIDs
+ Selects multiple units, or appends to selection.
++ Accepts a table with unitIDs as values + +
+ + +unitID
+ {[any]
+ , ...} unitIDs
+ append
+ bool
+ append to current selection
+ (default false)
+ Selects multiple units, or appends to selection.
++ Accepts a table with unitIDs as keys + +
+ + +any
+ {[unitID]
+ , ...} unitMap where keys are unitIDs
+ append
+ bool
+ append to current selection
+ (default false)
+ + +
Parameters for lighting
++ +
+ + +px
+ number
+
+
+
+ py
+ number
+
+
+
+ pz
+ number
+
+
+
+ dx
+ number
+
+
+
+ dy
+ number
+
+
+
+ dz
+ number
+
+
+
+ red
+ number
+
+
+
+ green
+ number
+
+
+
+ blue
+ number
+
+
+
+ red
+ number
+
+
+
+ green
+ number
+
+
+
+ blue
+ number
+
+
+
+ red
+ number
+
+
+
+ green
+ number
+
+
+
+ blue
+ number
+
+
+
+ ambientWeight
+ number
+
+
+
+ diffuseWeight
+ number
+
+
+
+ specularWeight
+ number
+
+
+
+ ambientRedDecay
+ number
+
+
+
+ ambientGreenDecay
+ number
+
+
+
+ ambientBlueDecay
+ number
+
+
+
+ diffuseRedDecay
+ number
+
+
+
+ diffuseGreenDecay
+ number
+
+
+
+ diffuseBlueDecay
+ number
+
+
+
+ specularRedDecay
+ number
+
+
+
+ specularGreenDecay
+ number
+
+
+
+ specularBlueDecay
+ number
+
+
+
+ ambientDecayType
+ number
+
+
+
+ diffuseDecayType
+ number
+
+
+
+ specularDecayType
+ number
+
+
+
+ radius
+ number
+
+
+
+ fov
+ number
+
+
+
+ ttl
+ number
+
+
+
+ priority
+ number
+
+
+
+ ignoreLOS
+ bool
+
+
+
+ + + + requires MaxDynamicMapLights > 0 + +
+ + +lightParams
+ lightParams
+
+
+
+ + + + requires MaxDynamicMapLights > 0 + +
+ + +lightParams
+ lightParams
+
+
+
+ + +
+ + +lightHandle
+ number
+
+
+
+ lightParams
+ lightParams
+
+
+
+ + +
+ + +lightHandle
+ number
+
+
+
+ lightParams
+ lightParams
+
+
+
+ + +
+ + + + + + +Set a map-illuminating light to start/stop tracking the position of a moving object (unit or projectile)
++ +
+ + +lightHandle
+ number
+
+
+
+ unitOrProjectileID
+ number
+
+
+
+ enableTracking
+ bool
+
+
+
+ unitOrProjectile
+ bool
+
+
+
+ Set a model-illuminating light to start/stop tracking the position of a moving object (unit or projectile)
++ +
+ + +lightHandle
+ number
+
+
+
+ unitOrProjectileID
+ number
+
+
+
+ enableTracking
+ bool
+
+
+
+ unitOrProjectile
+ bool
+
+
+
+ + +
+ +
+ + +unitID
+ number
+
+
+
+ noDraw
+ bool
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ drawMask
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ alwaysUpdateMatrix
+ bool
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ unitNoMinimap
+ bool
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ unitNoSelect
+ bool
+ whether unit can be selected or not
+ + +
+ + +unitID
+ number
+
+
+
+ unitLeaveTracks
+ bool
+ whether unit leaves tracks on movement
+ + +
+ + +unitID
+ number
+
+
+
+ featureID
+ number
+
+
+
+ scaleX
+ number
+
+
+
+ scaleY
+ number
+
+
+
+ scaleZ
+ number
+
+
+
+ offsetX
+ number
+
+
+
+ offsetY
+ number
+
+
+
+ offsetZ
+ number
+
+
+
+ vType
+ number
+
+
+
+ tType
+ number
+
+
+
+ Axis
+ number
+
+
+
+ + +
+ +
+ + +featureID
+ number
+
+
+
+ noDraw
+ bool
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ engineDrawMask
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ alwaysUpdateMat
+ number
+
+
+
+ Control whether a feature will fade or not when zoomed out.
++ +
+ + +featureID
+ number
+
+
+
+ allow
+ bool
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ scaleX
+ number
+
+
+
+ scaleY
+ number
+
+
+
+ scaleZ
+ number
+
+
+
+ offsetX
+ number
+
+
+
+ offsetY
+ number
+
+
+
+ offsetZ
+ number
+
+
+
+ vType
+ number
+
+
+
+ tType
+ number
+
+
+
+ Axis
+ number
+
+
+
+ + +
+ +
+ + +iconName
+ string
+
+
+
+ texFile
+ string
+
+
+
+ size
+ number
+
+
+
+ (optional)
+ dist
+ number
+
+
+
+ (optional)
+ radAdjust
+ number
+
+
+
+ (optional)
+ + +
+ + +iconName
+ string
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ drawIcon
+ bool
+
+
+
+ + +
+ + +unitDefID
+ number
+
+
+
+ iconName
+ string
+
+
+
+ + +
+ + +unitDefID
+ number
+
+
+
+ image
+ string
+ luaTexture|texFile
+ + + +
Prefer using VFS whenever possible
++ +
+ + +modfile
+ string
+
+
+
+ + +
+ + +path
+ string
+
+
+
+ + +
+ +
+ + ++ +
+ + +cmdIndex
+ number
+
+
+
+ button
+ number
+
+
+
+ (default 1)
+ leftClick
+ bool
+
+
+
+ (optional)
+ rightClick
+ optional bool
+
+
+
+ alt
+ optional bool
+
+
+
+ ctrl
+ optional bool
+
+
+
+ meta
+ optional bool
+
+
+
+ shift
+ optional bool
+
+
+
+ + +
+ + + +Disables the "Selected Units x" box in the GUI.
++ +
+ + +enable
+ bool
+
+
+
+ + +
+ + +state
+ bool
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ r
+ number
+
+
+
+ g
+ number
+
+
+
+ b
+ number
+
+
+
+ Changes/creates the cursor of a single CursorCmd.
++ +
+ + +cmdName
+ string
+
+
+
+ iconFileName
+ string
+
+not the full filename, instead it is like this:
+ Wanted filename: Anims/cursorattack_0.bmp
+ => iconFileName: cursorattack
+overwrite
+ bool
+
+
+
+ (default true)
+ hotSpotTopLeft
+ bool
+
+
+
+ (default false)
+ Mass replace all occurrences of the cursor in all CursorCmds.
++ +
+ + +oldFileName
+ string
+
+
+
+ newFileName
+ string
+
+
+
+ hotSpotTopLeft
+ bool
+
+
+
+ (default false)
+ Register your custom cmd so it gets visible in the unit's cmd queue
++ +
+ + +cmdID
+ number
+
+
+
+ cmdReference
+ string or number
+ iconname | cmdID_cloneIcon
+ (optional)
+ + +
+ +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ + +
+ + +cursorName
+ string
+
+
+
+ cursorScale
+ number
+
+
+
+ (default 1.0)
+ + +
+ +
+ + +always
+ table
+ {r,g,b}
+ LOS
+ table
+ = {r,g,b}
+ radar
+ table
+ = {r,g,b}
+ jam
+ table
+ = {r,g,b}
+ radar2
+ table
+ = {r,g,b}
+ + +
+ + +rotVal
+ number
+ in degrees
+ (default 0)
+ rotVel
+ number
+ in degrees
+ (default 0)
+ rotAcc
+ number
+ in degrees
+ (default 0)
+ rotValRng
+ number
+ in degrees
+ (default 0)
+ rotVelRng
+ number
+ in degrees
+ (default 0)
+ rotAccRng
+ number
+ in degrees
+ (default 0)
+ + + +
The following functions read the engine configs saved in Springsettings.cfg, a version-ed instance of these or a custom file supplied on the command line.
+ +
+ + +name
+ string
+
+
+
+ value
+ number
+
+
+
+ useOverlay
+ bool
+ the value will only be set in memory, and not be restored for the next game.
+ (default false)
+ + +
+ + +name
+ string
+
+
+
+ value
+ number
+
+
+
+ useOverla
+ bool
+ the value will only be set in memory, and not be restored for the next game.y
+ (default false)
+ + +
+ + +name
+ string
+
+
+
+ value
+ number
+
+
+
+ useOverlay
+ bool
+ the value will only be set in memory, and not be restored for the next game.
+ (default false)
+ Closes the application
++ +
+ + + ++ +
+ +
+ + +unitID
+ number
+
+
+
+ groupID
+ number
+ the group number to be assigned, or -1 for deassignment
+ + +
Very important! (allows synced inter-lua-enviroment communications)
++ +
+ + ++ +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ + +
+ +
+ + +resource
+ string
+ metal | energy
+ shareLevel
+ number
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ units
+ string
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ resource
+ string
+ metal | energy
+ amount
+ number
+
+
+
+ + +
+ +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ text
+ string
+
+
+
+ (default "")
+ localOnly
+ bool
+
+
+
+ (optional)
+ + +
+ + +x1
+ number
+
+
+
+ y1
+ number
+
+
+
+ z1
+ number
+
+
+
+ x2
+ number
+
+
+
+ y2
+ number
+
+
+
+ z2
+ number
+
+
+
+ localOnly
+ bool
+
+
+
+ (default false)
+ playerId
+ number
+
+
+
+ (optional)
+ + + + Issue an erase command for markers on the map. + +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ noop
+
+
+
+ localOnly
+ bool
+ do not issue a network message, erase only for the current player
+ (default false)
+ playerId
+ number
+ when not specified it uses the issuer playerId
+ (optional)
+ alwaysErase
+ bool
+ erase any marker when localOnly and current player is spectating. Allows spectators to erase players markers locally
+ (default false)
+ + +
It can be used to modify the following atmosphere parameters
++ +
+ + +Spring.SetAtmosphere({ fogStart = 0, fogEnd = 0.5, fogColor = { 0.7, 0.2, 0.2, 1 }})+ +
+ + +dirX
+ number
+
+
+
+ dirY
+ number
+
+
+
+ dirZ
+ number
+
+
+
+ intensity
+ number
+
+
+
+ (default true)
+ It can be used to modify the following sun lighting parameters
++ +
+ + +Spring.SetSunLighting({groundAmbientColor = {1, 0.1, 1}, groundDiffuseColor = {1, 0.1, 1} })Map rendering params
++ +
+ + +Allows to change map rendering params at runtime.
++ +
+ + +params
+ mapRenderingParams
+
+
+
+ + +
+ + +normal
+ bool
+
+
+
+ (default true)
+ shadow
+ bool
+
+
+
+ (default false)
+ + +
+ +
+ + +aiTeam
+ number
+
+
+
+ message
+ string
+
+
+
+ + +
+ +
+ + ++ +
+ + +itersPerBatch
+ int
+
+
+
+ (optional)
+ numStepsPerIter
+ int
+
+
+
+ (optional)
+ minStepsPerIter
+ int
+
+
+
+ (optional)
+ maxStepsPerIter
+ int
+
+
+
+ (optional)
+ minLoopRunTime
+ number
+
+
+
+ (optional)
+ maxLoopRunTime
+ number
+
+
+
+ (optional)
+ baseRunTimeMult
+ number
+
+
+
+ (optional)
+ baseMemLoadMult
+ number
+
+
+
+ (optional)
+ + +
+ + +drawSky
+ bool
+
+
+
+ + +
+ + +drawWater
+ bool
+
+
+
+ + +
+ + +drawGround
+ bool
+
+
+
+ + +
+ + +drawGroundDeferred
+ bool
+
+
+
+ drawGroundForward
+ bool
+ allows disabling of the forward pass
+ treturn nil
+ (optional)
+ + +
+ + +drawUnitsDeferred
+ bool
+
+
+
+ drawFeaturesDeferred
+ bool
+
+
+
+ drawUnitsForward
+ bool
+ allows disabling of the respective forward passes
+ (optional)
+ drawFeaturesForward
+ bool
+ allows disabling of the respective forward passes
+ (optional)
+ This doesn't actually record the game in any way, it just regulates the framerate and interpolations.
++ +
+ + +allowCaptureMode
+ bool
+
+
+
+ + +
+ + +timeOffset
+ bool
+
+
+
+ Water params
++ +
+ + +absorb
+ rgb
+
+
+
+ baseColor
+ rgb
+
+
+
+ minColor
+ rgb
+
+
+
+ surfaceColor
+ rgb
+
+
+
+ diffuseColor
+ rgb
+
+
+
+ specularColor
+ rgb
+
+
+
+ planeColor
+ rgb
+
+
+
+ texture
+ string
+ file
+ foamTexture
+ string
+ file
+ normalTexture
+ string
+ file
+ damage
+ number
+
+
+
+ repeatX
+ number
+
+
+
+ repeatY
+ number
+
+
+
+ surfaceAlpha
+ number
+
+
+
+ ambientFactor
+ number
+
+
+
+ diffuseFactor
+ number
+
+
+
+ specularFactor
+ number
+
+
+
+ specularPower
+ number
+
+
+
+ fresnelMin
+ number
+
+
+
+ fresnelMax
+ number
+
+
+
+ fresnelPower
+ number
+
+
+
+ reflectionDistortion
+ number
+
+
+
+ blurBase
+ number
+
+
+
+ blurExponent
+ number
+
+
+
+ perlinStartFreq
+ number
+
+
+
+ perlinLacunarity
+ number
+
+
+
+ perlinAmplitude
+ number
+
+
+
+ numTiles
+ number
+
+
+
+ shoreWaves
+ bool
+
+
+
+ forceRendering
+ bool
+
+
+
+ hasWaterPlane
+ bool
+
+
+
+ + + + Does not need cheating enabled. + Allows to change water params (mostly BumpWater ones) at runtime. You may want to set BumpWaterUseUniforms in your springrc to 1, then you don't even need to restart BumpWater via `/water 4`. + +
+ + +waterParams
+ waterParams
+
+
+
+ + +
+ + + Allow the engine to load the unit's model (and texture) in a background thread. + Wreckages and buildOptions of a unit are automatically preloaded. + +
+ + +unitDefID
+ number
+
+
+
+ + +
+ + +featureDefID
+ number
+
+
+
+ + +
+ + +modelName
+ string
+
+
+
+ + +
+ +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ width
+ number
+
+
+
+ height
+ number
+
+
+
+ + +
+ + + ++ +
+ + + ++ +
+ +
+ + +displayIndex
+ number
+
+
+
+ winPosX
+ number
+
+
+
+ winPosY
+ number
+
+
+
+ winSizeX
+ number
+
+
+
+ winSizeY
+ number
+
+
+
+ fullScreen
+ bool
+
+
+
+ borderless
+ bool
+
+
+
+ + +
+ + + ++ +
+ + + ++ +
+ +
+ + +startScript
+ string
+ the CONTENT of the script.txt spring should use to start.
+ + + + If this call returns, something went wrong + +
+ + +commandline_args
+ string
+ commandline arguments passed to spring executable.
+ startScript
+ string
+
+
+
+ Launches a new Spring instance without terminating the existing one.
++ + + If this call returns, something went wrong + +
+ + +commandline_args
+ string
+ commandline arguments passed to spring executable.
+ startScript
+ string
+ the CONTENT of the script.txt spring should use to start (if empty, no start-script is added, you can still point spring to your custom script.txt when you add the file-path to commandline_args.
+ Sets the icon for the process which is seen in the OS task-bar and other places (default: spring-logo).
++ + + Note: has to be 24bit or 32bit. + Note: on windows, it has to be 32x32 pixels in size (recommended for cross-platform) + Note: *.bmp images have to be in BGR format (default for m$ ones). + Note: *.ico images are not supported. + +
+ + +iconFileName
+ string
+
+
+
+ Sets the window title for the process (default: "Spring
+
+
+ The shortTitle is displayed in the OS task-bar (default: "Spring
+ +
+ + +threadName
+ string
+
+
+
+ (default main)
+ Relinquish control of the game loading thread and OpenGL context back to the UI (LuaIntro).
++ + + Should be called after each widget/unsynced gadget is loaded in widget/gadget handler. Use it to draw screen updates and process windows events. + +
+ + +sleep
+ number
+ time in milliseconds.
+ # + local wantYield = Spring.Yield and Spring.Yield() -- nil check: not present in synced + for wupget in pairs(wupgetsToLoad) do + loadWupget(wupget) + wantYield = wantYield and Spring.Yield() + end
UnsyncedReadCallouts to get state
++ +
+ +
+ +
+ + + ++ +
+ + +decalIndex
+ number
+
+
+
+ + +
+ + +decalIndex
+ number
+
+
+
+ + +
+ + +decalIndex
+ number
+
+
+
+ + +
+ + +decalIndex
+ number
+
+
+
+ + +
+ + +decalIndex
+ number
+
+
+
+ + +
+ + +decalIndex
+ number
+
+
+
+ + +
+ + +decalIndex
+ number
+
+
+
+ + +
+ +
+ + +unitID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +forced
+ bool
+
+
+
+ (default false)
+ + +
+ + +blockingCall
+ bool
+
+
+
+ (default true)
+ + +
+ + +collectGC
+ bool
+ collect before returning metric
+ (default false)
+ + +
+ +
+ + + ++ +
+ + + ++ +
+ +
+ + + ++ +
+ +
+ + +profilerName
+ string
+
+
+
+ frameData
+ bool
+
+
+
+ (default false)
+ + +
+ + + ++ +
+ + + +Get a timer with millisecond resolution
+ +Get a timer with microsecond resolution
+ +Get a timer for the start of the frame
++ + + This should give better results for camera interpolations + +
+ + +lastFrameTime
+ bool
+ whether to use last frame time instead of last frame start
+ (default false)
+ + +
+ + +endTimer
+ Timer
+
+
+
+ startTimer
+ Timer
+
+
+
+ returnMs
+ bool
+ whether to return timeAmount in milliseconds as opposed to seconds
+ (default false)
+ fromMicroSecs
+ bool
+ whether timers are in microseconds instead of milliseconds
+ (default false)
+ + +
+ +
+ + + +SDL_GetNumVideoDisplaysGet main view geometry (map and game rendering)
++ +
+ + + +Get dual view geometry (minimap when enabled)
++ +
+ + + +Get main window geometry
++ +
+ + + +Get main window display mode
++ +
+ + + +Get screen geometry
++ +
+ + +displayIndex
+ number
+
+
+
+ (default -1)
+ queryUsable
+ bool
+
+
+
+ (default false)
+ Get minimap geometry
++ +
+ + + +Get minimap rotation
++ +
+ + + ++ +
+ + + +Get vertices from currently active selection box
++ + + Returns nil when selection box is inactive + +
+ + + ++ +
+ + + ++ +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ + +
+ + + ++ + + Ideally, when running 30hz sim, and 60hz rendering, the draw frames should + have and offset of either 0.0 frames, or 0.5 frames. + + When draw frames are not integer multiples of sim frames, some interpolation + happens, and this timeoffset shows how far along it is. + +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ nil
+ nil or bool
+ when unitID is invalid
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ + +featureID
+ number
+
+
+
+ + +
+ +
+ + +unitID
+ number
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ radius
+ number
+ unitRadius when not specified
+ (optional)
+ checkIcon
+ bool
+
+
+
+ + +
+ + +unitID
+ number
+
+
+
+ + +
+ + +minX
+ number
+
+
+
+ minY
+ number
+
+
+
+ minZ
+ number
+
+
+
+ maxX
+ number
+
+
+
+ maxY
+ number
+
+
+
+ maxZ
+ number
+
+
+
+ + +
+ + +posX
+ number
+
+
+
+ posY
+ number
+
+
+
+ posZ
+ number
+
+
+
+ radius
+ number
+
+
+
+ (default 0)
+ + +
+ + +unitID
+ number
+
+
+
+ midPos
+ bool
+
+
+
+ (default false)
+ + +
+ + +teamID
+ number
+
+
+
+ (default -1)
+ radius
+ number
+
+
+
+ (default 30)
+ icons
+ bool
+
+
+
+ (default true)
+ + +
+ + +teamID
+ number
+
+
+
+ (default -1)
+ radius
+ number
+
+
+
+ (default 30)
+ icons
+ bool
+
+
+
+ (default true)
+ geos
+ bool
+
+
+
+ (default true)
+ + +
+ + +allyTeamID
+ number
+
+
+
+ (default -1)
+ addSyncedProjectiles
+ bool
+
+
+
+ (default true)
+ addWeaponProjectiles
+ bool
+
+
+
+ (default true)
+ addPieceProjectiles
+ bool
+
+
+
+ (default true)
+ + +
+ + + + + + ++ +
+ + + + + + ++ +
+ + + + + + ++ +
+ + + + + + ++ +
+ + + ++ +
+ + + +Get units inside a rectangle area on the map
++ +
+ + +left
+ number
+
+
+
+ top
+ number
+
+
+
+ right
+ number
+
+
+
+ bottom
+ number
+
+
+
+ allegiance
+ number
+ teamID when > 0, when < 0 one of AllUnits = -1, MyUnits = -2, AllyUnits = -3, EnemyUnits = -4
+ (default -1)
+ Get features inside a rectangle area on the map
++ +
+ + +left
+ number
+
+
+
+ top
+ number
+
+
+
+ right
+ number
+
+
+
+ bottom
+ number
+
+
+
+ + +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ + + +Get selected units aggregated by unitDefID
++ +
+ + + +Get an aggregate count of selected units per unitDefID
++ +
+ + + +Returns the amount of selected units
++ +
+ + + +Get if selection box is handled by engine
++ +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ + +texSquareX
+ number
+
+
+
+ texSquareY
+ number
+
+
+
+ lodMin
+ number
+
+
+
+ luaTexName
+ string
+
+
+
+ lodMax
+ number
+
+
+
+ (default lodMin)
+ Color triple (RGB)
++ +
+ + +r
+ number
+
+
+
+ g
+ number
+
+
+
+ b
+ number
+
+
+
+ + +
+ + + ++ +
+ + + +Get available cameras
++ +
+ + + +Parameters for camera state
++ + + Highly dependent on the type of the current camera controller + +
+ + +name
+ string
+ "ta"|"spring"|"rot"|"ov"|"free"|"fps"|"dummy"
+ mode
+ number
+ the camera mode: 0 (fps), 1 (ta), 2 (spring), 3 (rot), 4 (free), 5 (ov), 6 (dummy)
+ fov
+ number
+
+
+
+ px
+ number
+ Position X of the ground point in screen center
+ py
+ number
+ Position Y of the ground point in screen center
+ pz
+ number
+ Position Z of the ground point in screen center
+ dx
+ number
+ Camera direction vector X
+ dy
+ number
+ Camera direction vector Y
+ dz
+ number
+ Camera direction vector Z
+ rx
+ number
+ Camera rotation angle on X axis (spring)
+ ry
+ number
+ Camera rotation angle on Y axis (spring)
+ rz
+ number
+ Camera rotation angle on Z axis (spring)
+ angle
+ number
+ Camera rotation angle on X axis (aka tilt/pitch) (ta)
+ flipped
+ number
+ -1 for when south is down, 1 for when north is down (ta)
+ dist
+ number
+ Camera distance from the ground (spring)
+ height
+ number
+ Camera distance from the ground (ta)
+ oldHeight
+ number
+ Camera distance from the ground, cannot be changed (rot)
+ + +
+ + +useReturns
+ bool
+ when true return multiple values instead of table
+ (default true)
+ + +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ + + +Cartesian triple (XYZ)
++ +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ + +
+ + + ++ +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ z
+ number
+
+
+
+ Get information about a ray traced from screen to world position
++ + + Extended to allow a custom plane, parameters are (0, 1, 0, D=0) where D is the offset D can be specified in the third argument (if all the bools are false) or in the seventh (as shown). + + Intersection coordinates are returned in t[4],t[5],t[6] when the ray goes offmap and includeSky is true), or when no unit or feature is hit (or onlyCoords is true). + + This will only work for units & objects with the default collission sphere. Per Piece collission and custom collission objects are not supported. + + The unit must be selectable, to appear to a screen trace ray. + +
+ + +screenX
+ number
+ position on x axis in mouse coordinates (origin on left border of view)
+ screenY
+ number
+ position on y axis in mouse coordinates (origin on top border of view)
+ onlyCoords
+ bool
+ return only description (1st return value) and coordinates (2nd return value)
+ (default false)
+ useMinimap
+ bool
+ if position arguments are contained by minimap, use the minimap corresponding world position
+ (default false)
+ includeSky
+ bool
+
+
+
+ (default false)
+ ignoreWater
+ bool
+
+
+
+ (default false)
+ heightOffset
+ number
+
+
+
+ (default 0)
+ + +
+ + +x
+ number
+
+
+
+ y
+ number
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ + +
+ + +teamID
+ number
+
+
+
+ + +
+ + + ++ +
+ +
+ + + ++ +
+ + + + + + ++ +
+ +
+ + + ++ +
+ + + ++ +
+ + +maxLatency
+ number
+ used for isSimLagging return parameter
+ (default 500)
+ + +
+ +
+ + + ++ +
+ + + +Command Description
++ + + Contains data about a command + +
+ + +id
+ number
+
+
+
+ type
+ number
+
+
+
+ name
+ string
+
+
+
+ action
+ string
+
+
+
+ tooltip
+ string
+
+
+
+ texture
+ string
+
+
+
+ cursor
+ string
+
+
+
+ queueing
+ bool
+
+
+
+ hidden
+ bool
+
+
+
+ disabled
+ bool
+
+
+
+ showUnique
+ bool
+
+
+
+ onlyTexture
+ bool
+
+
+
+ params
+ {[string],...}
+
+
+
+ + +
+ + +cmdIndex
+ number
+
+
+
+ + +
+ + +cmdID
+ number
+
+
+
+ + +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ +
+ + + ++ +
+ + +button
+ number
+
+
+
+ + +
+ +
+ + + ++ +
+ +
+ + +maxLines
+ number
+
+
+
+ + +
+ +
+ + +scanSymbol
+ string
+
+
+
+ + +
+ + +keyCode
+ number
+
+
+
+ + +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ + + ++ +
+ + +keySym
+ string
+
+
+
+ + +
+ + +keyCode
+ number
+
+
+
+ + +
+ + +scanCode
+ number
+
+
+
+ Keybinding spec
++ + + Contains data about a keybinding + +
+ + ++ +
+ + +keySet1
+ string
+ filters keybindings bound to this keyset
+ (optional)
+ keySet2
+ string
+ OR bound to this keyset
+ (optional)
+ + +
+ + +actionName
+ string
+
+
+
+ + +
+ +
+ + + ++ +
+ + + ++ +
+ + +unitID
+ number
+
+
+
+ + +
+ + +groupID
+ number
+
+
+
+ + +
+ + +groupID
+ number
+
+
+
+ + +
+ + +groupID
+ number
+
+
+
+ + +
+ + +groupID
+ number
+
+
+
+ + +
Roster spec
++ + + Contains data about a player + +
+ + +name
+ string
+
+
+
+ playerID
+ number
+
+
+
+ teamID
+ number
+
+
+
+ allyTeamID
+ number
+
+
+
+ spectator
+ bool
+
+
+
+ cpuUsage
+ number
+ in order to find the progress, use: cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000 for the progress
+ pingTime
+ number
+ if -1, the player is pathfinding
+ + +
+ + +sortType
+ number
+ return unsorted if unspecified. Disabled = 0, Allies = 1, TeamID = 2, PlayerName = 3, PlayerCPU = 4, PlayerPing = 5
+ (optional)
+ showPathingPlayers
+ bool
+
+
+
+ (default false)
+ + +
+ + +playerID
+ number
+
+
+
+ packetID
+ number
+ [opt]
+ + +
+ + +playerID
+ number
+
+
+
+ + +
Configuration spec
++ + + Contains data about a configuration, only name and type are guaranteed + +
+ + +name
+ string
+
+
+
+ type
+ string
+
+
+
+ description
+ string
+
+
+
+ defaultValue
+ string
+
+
+
+ minimumValue
+ string
+
+
+
+ maximumValue
+ string
+
+
+
+ safemodeValue
+ string
+
+
+
+ declarationFile
+ string
+
+
+
+ declarationLine
+ string
+
+
+
+ readOnly
+ bool
+
+
+
+ + +
+ + +name
+ string
+
+
+
+ default
+ number or nil
+
+
+
+ (default 0)
+ + +
+ + +name
+ string
+
+
+
+ default
+ number or nil
+
+
+
+ (default 0)
+ + +
+ + ++ +
+ + + +{ "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }VFSVirtual File System
++ +