Lua UnsyncedCtrl

2017-10-06T19:22:42Z

Jrb0001:

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

<div class="note">
NOTE: Prior to 102.0, entries below marked (needs ModUICtrl) require the setting ModUICtrl to be enabled in the users [[springrc]], if you want to use them in unsynced LuaRules/LuaGaia. It is enabled by default in previous versions and removed in 102.0 so you generally don't need to care.</div>

= UI =
'''Spring.SetLastMessagePosition'''
( number x, number y, number z ) -> nil

= Ingame Console =
'''Spring.Echo'''
( arg1 [, arg2 [, ... ] ] ) -> nil

Useful for debugging. Prints values in the spring chat console. Hint: the default print() writes to STDOUT.

'''Spring.Log'''
( string section, int logLevel | string logLevel,
arg2 [, arg3 [, ... ] ] ) -> nil

Possible values for logLevel are:
"debug" | LOG.DEBUG
"info" | LOG.INFO
"notice" | LOG.NOTICE (engine default) {{new|97}}
"warning" | LOG.WARNING
"error" | LOG.ERROR
"fatal" | LOG.FATAL

'''Spring.SendCommands''' (needs ModUICtrl)
( string command1 [, string command2 [ ... ] ] ) -> nil
( {string command1, string command2, ...} ) -> nil

== GUI ==
'''Spring.SetActiveCommand''' (needs ModUICtrl)
( string action [, string actionExtra ] ) -> nil | boolean
( number cmdIndex [, number button = 1
[, boolean leftClick, boolean rightClick,
boolean alt, boolean ctrl, boolean meta, boolean shift]] ) -> nil | boolean
'''Spring.LoadCmdColorsConfig''' (needs ModUICtrl)
( string config ) -> nil
'''Spring.LoadCtrlPanelConfig''' (needs ModUICtrl)
( string config ) -> nil
'''Spring.ForceLayoutUpdate''' (needs ModUICtrl)
( ) -> nil
'''Spring.SetDrawSelectionInfo''' disables the "Selected Units x" box in the GUI (needs ModUICtrl)
( boolean enable ) -> nil

== Mouse ==
'''Spring.SetMouseCursor''' (needs ModUICtrl)
( string cursorName [, number scale ] ) -> nil
'''Spring.WarpMouse''' (needs ModUICtrl)
( number x, number y ) -> nil

== LOS Colors ==
'''Spring.SetLosViewColors''' (needs ModUICtrl)

New arguments since 100.0 (radar2 is the inside of radar edge):
( always = {r,g,b}, LOS = {r,g,b}, radar = {r,g,b}, jam = {r,g,b}, radar2 = {r,g,b}) -> nil

Arguments for 99.0 and before:
( table reds = { number always, number LOS, number radar, number jam },
table greens = { number always, number LOS, number radar, number jam },
table blues = { number always, number LOS, number radar, number jam } ) -> nil

== SendMessage ==
'''Spring.SendMessage'''
( string "message" ) -> nil
'''Spring.SendMessageToPlayer'''
( number playerID, string "message" ) -> nil
'''Spring.SendMessageToTeam'''
( number teamID, string "message" ) -> nil
'''Spring.SendMessageToAllyTeam'''
( number allyID, string "message" ) -> nil
'''Spring.SendMessageToSpectators'''
( string "message" ) -> nil
Funfact:
<PLAYER#> (with # being a playerid) inside the string will be replaced with the players name.
ie
Spring.SendMessage ("<PLAYER1> did something")
might display as "ProRusher did something"

== Markers ==
'''Spring.MarkerAddPoint''' (needs ModUICtrl)
( number x, number y, number z [, string text = "" [, bool localOnly] ] ) -> nil
'''Spring.MarkerAddLine''' (needs ModUICtrl)
( number x1, number y1, number z1, number x2, number y2, number z2 ) -> nil
'''Spring.MarkerErasePosition''' (needs ModUICtrl)
( number x, number y, number z ) -> nil

= Sounds =
'''Spring.LoadSoundDef'''
( string "soundfile" ) -> nil | boolean success
Loads a SoundDefs file, the format is the same as in `gamedata/sounds.lua`.

