Spring - User contributions [en]

Script.txt

2016-01-19T00:44:01Z

Funkencool: Fix broken link

= Script.txt =
Start script file for Spring Engine.

Lobbies create it for spring, usually found in <code>~/.spring/script.txt</code> on Linux/MacOSX.

On Windows it can be found mostly in <code>My Documents\My Games\Spring\script.txt</code> or next to spring.exe.

== Structure ==
See {{sourcelink|file=doc/StartScriptFormat.txt}} for a more detailed example.

Spring 97.0 added <code>GAME/MUTATOR{0..9}</code> so you can load arbitrary mutator archives before the game. Additionally since 97.0 <code>GAME/GameID</code> is the only seed of the synced random generator, so you can define the <code>GameID</code> in a luaAI battle startscript and you will always get a syncing match.

Since 99.0 <code>GAME/Gametype</code> can be a [[rapid]] tag, and demo recording can be disabled by setting <code>GAME/RecordDemo</code> to 0

Overview of the structure:
<code><pre>[GAME]
{
// game attributes
[MUTATOR0]
{
// mutator attributes
}
[AI0]
{
// AI attributes
}
[PLAYER0]
{
// player attributes
}
[TEAM0]
{
// team attributes
}
[ALLYTEAM0]
{
// ally team attributes
}
[RESTRICT]
{
// restrictions
}
[MODOPTIONS]
{
// values for the options defined in Modoptions.lua
}
[MAPOPTIONS]
{
// values for the options defined in Mapoptions.lua
}
}</pre></code>

= Examples =
== minimal functional startscript ==
Based on {{forumlink|topic=32893&p=566971#p566953|title=these two posts:}}
<code><pre>
[GAME]
{
MapName=DeltaSiegeDry;
GameType=Balanced Annihilation V8.10;
IsHost=1;
[PLAYER0]
{
Team=0;
}
[TEAM0]
{
TeamLeader=0;
AllyTeam=0;
}
[ALLYTEAM0]
{
}
}
</pre></code>

== More examples ==
startscripts used for pre-defined offline matches vs AI in different team configurations -
https://code.google.com/p/springtanks/source/browse/#svn%2Ftrunk%2FMissions

= Generating startscripts =
It is possible to use for example Springlobby to setup a game via the Singleplayer tab.

The temporary file that gets generated can be copied for further use.

== Converting Lua tables to script.txt format ==

{{forumlink|topic=32643|title=lua table -> script.txt generator}} - thread with two examples

[[Category:Development]]

Mapdev:SMF format

2014-10-03T06:53:58Z

Funkencool: to match source code

= SMF(Spring Map File) Reference =
SMF is a binary format
* [https://github.com/spring/spring/blob/2e5bc43dc464ec27d6b880d105f0c618e07c4ff8/rts/Map/SMF/mapfile.h mapfile.h]
* [https://github.com/spring/spring/blob/2e5bc43dc464ec27d6b880d105f0c618e07c4ff8/rts/Map/SMF/SmfMapFile.cpp SmfMapFile.cpp]

== File location ==
maparchive.sd7/maps/mymapname.smf

== Data Map ==
* smu = spring map unit, the size you see when in the lobby. roughly between 2 and 64.
{| class="wikitable" width="100%"
|+ align="left" | Header
! style="width: 20%" | Bytes
! style="width: 20%" | Type !! Description
|-
| 16 || <code>char[]</code> || Magic number; "spring map file\0"
|-
| 4 || <code>int</code> || Version number; "1"
|-
| 4 || <code>unsigned int</code> || ID, should be as unique as possible.
|-
| 4 || <code>int</code> || Width; smu * 64
|-
| 4 || <code>int</code> || Length; smu * 64
|-
| 4 || <code>int</code> || Square size; 8
|-
| 4 || <code>int</code> || Texels per square size; 8
|-
| 4 || <code>int</code> || Tile size; 32
|-
| 4 || <code>float</code> || Depth/min height; 512 = 1*smu
|-
| 4 || <code>float</code> || Height/max height; 512 = 1*smu
|-
| 4 || <code>int</code> || Byte offset to start of height map
|-
| 4 || <code>int</code> || Byte offset to start of type map
|-
| 4 || <code>int</code> || Byte offset to start of tile index
|-
| 4 || <code>int</code> || Byte offset to start of mini map
|-
| 4 || <code>int</code> || Byte offset to start of metal map
|-
| 4 || <code>int</code> || Byte offset to start of features map
|-
| 4 || <code>int</code> || No of extra headers
|}

{| class="wikitable" width="100%"
|+ align="left" | + Extra Headers
! style="width: 20%" | Bytes
! style="width: 20%" | Type !! Description
|-
| 4 || <code>int</code> || Size of the header
|-
| 4 || <code>int</code> || Type of header
|-
| * || * || Data of header
|}
*
*
*
{| class="wikitable" width="100%"
|+ align="left" | + Height Map
! style="width: 20%" | Bytes
! style="width: 20%" | Type !! Description
|-
| (width+1)*(length+1) || <code>unsigned short[]</code> || Data for height map.
|}

{| class="wikitable" width="100%"
|+ align="left" | + Type Map
! style="width: 20%" | Bytes
! style="width: 20%" | Type !! Description
|-
| (width/2)*(length/2) || <code>char[]</code> || Data for type map.
|}

{| class="wikitable" width="100%"
|+ align="left" | + Mini Map
! style="width: 20%" | Bytes
! style="width: 20%" | Type !! Description
|-
| 699048 || <code>char[]</code> || raw DXT1 compressed 1024x1024 image.
|}

{| class="wikitable" width="100%"
|+ align="left" | + Tile Index Header
! style="width: 20%" | Bytes
! style="width: 20%" | Type !! Description
|-
| 4 || <code>int</code> || Number of tile files
|-
| 4 || <code>int</code> || Total number of tiles in all files.
|}

{| class="wikitable" width="100%"
|+ align="left" | + SMT File Infos
! style="width: 20%" | Bytes
! style="width: 20%" | Type !! Description
|-
| 4 || <code>int</code> || Number of tiles in this file
|-
| size of filename || <code>char[]</code> || The filename of the smt.
|}
*
*
*
{| class="wikitable" width="100%"
|+ align="left" | + Tile Index
! style="width: 20%" | Bytes
! style="width: 20%" | Type !! Description
|-
| (width / 4) * (length / 4) || <code>int[]</code> || Index numbers of tiles in SMT's
|}

{| class="wikitable" width="100%"
|+ align="left" | + Metal Map
! style="width: 20%" | Bytes
! style="width: 20%" | Type !! Description
|-
| (width / 2) * (length / 2) || <code>char[]</code> || Metal Density
|}

{| class="wikitable" width="100%"
|+ align="left" | + Features Header
! style="width: 20%" | Bytes
! style="width: 20%" | Type !! Description
|-
| 4 || <code>int</code> || Number of features
|-
| 4 || <code>int</code> || Number of feature types
|-
| * || <code>char[]</code> || List of feature names delimited by null
|}

{| class="wikitable" width="100%"
|+ align="left" | + Features
! style="width: 20%" | Bytes
! style="width: 20%" | Type !! Description
|-
| 4 || <code>int</code> || Type of feature, corresponds with feature name list.
|-
| 4 || <code>float</code> || X Position (along the width of the map)
|-
| 4 || <code>float</code> || Y Position (Up into the sky)
|-
| 4 || <code>float</code> || Z Position (along the length of the map)
|-
| 4 || <code>float</code> || rotation, not sure of scale
|-
| 4 || <code>float</code> || relative size (not implemented); 1
|}
*
*
*

== Optional Extra Headers & data ==
{| class="wikitable" width="100%"
|+ align="left" | + Grass Extra header
! style="width: 20%" | Bytes
! style="width: 20%" | Type !! Description
|-
| 4 || <code>int</code> || Size of the header; 12
|-
| 4 || <code>int</code> || Type of header; 1
|-
| 4 || <code>int</code> || Byte offset to beginning of grass map
|}

{| class="wikitable" width="100%"
|+ align="left" | + Grass Data
| style="width: 20%" | (width / 4) * (length / 4)
| style="width: 20%" | <code>unsigned char</code>
| Map defining the grass on the map. not sure what 256 available values mean.
|}

[[Category:Map Dev]]

Chili:Skins

2014-02-22T05:26:22Z

Funkencool: A basic page to describe altering/creating chili skins. I'm currently working on some code examples

First off this topic will probably benefit from a veterans touch. Still, I'm going to try my best to explain the ease at which chili skins can be created and altered.

Chili has been around since before I even touched lua (or any spring code for that matter) but it seems it's just finally becoming the standard. Just about every active/upcoming game is using it for their UI purposes now, and I'm kind of surprised there hasn't been more interest in custom skins from the player base. Maybe it's because they don't know how easy it is.

==What is a chili skin?==
Unlike previous UI frameworks, such as IceUI and RedUI, Chili can (and usually does) use textures for drawing elements.

A skin consists of 1 or more images which are assigned to chili elements through the '''skin.lua''' file.
https://dl.dropboxusercontent.com/u/19847614/Spring/Screens/Chiliskin.PNG

Each skin gets its own folder in "LuaUI/Chili/Skins/".

==How to alter a skin?==
First find and open the skin's directory. A good starting point is JK's default skin 'Robocracy' which is a very complete and well made skin (he did code chili).
In that case it would be in "luaui/chili/skins/robocracy"

From there find the texture you'd like to change, open it for editing with your program of choice, and let the creativity flow.

For basic alterations it's really that easy.

==Why?==
Because most, if not all of your Spring games will soon come with chili. What's cooler than seeing your own bad-ass skin while playing those games?

Lua:Callins

2014-02-15T23:40:31Z

Funkencool: I believe MouseWheel has the same return treatment as MousePress (so widgets can get control of scrolling)

= Lua Callins =
== Common ==
{{LuaCallin
|name = Initialize
|params =
|return = none
|description = Called when the addon is (re)loaded.
}}

{{LuaCallin
|name = Shutdown
|params =
|return = none
|description = Called when the addon or the game is shutdown.
}}

== Unsynced Only ==

{{LuaCallin
|name = DefaultCommand
|params = type, id
|return = number cmdID
|description = Used to set the default command when a unit is selected.
}}

{{LuaCallin
|name = CommandNotify
|params = cmdID, cmdParams, cmdOptions
|return = bool removeCmd
|description = Called when a command is issued. Returning <code>true</code> deletes the command and does not send it through the network.
}}

{{LuaCallin
|name = WorldTooltip
|params = ttType, data1, data2, data3
|return = string newTooltip
|description = The parameters can be <code>"unit"</code>, <code>unitID</code>; <code>"feature"</code>, <code>featureID</code>; <code>"ground"</code>, <code>posX</code>, <code>posY</code>, <code>posZ</code> or <code>"selection"</code>.
}}

{{LuaCallin
|name = UnsyncedHeightMapUpdate
|params = ???
|return = none
|description = Called when the unsynced copy of the height-map is altered.
}}

{{LuaCallin
|name = GameProgress
|params = serverFrameNum
|return = none
|description = Called every 60 frames, calculating delta between GameFrame and GameProgress. Can give an ETA about catching up with simulation for mid-game join players.
}}

{{LuaCallin
|name = GameSetup
|params = state, ready, playerStates
|return = bool newReady, bool renderDefaultGUI
|description = ???
}}

{{LuaCallin
|name = SunChanged
|params = ???
|return = none
|description = ???
}}

{{LuaCallin
|name = AddConsoleLine
|params = msg, priority
|return = none
|description = Called when text is entered into the console (e.g. Spring.Echo).
}}

{{LuaCallin
|name = RecvSkirmishAIMessage
|params = aiTeam, dataStr
|return = ???
|description = ???
}}

{{LuaCallin
|name = RecvFromSynced
|params = ...
|return = none
|description = Receives data sent via [[Lua_System#Synced|SendToUnsynced]] callout.
}}

{{LuaCallin
|name = Save
|params = zip
|return = none
|description = Called when a chat command '/save' or '/savegame' is received. The single argument is a userdatum representing the savegame zip file. See [[Lua_SaveLoad#Save_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

{{LuaCallin
|name = LoadProgress
|params = message, replaceLastLine
|return = none
|description = Only available to LuaIntro.
}}

{{LuaCallin
|name = GroupChanged
|params = ???
|return = ???
|description = ???
}}

{{LuaCallin
|name = ConfigureLayout
|params = ???
|return = ???
|description = ???
}}

=== Input ===
{{LuaCallin
|name = IsAbove
|params = x, y
|return = bool isAbove
|description = Called every Update. Must return <code>true</code> for <code>Mouse*</code> events and <code>GetToolTip</code> to be called.
}}

{{LuaCallin
|name = GetTooltip
|params = x, y
|return = string tooltip
|description = Called when <code>IsAbove</code> returns true.
}}

{{LuaCallin
|name = KeyPress
|params = key, mods, isRepeat
|return = none
|description = Called repeatedly when a key is pressed down. If you want an action to occur only once check for <code>isRepeat == false</code>. The <code>mods</code> parameter is a table, with keys <code>alt</code>, <code>ctrl</code>, <code>meta</code> and <code>shift</code> each having a boolean value.
}}

{{LuaCallin
|name = KeyRelease
|params = key
|return = none
|description = Called when the key is released.
}}

{{LuaCallin
|name = JoystickEvent
|params = ???
|return = none
|description = ???
}}

{{LuaCallin
|name = MousePress
|params = x, y, button
|return = bool becomeMouseOwner
|description = Called when a mouse button is pressed. The <code>button</code> parameter supports up to 7 buttons. Must return <code>true</code> for <code>MouseRelease</code> and other functions to be called.
}}

{{LuaCallin
|name = MouseRelease
|params = x, y, button
|return = bool becomeMouseOwner
|description = Called when a mouse button is released. Please note that in order to have Spring call <code>MouseRelease</code>, you need to have a <code>MousePress</code> call-in in the same addon that returns <code>true</code>.
}}

{{LuaCallin
|name = MouseWheel
|params = up, value
|return = none
|description = Called when the mouse wheel is moved. The parameters indicate the direction and amount of travel.
}}

{{LuaCallin
|name = MouseMove
|params = x, y, dx, dy, button
|return = none
|description = Called when the mouse is moved. The <code>dx</code> and <code>dy</code> parameters indicate the distance travelled, whereas the first two indicate the final position.
}}

=== Players ===
{{LuaCallin
|name = PlayerChanged
|params = playerID
|return = none
|description = Called whenever a player's status changes e.g. becoming a spectator.
}}

{{LuaCallin
|name = PlayerAdded
|params = playerID
|return = none
|description = Called whenever a new player joins the game.
}}

{{LuaCallin
|name = PlayerRemoved
|params = playerID, reason
|return = none
|description = Called whenever a player is removed from the game.
}}

=== Drawing ===

{{LuaCallin
|name = ViewResize
|params = viewSizeX, viewSizeY
|return = none
|description = Called whenever the window is resized.
}}

{{LuaCallin
|name = Update
|params = none
|return = none
|description = Called for every draw frame. The parameter is the time since the last update. Perform calculations in here and only drawing in Draw* callins.}}

Inside the Draw* functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.

{{LuaCallin
|name = DrawGenesis
|params =
|return = none
|description = Don't render here. Spring draws the sky, the map, some water types, and unit selection.
}}

{{LuaCallin
|name = DrawWorldPreUnit
|params =
|return = none
|description = Spring draws units, features, some water types, cloaked units, and the sun.
}}

{{LuaCallin
|name = DrawWorld
|params =
|return = none
|description = Spring draws command queues, 'map stuff', and map marks.
}}

{{LuaCallin
|name = DrawWorldShadow
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawWorldReflection
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawWorldRefraction
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawScreen
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawScreenEffects
|params = vsx, vsy
|return = none
|description = Where <code>vsx</code>, <code>vsy</code> are screen coords.
}}

{{LuaCallin
|name = DrawLoadScreen
|params =
|return = none
|description = {{new|95.0}} Only available to LuaIntro, draws custom load screens.
}}

{{LuaCallin
|name = DrawInMinimap
|params = sx, sy
|return = none
|description = Where <code>sx</code>, <code>sy</code> are values relative to the minimap's position and scale.
}}

=== Custom Object Rendering ===
For the following calls <code>drawMode</code> can be one of the following, <code>notDrawing = 0</code>, <code>normalDraw = 1</code>, <code>shadowDraw = 2</code>, <code>reflectionDraw = 3</code>, <code>refractionDraw = 4</code>.

{{LuaCallin
|name = DrawUnit
|params = unitID, drawMode
|return = bool suppressEngineDraw
|description = For custom rendering of units, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

{{LuaCallin
|name = DrawFeature
|params = unitID, drawMode
|return = bool suppressEngineDraw
|description = For custom rendering of features, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

{{LuaCallin
|name = DrawShield
|params = unitID, weaponID, drawMode
|return = bool suppressEngineDraw
|description = For custom rendering of [[Gamedev:WeaponDefs#Shield_(WeaponType)|shields]].
}}

{{LuaCallin
|name = DrawProjectile
|params = projectileID, drawMode
|return = bool suppressEngineDraw
|description = For custom rendering of weapon (& other) projectiles.
}}

== Synced - Unsynced Shared ==

=== Game ===

{{LuaCallin
|name = GameID
|params = gameID
|return = none
|description = Called once to deliver the gameID.
}}

{{LuaCallin
|name = GamePaused
|params =
|return = none
|description = Called when the game is paused.
}}

{{LuaCallin
|name = GameOver
|params = winningAllyTeams
|return = none
|description = The parameter is a list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).
}}

{{LuaCallin
|name = GameFrame
|params = frame
|return = none
|description = Called for every game simulation frame (30 per second).
}}

{{LuaCallin
|name = GamePreload
|params =
|return = none
|description = Called before the 0 gameframe.
}}

{{LuaCallin
|name = GameStart
|params =
|return = none
|description = Called upon the start of the game.
}}

=== Teams ===
{{LuaCallin
|name = TeamChanged
|params = teamID
|return = none
|description = ???
}}

{{LuaCallin
|name = TeamDied
|params = teamID
|return = none
|description = Called when a team dies (see [[Lua_SyncedCtrl#Game_End|Spring.KillTeam]]).
}}

=== Units ===
{{LuaCallin
|name = UnitCreated
|params = unitID, unitDefID, unitTeam, builderID
|return = none
|description = Called at the moment the unit is created.
}}

{{LuaCallin
|name = UnitFinished
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called at the moment the unit is completed.
}}

{{LuaCallin
|name = UnitFromFactory
|params = unitID, unitDefID, unitTeam, factID, factDefID, userOrders
|return = none
|description = Called when a factory finishes construction of a unit.
}}

{{LuaCallin
|name = UnitGiven
|params = unitID, unitDefID, newTeam, oldTeam
|return = none
|description = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitTaken
|params = unitID, unitDefID, oldTeam, newTeam
|return = none
|description = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitDamaged
|params = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a unit is damaged (after <code>UnitPreDamaged</code>).
}}

{{LuaCallin
|name = UnitDestroyed
|params = unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a unit is destroyed.
}}

{{LuaCallin
|name = UnitUnitCollision
|params = colliderID, collideeID
|return = none
|description = Called when two units collide. Both units must be registered with [[Lua_System#Synced|Script.SetWatchUnit]].
}}

{{LuaCallin
|name = UnitFeatureCollision
|params = colliderID, collideeID
|return = none
|description = Called when a unit collides with a feature. The unit must be registered with [[Lua_System#Synced|Script.SetWatchUnit]] and the feature registered with [[Lua_System#Synced|Script.SetWatchFeature]].
}}

{{LuaCallin
|name = UnitCommand
|params = unitID, unitDefID, teamID, cmdID, cmdParams, cmdOptions
|return = none
|description = Called after when a unit accepts a command, after <code>AllowCommand</code> returns <code>true</code>.
}}

{{LuaCallin
|name = UnitCmdDone
|params = unitID, unitDefID, unitTeam, cmdID, cmdTag, cmdParams, cmdOpts
|return = none
|description = Called when a unit completes a command.
}}

{{LuaCallin
|name = UnitLoaded
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|return = none
|description = Called when a unit is loaded by a transport.
}}

{{LuaCallin
|name = UnitUnloaded
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|return = none
|description = Called when a unit is unloaded by a transport.
}}

{{LuaCallin
|name = UnitExperience
|params = unitID, unitDefID, unitTeam, experience, oldExperience
|return = none
|description = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]].
}}

{{LuaCallin
|name = UnitIdle
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit is idle (empty command queue).
}}

{{LuaCallin
|name = UnitCloaked
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit cloaks.
}}

{{LuaCallin
|name = UnitDecloaked
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit decloaks.
}}

{{LuaCallin
|name = UnitMoved
|params = ???
|return = none
|description = ??? Not implemented in base handler
}}

{{LuaCallin
|name = UnitMoveFailed
|params = ???
|return = none
|description = ??? Not implemented in base handler
}}

{{LuaCallin
|name = StockpileChanged
|params = unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount
|return = none
|description = Called when a units stockpile of weapons increases or decreases. See {{xtaglink|Gamedev:WeaponDefs|stockpile}}.
}}

{{LuaCallin
|name = UnitEnteredLos
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit enters LOS of an allyteam.
}}

{{LuaCallin
|name = UnitLeftLos
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit leaves LOS of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredRadar
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit enters radar of an allyteam.
}}

{{LuaCallin
|name = UnitLeftRadar
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit leaves radar of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredAir
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftAir
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitEnteredWater
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftWater
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitSeismicPing
|params = x, y, z, strength, allyTeam, unitID, unitDefID
|return = none
|description = Called when a unit emits a seismic ping. See {{xtaglink|Gamedev:UnitDefs|seismicSignature}}.
}}

=== Features ===
{{LuaCallin
|name = FeatureCreated
|params = featureID, allyTeamID
|return = none
|description = Called when a feature is created.
}}

{{LuaCallin
|name = FeatureDamaged
|params = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a feature is damaged.
}}

{{LuaCallin
|name = FeatureDestroyed
|params = featureID, allyTeamID
|return = none
|description = Called when a feature is destroyed.
}}

{{LuaCallin
|name = FeatureMoved
|params = ???
|return = none
|description = ???
}}

=== Projectiles ===
The following Callins are only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]].

{{LuaCallin
|name = ProjectileCreated
|params = proID, proOwnerID, weaponDefID
|return = none
|description = Called when the projectile is created.
}}

{{LuaCallin
|name = ProjectileDestroyed
|params = proID
|return = none
|description = Called when the projectile is destroyed.
}}

{{LuaCallin
|name = Explosion
|params = weaponDefID, px, py, pz, ownerTeamID
|return = bool noGfx
|description = Called when an explosion occurs. If it returns <code>true</code> then no graphical effects are drawn by the engine for this explosion.
}}

== Synced Only ==
{{LuaCallin
|name = CommandFallback
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag
|return = bool used, bool finished
|description = Called when the unit reaches an unknown command in its queue (i.e. one not handled by the engine). If no addon returns <code>used</code> as <code>true</code> the command is dropped, if an addon returns <code>true, true</code> the command is removed because it's done, with <code>true, false</code> it's kept in the queue and <code>CommandFallback</code> gets called again on the next slowupdate.
}}

{{LuaCallin
|name = AllowCommand
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced
|return = bool allow
|description = Called when the command is given, before the unit's queue is altered. The return
value is whether it should be let into the queue. The queue remains untouched when a command is blocked, whether it would be queued or replace the queue.
}}

{{LuaCallin
|name = AllowUnitCreation
|params = unitDefID, builderID, builderTeam, x, y, z, facing
|return = bool allow
|description = Called just before unit is created, the boolean return value determines whether or not the creation is permitted.
}}

{{LuaCallin
|name = AllowUnitTransfer
|params = unitID, unitDefID, oldTeam, newTeam, capture
|return = bool allow
|description = Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.
}}

{{LuaCallin
|name = AllowUnitBuildStep
|params = builderID, builderTeam, unitID, unitDefID, part
|return = bool allow
|description = Called just before a unit progresses its build percentage, the boolean return value determines whether or not the build makes progress.
}}

{{LuaCallin
|name = AllowFeatureCreation
|params = featureDefID, teamID, x, y, z
|return = bool allow
|description = Called just before feature is created, the boolean return value determines whether or not the creation is permitted.
}}

{{LuaCallin
|name = AllowFeatureBuildStep
|params = builderID, builderTeam, featureID, featureDefID, part
|return = bool allow
|description = Called just before a feature progresses its build percentage, the boolean return value determines whether or not the progress change is permitted.
}}

{{LuaCallin
|name = AllowResourceLevel
|params = teamID, res, level
|return = bool allow
|description = Called when a team sets the sharing level of a resource, the boolean return value determines whether or not the sharing level is permitted.
}}

{{LuaCallin
|name = AllowResourceTransfer
|params = oldTeamID, newTeamID, res, amount
|return = bool allow
|description = Called just before resources are transferred between players, the boolean return value determines whether or not the transfer is permitted.
}}

{{LuaCallin
|name = AllowStartPosition
|params = clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ
|return = bool allow
|description = <code>clamped</code> are the coordinates clamped into start-boxes, <code>raw</code> is where player tried to place their marker. The <code>readyState</code> can be any one of <code>0</code> - player picked a position, <code>1</code> - player clicked ready, <code>2</code> - game was force-started (player did not click ready) or <code>3</code> the player failed to load. {{new|95.0}} the default 'failed to choose' start-position is now just <code>(0,0,0)</code>, not <code>(0,-500,0)</code>.
}}

{{LuaCallin
|name = AllowDirectUnitControl
|params = unitID, unitDefID, unitTeam, playerID
|return = bool allow
|description = Determines if this unit can be controlled directly in FPS view.
}}

{{LuaCallin
|name = AllowWeaponTargetCheck
|params = attackerID, attackerWeaponNum, attackerWeaponDefID
|return = bool allow
|description = Determines if this weapon can automatically generate targets itself. See also {{xtaglink|Gamedev:WeaponDefs|commandFire}} weaponDef tag.
}}

{{LuaCallin
|name = AllowWeaponTarget
|params = attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority
|return = bool allowed, number priority
|description = Controls blocking of a specific target from being considered during a weapon's periodic auto-targeting sweep. The second return value controls the priority of the target (maximum of <code>1.0</code>).
}}

{{LuaCallin
|name = AllowWeaponInterceptTarget
|params = interceptorUnitID, interceptorWeaponID, targetProjectileID
|return = bool allowed
|description = Controls blocking of a specific intercept target from being considered during an {{xtaglink|Gamedev:WeaponDefs|interceptor}} weapon's periodic auto-targeting sweep. Only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]].
}}

{{LuaCallin
|name = TerraformComplete
|params = unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam
|return = bool stop
|description = Called when pre-building terrain levelling terraforms are completed (c.f. {{xtaglink|Gamedev:UnitDefs|levelGround}}). If the return value is <code>true</code> the current build order is terminated.
}}

{{LuaCallin
|name = MoveCtrlNotify
|params = unitID, unitDefID, unitTeam, data
|return = bool moveCtrlComplete
|description = Enable both [[Lua_MoveCtrl#Options|Spring.MoveCtrl.SetCollideStop]] and [[Lua_MoveCtrl#Options|Spring.MoveCtrl.SetTrackGround]] to enable this call-in, data was supposed to indicate the type of notification but currently never has a value other than <code>1</code> ("unit hit the ground"). The return value determines whether or not the unit should remain script-controlled (<code>false</code>) or return to engine controlled movement (<code>true</code>).
}}

{{LuaCallin
|name = RecvLuaMsg
|params = msg, playerID
|return = none
|description = Receives messages from unsynced sent via [[Lua_UnsyncedCtrl#SendLuaMessage|Spring.SendLuaRulesMsg]].
}}

{{LuaCallin
|name = Load
|params = zip
|return = none
|description = Called after <code>GamePreload</code> and before <code>GameStart</code>. See [[Lua_SaveLoad#Load_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

=== Damage Controllers ===

{{LuaCallin
|name = UnitPreDamaged
|params = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = number newDamage, number impulseMult
|description = Called before damage is applied to the unit, allows fine control over how much damage and [http://en.wikipedia.org/wiki/Impulse_(physics) impulse] is applied.
}}

{{LuaCallin
|name = ShieldPreDamaged
|params = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile
|return = bool handleCollision
|description = Called before any engine shield-vs-projectile logic executes. If the return value is <code>true</code> the gadget handles the collision event and the engine does not remove the projectile.
}}

{{LuaCallin
|name = FeaturePreDamaged
|params = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = number newDamage, number impulseMult
|description = Called before damage is applied to the feature, allows fine control over how much damage and [http://en.wikipedia.org/wiki/Impulse_(physics) impulse] is applied.
}}

[[Category: Lua]]

LUPS

2013-06-11T20:55:14Z

Funkencool: Should look a little nicer now

Lua Particle System (LUPS)

Licensed under the terms of the GNU GPL, v2 or later.

== Implementation ==
First, you need to differ between synced and unsynced FX,
so there are 2 LUPS instances running:
one in LuaUI (widget) and
one in LuaRules (gadget).
(To start a new instance simply include lups/lups.lua)

== Why differ between synced and unsynced FX? ==
LuaUI has only a limited access to engine values, so it
could never determine the unittype of enemy units in airlos,
nor is it able to catch weapon explosion or to interact with
cob.

== Which files are used by LUPS? ==
the core uses the following:
lups/*
bitmaps/GPL/lups/*
LuaUI/Widgets/lups_wrapper.lua
LuaRules/Gadgets/lups_wrapper.lua (only if you want synced
FX like shockwaves/nanolasers)
and there are the managers:
LuaUI/Widgets/gfx_lups_manager.lua
LuaRules/Gadgets/gfx_lups_manager.lua
the shockwaves gadget:
LuaRules/Gadgets/lups_shockwaves.lua

== What are those managers? ==
LUPS itself doesn't start any FX. It needs other lua files
to tell LUPS when it should start a new FX.
There are many widgets and gadgets, which start LUPS FXs,
but the most interesting ones are the managers (and perhaps
the shockwaves gadget).
Also the manager in LuaRules differ from that one in LuaUI.
The manager in LuaUI starts FXs everytime an new unit gets
finished or an enemy unit enters the LOS, so those FX only
vanish if the unit dies or leaves the LOS again.
The LuaRules manager is much less customizable, it creates
very special FXs like cloaking and it also manage parts of
the LUPS nano particle handling.

== How do I implement my own FX? ==
Okay, in the case you use the LuaUI manager and you want to
create a per-unit FX (like a fusion FX, airjets, ...):

1. open LuaUI/Widgets/gfx_lups_manager.lua
(don't shock the file seems huge, but most is only config,
and yeah it needs a cleanup ... someday :x)
2. scroll down (~50% scrollbar)
you will find the following table/array:
"local UnitEffects = {...}"
It holds the FX per-unitdef.
3. create a new sub-table like the following:
[UnitDefNames["%UNITDEF_NAME%"].id] = {
{class='%FXCLASS%',options=%MY_FXOPTIONS_TABLE%}
},

== What FXClasses exist and how do I know their options? ==
All FXClasses are located here:
/lups/ParticleClasses/*
If you open on of those files, you will see a function like this:

function ShieldSphereParticle.GetInfo()
return {
name = "ShieldSphere",
}
end

That returned name is what you fill in %FXCLASS% (uppercase
doesn't matter), also it is in most cases same as the filename.
To see possible options of the FXClass scroll a bit down, you
will find a table like this:

ShieldSphereParticle.Default = {
pos = {0,0,0}, -- start pos
layer = -23,
life = 0, --in frames
size = 0,
sizeGrowth = 0,
margin = 1,
colormap1 = { {0, 0, 0, 0} },
colormap2 = { {0, 0, 0, 0} },
repeatEffect = false,
}

The table contains all options and their default values.
So an example fx placed in LuaUI/Widgets/gfx_lups_manager.lua
could look like this:
[UnitDefNames["armcom"].id] = {
{class='ShieldSphere',options={ life=3000, repeatEffect=true, size=300, colormap1={1,0,0,0.5}, colormap2={0,1,0,0.5} } }
},

== How do I start my own FX from my widget/gadget? ==
First, you need a link to the interface, to do so you need
to access the global shared table of the widget-/gadgetHandler.
for LuaUI:
local LupsApi = WG.Lups
for LuaRules:
local LupsApi = GG.Lups
(nil check those, it is possible that Lups hasn't started yet!)

That Api contains the following functions:
LupsApi.GetStats()
LupsApi.GetErrorLog(minPriority)
-> LupsApi.AddParticles(class,options) //returns a fxID
-> LupsApi.RemoveParticles(fxID)
LupsApi.AddParticlesArray({ {class=className, ..FX options..},{class=className, ..FX options..},.. } )
LupsApi.HasParticleClass(className)
and
LupsApi.Config = {...} //contains the options of lups.cfg

== Example usage of AddParticles() ==
LupsApi.AddParticles('ShieldSphere', {
unit=unitID,
piece="head",
pos={0,100,0},
life=3000,
repeatEffect=true,
size=300,
colormap1={1,0,0,0.5},
colormap2={0,1,0,0.5}
})

== How do I bind a FX to an unit/unitpiece? ==
There are some special options tags, those are:
unit := binds fx to unitID
piece:= binds fx to pieceNAME
pos := worldspace coord or offset coord from the unit/unitpiece center
onActive := only show FX if the unit is active (e.g. used for airjets - a plane is active, if it flies)

== Can I modify FX on runtime? ==
Sure you can. There is only one issue in 76b1 (it will
be fixed in the next spring release):
you can't modify widgets if they are in a .sdd, so you
have to copy it to your local widgets folder,
then you can run:
/luaui reload
each time you modified the file.

== I heard some options can contain Lua code? ==
Yeah, but only the SimpleParticles class support them and
_only_ in the "partpos" param:

LupsApi.AddParticles('SimpleParticles', {
...
partpos = "r*cos(beta)*sin(alpha),r*cos(alpha),r*sin(beta)*sin(alpha) | r=random()*20, alpha=2*math.pi*random(), beta=2*math.pi*random()"
...
})

The syntax is a bit extended so it looks similar to the
definitions of a mathical sets, but it can still contain
any lua code.

Valid examples are:
"x,y,z | x=10,y=30,z=0"
"10,30,0"
"random(),random(),random()"
"x,y,z | r=random(), if (r>10) then x=10; y=30; z=0; else x=-10; y=-30; z=-0; end"

[[Category:Libraries]]

Chili:Controls

2013-05-20T21:56:13Z

Funkencool: Created page with "== Checking The Source == As I fill this in or it becomes outdated, I suggest looking through the source code. The most up to date list of controls can be found at https://git..."

== Checking The Source ==
As I fill this in or it becomes outdated, I suggest looking through the source code.
The most up to date list of controls can be found at
https://github.com/jk3064/chiliui/tree/master/chili/controls

A widget containing an example of all the controls will most likely be found here https://github.com/jk3064/chiliui/blob/master/gui_chiliguidemo.lua

= Controls =
== control ==
== button ==
=== image ===
== checkbox ==
== colorbars ==
== label ==
== layoutpanel ==
=== imagelistview ===
=== grid ===
=== stackpanel ===
=== treeview ===
== progressbar ==
== scrollpanel ==
== textbox ==
== trackbar ==
== Window ==

Suggested maps for 3ffa

2012-06-17T13:36:42Z

Funkencool: /* Maps for 3 free for all games (xta) */

= Maps for 3 free for all games (xta) =

'''Good maps'''

*[http://www.springfiles.com/show_file.php?id=569 SaltRockColony]

*[http://www.springfiles.com/show_file.php?id=878 Ternion]

*[http://www.springfiles.com/show_file.php?id=579 Sherwood]

*[http://www.springfiles.com/search_result.php?search=Red%2520Triangle&select=select_all Red Triangle] (v2 or remake).

*[http://www.springfiles.com/show_file.php?id=2291 Sparewood Remake]

*[http://mapinfo.adune.nl/?map=Chernobyl Chernobyl] is sort of lol map, but has interesting gameplay.

*[http://mapinfo.adune.nl/?map=Curved_Focus Curved Focus] is an interesting alternative, it looks like chernobyl's less lol version.

*[http://www.springfiles.com/show_file.php?id=304 Gods of war 2 remake] it has 6 islands, so it can be setup for 3ffa, and let an island in between each player. A sea 3ffa map!.

*[http://springfiles.com/spring/spring-maps/trefoilv1 Trefoil v1] I may be biased as its my map, but I have a lot of fun with it!

'''Overplayed ones'''

*[http://www.springfiles.com/show_file.php?id=189 Desert triad] (this map is also thought to be unbalanced, as right side hill has terrain disponibility advantage.)

'''unbalanced'''

*[http://www.springfiles.com/show_file.php?id=699 The Cold Place] (remake is not suggested, as its too big, and has too much metal for a 3ffa, otoh it *may be well balanced for 3ffa unlike the original, reviewing upon testing)

[[Category:Maps]]