'''Spring.PlaySoundFile''' Plays WAV or OGG sounds.
( string "soundfile" [, number volume = 1.0
[, number posx, number posy, number posz
[, number speedx, number speedy, number speedz ] ] ], [string/number channel ] ) -> nil | boolean
`channel` is new in Spring0.83, and can be one of those:
"general" || 0 || nil (default)
"battle" || "sfx" | 1
"unitreply" || "voice" || 2
"userinterface" || "ui" || 3


'''Spring.PlaySoundStream'''
( string "oggfile" [, number volume = 1.0
[, bool enqueue ]] ) -> nil | boolean true
Allow you to play an Ogg Vorbis (.OGG) compressed sound file. In 83.0 and up multiple sound streams may be played at once 
'''Spring.StopSoundStream'''
( ) -> nil
Terminates any SoundStream currently running.
'''Spring.PauseSoundStream'''
( ) -> nil
'''Spring.SetSoundStreamVolume'''
( number volume ) -> nil

= SendLuaMessage =
Very important! (allows synced inter-lua-enviroment communications)

'''Spring.SendLuaUIMsg''' (needs ModUICtrl)
( string message, string mode ) -> nil
possible modes are: "s"/"specs" & "a"/"allies"
'''Spring.SendLuaGaiaMsg''' (needs ModUICtrl)
( string message ) -> nil
'''Spring.SendLuaRulesMsg''' (needs ModUICtrl)
( string message ) -> nil

= AI =
'''Spring.SendSkirmishAIMessage''' {{new|83.0}}
( number aiTeam, string message )
-> nil | boolean ai_processed, { [1] = string response1, etc... }
Note there is nothing in this table due to "limitations" of the AI interface.

= Units =
'''Spring.SetUnitLeaveTracks''' {{new|83.0}}
( number unitID, boolean leavetracks ) -> nil

== Unit Selection ==
'''Spring.SelectUnitMap'''
( { [unitID] = anything, ...} [,boolean append] ) -> nil
'''Spring.SelectUnitArray'''
( { [1] = unitID1 , [2] = unitID2 , ...} [,boolean append] ) -> nil

'''Spring.SetDrawSelectionInfo'''
( boolean drawSelectionInfo ) -> nil

== Unit Group ==
'''Spring.SetUnitGroup''' (needs ModUICtrl)
( number unitID, number groupID ) -> nil

== Give Order ==
'''Spring.GiveOrder''' gives order to all selected units (needs ModUICtrl)
( number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnit''' (needs ModUICtrl)
( number unitID,
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnitMap''' (needs ModUICtrl)
( unitMap = { [unitID] = dontCare, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnitArray''' (needs ModUICtrl)
( unitArray = { [1] = unitID, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderArrayToUnitMap''' (needs ModUICtrl)
( unitMap = { [number unitID] = dontCare, etc... },
orderArray = {
{ number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"}
}, ..
}
) -> nil | boolean true
'''Spring.GiveOrderArrayToUnitArray''' (needs ModUICtrl)
( unitArray = { [1] = number unitID, etc... },
orderArray = {
{ number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"}
}, ..
},
[boolean pairwise]
) -> nil | boolean true

pairwise param ({{new|89.0}}) is used to send multiple units a single individual command

'''Spring.SetBuildFacing'''
( int Facing ) -> nil

'''Spring.SetBuildSpacing'''
( int Spacing ) -> nil

== Unit NoDraw,NoSelect,NoMinimap ==
'''Spring.SetUnitNoDraw''' LuaGadgets only!
( number unitID, boolean noDraw ) -> nil
'''Spring.SetUnitNoSelect''' LuaGadgets only!
( number unitID, boolean noSelect ) -> nil
'''Spring.SetUnitNoMinimap''' LuaGadgets only!
( number unitID, boolean noMinimap ) -> nil

= Features =
'''Spring.SetFeatureFade''' {{new|101.0}}
( int featureID, bool allow ) -> nil
Control whether a feature will fade or not when zoomed out.

'''Spring.SetFeatureNoDraw''' LuaGadgets only!
( number featureID, boolean noDraw ) -> nil

= Developers =
'''Spring.SetDrawSky'''
( boolean drawSky ) -> nil
'''Spring.SetDrawWater'''
( boolean drawWater ) -> nil
'''Spring.SetDrawGround'''
( boolean drawGround ) -> nil

'''Spring.SetWaterParams''' needs cheating enabled!
( table params ) -> nil
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`. 
`params` table may contain:
params = {
absorb = {number r, number g, number b},
baseColor = {number r, number g, number b},
minColor = {number r, number g, number b},
surfaceColor = {number r, number g, number b},
diffuseColor = {number r, number g, number b},
specularColor = {number r, number g, number b},
planeColor = {number r, number g, number b},
texture = string file,
foamTexture = string file,
normalTexture = string file,
damage = number value,
repeatX = number value,
repeatY = number value,
surfaceAlpha = number value,
ambientFactor = number value,
diffuseFactor = number value,
specularFactor = number value,
specularPower = number value,
fresnelMin = number value,
fresnelMax = number value,
fresnelPower = number value,
reflectionDistortion = number value,
blurBase = number value,
blurExponent = number value,
perlinStartFreq = number value,
perlinLacunarity = number value,
perlinAmplitude = number value,
numTiles = number value,
shoreWaves = boolean value,
forceRendering = boolean value,
hasWaterPlane = boolean value,
}

'''Spring.SetLogSectionFilterLevel''' {{New|95.0}}
(string sectionName, string|number logLevel)
see [[infolog.txt]] for possible log sections (?)

'''Spring.SetDrawGroundDeferred''' {{New|95.0}}
( boolean drawGroundDeferred [, boolean drawGroundForward] ) -> nil
{{new|101.0}} {{var|drawGroundForward}} allows disabling of the forward pass

'''Spring.SetDrawModelsDeferred''' {{New|95.0}}
( boolean drawUnitsDeferred,
boolean drawFeaturesDeferred
[, boolean drawUnitsForward
[, boolean drawFeaturesForward ]]
) -> nil

{{new|101.0}} {{var|drawFeaturesForward}}, {{var|drawUnitsForward}} allows disabling of the respective forward passes

= GUI =
'''Spring.DrawUnitCommands'''
( number unitID ) -> nil
( { [1] = unitID, ... } [, false ] ) -> nil
( { [unitID] = anything, ... }, true ) -> nil

'''Spring.SetTeamColor'''
( number teamID, number r, number g, number b ) -> nil

'''Spring.AssignMouseCursor''' changes/creates the cursor of a single CursorCmd
( string "cmdName", string "iconFileName"
[, boolean overwrite = true [, boolean hotSpotTopLeft = false] ] ) -> nil | boolean
Note, that iconFileName is not the full filename instead it is like this: 
wanted filename: Anims/cursorattack_0.bmp 
=> iconFileName: cursorattack


'''Spring.ReplaceMouseCursor''' mass replace all occurrence of the cursor in all CursorCmds
( string "oldFileName", string "newFileName" [, boolean hotSpotTopLeft = false] ) -> nil | boolean

'''Spring.SetCustomCommandDrawData''' register your custom cmd so it gets visible in the unit's cmd queue
( number cmdID,
number cmdID_cloneIcon | string iconname,
{ number r, number g, number b, number a } [, boolean showArea ] ) -> nil
( number cmdID, nil) -> nil

= Sharing =
'''Spring.SetShareLevel''' note: shareLevel is 0<= x <= 1 (needs ModUICtrl)
( string "metal" | "energy", number shareLevel ) -> nil
'''Spring.ShareResources''' (needs ModUICtrl)
( number teamID, string "units" ) -> nil
( number teamID, string "metal" | "energy", number amount ) -> nil

= UnitDef RadarIcons & BuildPics =
'''Spring.AddUnitIcon'''
( string iconName, string texFile [, number size [, number dist [, boolean radAdjust ]]] )
-> nil | boolean
'''Spring.FreeUnitIcon'''
( string iconName ) -> nil | boolean
'''Spring.SetUnitDefIcon''' (RadarIcon) (needs ModUICtrl)
( number unitDefID, string iconName ) -> nil
'''Spring.SetUnitDefImage''' (BuildPic) (needs ModUICtrl)
( number unitDefID, luaTexture | string texFile ) -> nil

= Camera =
'''Spring.SetCameraState'''
( table camState, number camTime) -> nil | boolean
camState has the same format as the output of Spring.GetCameraState(). See [[Lua_camState]] for details about camState.

The camState's mode/name must fit the rest of the state. Getting a state, changing its mode/name and then passing it to SetCameraState will have undesired results. [https://springrts.com/mantis/view.php?id=5028#c15491 Also see #5028]

'''Spring.SetCameraTarget'''
( number x, number y, number z [,number transTime] ) -> nil
For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.

'''Spring.SetCameraOffset''' (needs ModUICtrl)
( [number px = 0 [, number py = 0 [, number pz = 0
[, number tx = 0 [, number ty = 0 [, number tz = 0]]]]]] ) -> nil

= (Virtual-)FileSystem =
'''Spring.ExtractModArchiveFile'''
( string modfile ) -> boolean
'''Spring.CreateDir''' (needs ModUICtrl)
( number path ) -> nil | boolean

The full VFS API is available at [[Lua_VFS|link]].

= Engine Config =
The following functions read the engine configs saved in [[springrc]], a version-ed instance of these or a custom file supplied on the command line.
If ''*Overlay'' is ''true'', the value will only be set in memory, and not be restored for the next game

'''Spring.GetConfigInt''' (needs ModUICtrl)
( string name [, number default [, boolean setInOverlay = false]] ) -> nil | number
'''Spring.SetConfigInt''' (needs ModUICtrl)
( string name, number value [, boolean useOverlay = false] ) -> nil
'''Spring.GetConfigString''' (needs ModUICtrl)
( string name [, string default [, boolean setInOverlay = false]] ) -> nil | string
'''Spring.SetConfigString''' (needs ModUICtrl)
( string name, string value [, boolean useOverlay = false] ) -> nil

= World Primitives =
outdated! use opengl api instead!

'''Spring.AddWorldIcon'''
( number cmdID, number x, number y, number z ) -> nil
'''Spring.AddWorldText'''
( string "text", number x, number y, number z ) -> nil
'''Spring.AddWorldUnit'''
( number unitDefID,
number x, number y, number z,
number team, number facing) -> nil

= Sun =
The dynamic Sun must be invoked via /dynamicsun.

'''Spring.SetSunManualControl'''
( boolean setManualControl ) - > nil

'''Spring.SetSunParameters'''
( number dirX, number dirY, number dirZ, number dist, number startTime, number orbitTime ) -> nil

'''Spring.SetSunDirection'''
( number dirX, number dirY, number dirZ ) -> nil

'''Spring.SetSunLighting''' {{new|101.0}}
( table params ) -> nil

It can be used to modify the following sun lighting parameters:
{ground,unit}{Ambient,Diffuse,Specular}Color and specularExponent
All Colourvalues have to in the Range from 0.0 to 1.0 for all colors and the alpha
Example usage: Spring.SetSunLighting({groundAmbientColor = {1, 0.1, 1}, groundDiffuseColor = {1, 0.1, 1} })


'''Spring.SetAtmosphere''' {{new|101.0}}
( table params ) -> nil

It can be used to modify the following atmosphere parameters:
fog{Start,End}, {sun,sky,cloud}Color
Example usage: Spring.SetAtmosphere({ fogStart = 0, fogEnd = 0.5, fogColor = { 0.7, 0.2, 0.2, 1 }})


= Misc =

'''Spring.Reload''' {{new|99.0}}
( string startscript )
start-script is the CONTENT of the [[script.txt]] spring should use to start.

'''Spring.Restart''' {{new|0.79}}
( string commandline_args, string startscript )
-> if this call returns, something went wrong
''commandline_args'' are commandline arguments passed to spring executable

start-script is 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''

'''Spring.SetWMIcon''' {{new|83.0}}
( string iconFileName ) -> nil
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.

'''Spring.SetWMCaption''' {{new|83.0}}
( string title [, string titleShort = title ] ) -> nil

Sets the window ''title'' for the process (default: "Spring <version>").

The ''shortTitle'' is displayed in the OS task-bar (default: "Spring <version>").

'''NOTE:''' ''shortTitle'' is only ever possibly used under X11 (Linux & OS X), but not with QT (KDE) and never under Windows. See [http://www.gpwiki.org/index.php/SDL:Tutorials:Initializing_SDL_Libraries#About_the_icon_.28.22Icon_Title.22.29_parameter_on_different_window-managers this site] for more details.

'''Spring.ClearWatchDogTimer''' {{new|83.0}}
( [ string threadName = main ] ) -> nil

'''Spring.SetClipboard''' {{new|98.0}}
( string text) -> nil

= Rendering =
== Preload ==
Allow the engine to load the unit's model (and texture) in a background thread. Wreckages and buildOptions of a unit are automatically preloaded.

'''Spring.PreloadUnitDefModel''' {{new|101.0}}
( number unitDefID ) -> nil

'''Spring.PreloadFetureDefModel''' {{new|101.0}}
( number featureDefID ) -> nil

== Lighting ==
NOTE: these (0.83+) lighting callouts only work when called from unsynced gadgets!

'''Spring.AddMapLight''' (requires MaxDynamicMapLights > 0)
(table lightParams) -> number lightHandle
'''Spring.AddModelLight''' (requires MaxDynamicModelLights > 0)
(table lightParams) -> number lightHandle

'''Spring.UpdateMapLight'''
(number lightHandle, table lightParams) -> boolean success
'''Spring.UpdateModelLight'''
(number lightHandle, table lightParams) -> boolean success

'''Spring.SetMapLightTrackingState'''
(number lightHandle, number unitOrProjectileID,
boolean enableTracking, boolean unitOrProjectile) -> boolean success
'''Spring.SetModelLightTrackingState'''
(number lightHandle, number unitOrProjectileID,
boolean enableTracking, boolean unitOrProjectile) -> boolean success

'''lightParams''' is a table that should contain at least one of the following recognized key/value pairs:

lightParams = {
position = {px, py, pz},
direction = {dx, dy, dz},
ambientColor = {red, green, blue},
diffuseColor = {red, green, blue},
specularColor = {red, green, blue},
intensityWeight = {ambientWeight, diffuseWeight, specularWeight},

-- per-frame decay of ambientColor (spread over TTL frames)
ambientDecayRate = {ambientRedDecay, ambientGreenDecay, ambientBlueDecay},
-- per-frame decay of diffuseColor (spread over TTL frames)
diffuseDecayRate = {diffuseRedDecay, diffuseGreenDecay, diffuseBlueDecay},
-- per-frame decay of specularColor (spread over TTL frames)
specularDecayRate = {specularRedDecay, specularGreenDecay, specularBlueDecay},
-- *DecayType = 0.0 -> interpret *DecayRate values as linear, else as exponential
decayFunctionType = {ambientDecayType, diffuseDecayType, specularDecayType},

radius = number elmos,
fov = number degrees,
ttl = number frames,
priority = number,
ignoreLOS = boolean,
}

= Map =
'''Spring.SetSkyBoxTexture''' {{new|101.0}}
( string texName ) -> nil

'''Spring.SetMapShadingTexture''' {{new|101.0}}
( string texType, string texName ) -> boolean success

<div class="note">Example usage: Spring.SetMapShadingTexture("$ssmf_specular", "name_of_my_shiny_texture")</div>

'''Spring.SetMapSquareTexture'''
( number texSqrX, number texSqrY, string luaTexName ) -> boolean success

'''Spring.SetMapShader''' {{101.0}}
( number standardShaderID, number deferredShaderID ) -> nil

<div class="note">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.</div>

[[category: Lua]]

Spring - User contributions [en]

Lua UnsyncedCtrl