_________ __                 __
        /   _____//  |_____________ _/  |______     ____  __ __  ______
        \_____  \\   __\_  __ \__  \\   __\__  \   / ___\|  |  \/  ___/
        /        \|  |  |  | \// __ \|  |  / __ \_/ /_/  >  |  /\___ \
       /_______  /|__|  |__|  (____  /__| (____  /\___  /|____//____  >
               \/                  \/          \//_____/            \/
    ______________________                           ______________________
                          T H E   W A R   B E G I N S
           Stratagus - A free fantasy real time strategy game engine

Stratagus Configuration Language Description: Config


Stratagus FAQ PREV NEXT LUA Index
AStar DecorationOnTop DefineDecorations DefineDefaultActions DefineDefaultIncomes DefineDefaultResourceAmounts DefineDefaultResourceNames DefinesSprites GetVideoFullScreen GetVideoResolution HealthSprite ManaSprite RevealMap RightButtonAttacks RightButtonMoves SavePreferences SetAllPlayersBuildingLimit SetAllPlayersUnitLimit SetAllPlayersTotalUnitLimit SetBuildingCapture SetClickMissile SetCurrentChapter SetCurrentTip SetDamageFormula SetDamageMissile SetDoubleClickDelay SetEditorSelectIcon SetEditorUnitsIcon SetEditorStartUnit SetFancyBuildings SetFogOfWar SetFogOfWarColor SetFogOfWarGraphics SetFogOfWarOpacity SetForestRegeneration SetGrabMouse SetGodMode SetGroupKeys SetHoldClickDelay SetKeyScroll SetKeyScrollSpeed SetLeaveStops SetMaxOpenGLTexture SetMaxSelectable SetMetaServer SetMinimapTerrain SetMouseScroll SetMouseScrollSpeed SetMouseScrollSpeedControl SetMouseScrollSpeedDefault SetRevealAttacker SetSelectionStyle SetShowAttackRange SetShowCommandKey SetShowOrders SetShowReactionRange SetShowSightRange SetShowTips SetSpeedBuild SetSpeedResearch SetSpeedResourcesHarvest SetSpeedResourcesReturn SetSpeedTrain SetSpeedUpgrade SetSpeeds SetTitleScreens SetTrainingQueue SetXpDamage SetUseHPForXp SetVideoFullScreen SetVideoResolution SetVideoSyncSpeed ShowEnergySelectedOnly ShowFull DefineDecoration ShowHealthBar ShowHealthDot ShowHealthHorizontal ShowHealthVertical ShowManaBar ShowManaDot ShowManaHorizontal ShowManaVertical ShowNoFull

Intro - Introduction to config functions and variables

General configurations.

Functions

AStar(tag, value, ...)

Sets variables about the pathfinder. What the movement cost for unseen terrian is and whether units are aware of what's under unseen terrain. Items can be turned on and off to give desired behaviour, however dont-know-unseen-terrain will increase the amount the pathfinder is used at the start of a game while the map is being discovered. If you need the performance, turn it off.

The Cost of a move is 1 if moving straight, or 2 if moving diagonal.

"fixed-unit-cost", number
cost to move over a unit that is standing still. (must be greater than 3)
"moving-unit-cost", number
cost to move over a unit that is moving to somewhere. (must be greater than 3)
"unseen-terrain", number
Whether the pathfinder treats unknown terrain as visible when calculating paths or not. <'dont-know-unseen-terrain|'know-unseen-terrain>
"unseen-terrain-cost", number
Extra cost to move on unseen terrain, makes units tend towards know areas when finding paths.
"know-unseen-terrain"
consider (FIXME ? AI and human ?) know(s) all the terrain.
"dont-know-unseen-terrain"
consider (FIXME ? AI and human ?) do(es)n't know all the terrain.
RETURNS
Nothing

Example

AStar("fixed-unit-cost", 1000, "moving-unit-cost", 20, "know-unseen-terrain", "unseen-terrain-cost", 2)

DecorationOnTop()

Show bars and dots always on top.
RETURNS
Nothing

DefineDefaultActions("name", ...)

Defines the names of the actions used to harvest/get resources. eg mine gold, or drill oil.
"name"
The name to give to the action associated with the resource.
RETURNS
Nothing

Example

    -- In the same order as resources are defined.
    DefineDefaultActions("stop", "mine", "chop", "drill", "mine", "mine", "mine")

DefineDefaultIncomes([number, number, ...])

Defines the amount of resource to pickup by default when harvesting/collecting. When collecting gold for example you get 100 gold for a single pickup.
number
The amount of resource to collect by default per pickup.
RETURNS
Nothing

Example

    -- Define 7 default incomes
    -- Resources "time", "gold", "wood", "oil", "ore", "stone", "coal"
    DefineDefaultIncomes(0, 100, 100, 100, 100, 100, 100)

DefineDefaultResourceAmounts("name", amount ...)

Defines the default amounts to give to a resource producing unit when placing it for the first time in the editor.
"name"
The name of the resource for the default to be applied to
amount
The amount to set the default too.
RETURNS
Nothing

Example

    DefineDefaultResourceAmounts(
        "gold", 100000,
        "oil", 50000)

DefineDefaultResourceNames("name", ...)

Names the resources in a given order.
name
Name to give to the resource
RETURNS
Nothing

Example

    -- Define Resource names
    DefineDefaultResourceNames(
        "time", "gold", "wood", "oil", "ore", "stone", "coal")

DefineSprite({tag = value}, ...)

Define sprite to be shown for variables.
Tag could be :
Name = "sprite-name"
name of the sprite
File = "filename"
filename containing the sprite
Offset = {x, y}
offset when drawing the sprite
Size = {width, height}
Size of the sprite (!= of size of image)

Example

-- It is equivalent to :
-- HealthSprite("graphics/ui/health2.png", 0, -4, 31, 4)
-- ManaSprite("graphics/ui/mana2.png", 0, -1, 31, 4)
DefineSprites({Name = "sprite-health", File = "graphics/ui/health2.png", Offset = {0, -4}, Size = {31, 4}},
    {Name = "sprite-mana", File = "graphics/ui/mana2.png", Offset = {0, -1}, Size = {31, 4}})

GetVideoFullScreen()

Check if the game is in full screen or windowed mode.
RETURNS
True if full screen, false if in windowed mode

Example

    -- Get Fullscreen
    fullscreen = GetVideoFullScreen()

GetVideoResolution()

Get the video resolution.
RETURNS
Width and Height of current resolution

Example

    -- Get the video resolution
    w,h = GetVideoResolution()

HealthSprite(file, hotx, hoty, width, height)

Define health-sprite.
"file"
file where is the image.
hotx, hoty
offset from the sprite when it is drawn.
width, height
Size of the health sprite image.

Example

    HealthSprite("graphics/ui/health2.png", 0, -4, 31, 4)

Note

Use DefineSprites instead with Name="sprite-health".

ManaSprite(file, hotx, hoty, width, height)

Define mana-sprite.
"file"
file where is the image.
hotx, hoty
offset from teh sprite when it is drawn.
width, height
Size of the image.
RETURNS
Nothing

Example

ManaSprite("graphics/ui/mana2.png", 0, -1, 31, 4)

Note

Use DefineSprites instead with Name="sprite-mana".

DefineDecorations({tag = value, ...}, ...)

Define how to show variables.
Index = variable
To which variable it applies. Variables could be
Hitpoints
represent the HP of the unit.
Mana
represent the mana of the unit.
Transport
represent how many units are in the unit.
Ressources
represent ressource for gathering and gathered unit.
Training
represent the elapsed time of unit in training.
Research
represent the elapsed time for research.
UpgradeTo
represent the elapse time to evolve in the new unit.
variable
variable defined with DefineVariables()
Offset = {x, y}, OffsetPercent = {xp, yp}
Decoration is placed at {x + weight(unit) * xp, y + height(unit) * yp} from the unit.
CenterX = boolean, CenterY = boolean
If set to true, use center of decoration instead of the upper-left corner.
ShowIfNotEnable = boolean
if false (default), show decoration only when variable is enable.
ShowWhenNull = boolean
if true, show also when variable value is 0.
HideHalf = boolean
if true, don't show when variable value is not 0 nor max.
ShowWhenMax = boolean
if false, don't show when variable value is max.
ShowOnlySelected = boolean
if true, show only when unit is selected.
HideNeutral = boolean
if true, don't show for neutral unit.
HideAllied = boolean
if true, don't show for allied unit (but show your :) ).
ShowOpponent = boolean
if true, show also for opponent unit.
Method = {method-name, {tag = value}}
Which method we use to show variable. It could be a bar, a sprite, a number...
"text", {}
Show the value with a number
"static-sprite", {"sprite-name", number}
Use the number icon of the sprite (defined by DefineSprites())
"sprite", {"sprite-name"}
Show the p-th icon of the sprite (p depands of variable percent value: from full (left) to empty (right of th image)). The sprite is defined by DefineSprites().
"bar", {tag, value}
Show like a rectangular bar.
Orientation = "vertical" or "horizontal"
orientation of the bar, default is horizontal
SEToNW = boolean
if true, bar is growing from bottom to uppper border (for vertical bar) or right to left (for horizontal bar) (South-Easth to Nord-Weast).
Height = number, Width = number
size of the bar, 0 assume size of the unit.
BorderSize = number
bar is surroundded with a border.
ShowFullBackground
Show badgroung like if value is max

Example

-- Equivalent of ShowHealthDot
DefineDecorations({Index = "HitPoints", HideNeutral = true, CenterX = true,
  OffsetPercent = {50, 100}, Method = {"sprite", {"sprite-health"}}})

RevealMap()

Reveal the entire map.
RETURNS
Nothing

Example

    RevealMap()

RightButtonAttacks()

If you prefer fighters are attacking by right clicking empty space.
RETURNS
Nothing

Example

    RightButtonAttacks()

RightButtonMoves()

If you prefer fighters are moving by right clicking empty space.
RETURNS
Nothing

Example

    RightButtonMoves()

SavePreferences

Save the user preferences
RETURNS
Nothing

Example

    SavePreferences()

SetAllPlayersBuildingLimit(limit)

Set the limit on the number of buildings a player is allowed to have at one time.
limit
The maximum number of buildings a player can have.
RETURNS
The limit that was set.

Example

    SetAllPlayersBuildingLimit(200)

SetAllPlayersUnitLimit(limit)

Sets the number of non-building type units a player can have.
limit
Number of non-building unit the player can have
RETURNS
The limit that was set.

Example

    SetAllPlayersUnitLimit(200)

SetAllPlayersTotalUnitLimit(limit)

Sets the total number of units a player may have, building or non-building.
limit
The number of units to set the limit to.
RETURNS
The limit that was set.

Example

    SetAllPlayersTotalUnitLimit(400)

SetBuildingCapture(boolean)

Enable or disable building capture.
boolean
true or false, depending on if you want building capture enabled.
RETURNS
Old value of Building Capture

Example

  SetBuildingCapture(true)

SetClickMissile("missile-type")

Sets the missile to use for displaying when a player clicks on a location on the map.
missile-type
The missile to use, as defined in the missiles section
RETURNS
Old value of the click missile

Example

    SetClickMissile("missile-green-cross")

SetCurrentChapter(number)

Sets the current chapter in a campaign. A campaign can have any number of chapters. If too large a number is specified, it will default to the last chapter.
number
The number of the chapter to skip too as define in the campaign definition
RETURNS
Nothing

Example

    -- Set to chapter 2
	SetCurrentChapter(2)

SetCurrentTip(number)

Sets the number of the tip to display next. If larger than the number of tips or not tips are defined, it defaults to Tip 0.
number
The tip number to use, defaults to 0 on error
RETURNS
The old tip number that was set

Example

    -- Set Tip to No 10
    SetCurrentTip(10)

SetDamageFormula(NumberDesc)

Sets the formula to compute damage for missile that the unit fire on goal.
NumberDesc
Number description. See Trigger for a explanation.

Example

--
--  Damage is random between 51-100% of
--  Max(0, Attacker->BasicDamage - Defender->Armor) + Attacker->PiercingDamage.
--
  SetDamageFormula(Div(Mul(Add(51, Rand(50)),
				  Add(Max(0, Sub( AttackerVar("BasicDamage"), DefenderVar("Armor"))),
					  AttackerVar("PiercingDamage"))), 100))

SetDamageMissile("missile-type")

Sets the missile to use for displaying the damage done to units.
"missile-type"
missile name to use to display the damage
RETURNS
Old missile type defined as the Damage Missile

Example

  SetDamageMissile("missile-hit")

SetDoubleClickDelay(delay)

Set the delay of double clicking the mouse.
delay
The delay in ms.

Example

SetDoubleClickDelay(300)

SetEditorSelectIcon("icon-name")

Set the icon that is used in the editor to indicate selection.
"icon-name"
The name of the icon.

Example

  -- Use "icon-human-patrol-land" for the editor's select icon.
  SetEditorSelectIcon("icon-human-patrol-land")

SetEditorUnitsIcon("icon-name")

Set the icon that is used in the editory for unit selection.
icon
The name of the icon.

Example

  -- Use "icon-footman" for the editor's units icon.
  SetEditorUnitsIcon("unit-footman")

SetEditorStartUnit("unit-start")

Set the unit used in the editor to show the start location.
unit
The name of the unit.

Example

  SetEditorStartUnit("unit-start-location")

SetFancyBuildings(boolean)

if true, enable fancy building (random mirroring buildings).

SetFogOfWar(boolean)

If true, enable fog of war.

SetFogOfWarColor(red,green,blue)

Set the color of the fog of war. Each parameter is in the range 0-255.

Example (white fog of war)

  SetFogOfWarColor(255,255,255)

SetFogOfWarGraphics(graphic)

Set the graphics used to render the borders of the view of the units.

Example

  SetFogOfWarGraphics("general/fog.png")

SetFogOfWarOpacity(number)

Set the level of Opaqueness/transparency of the fog of war (0-255), 128 is optimized, all other values will be much slower to render.

Example

  SetFogOfWarOpacity(128)

SetForestRegeneration(number)

Set forest regeneration speed. (n * seconds, 0 = disabled)

SetGrabMouse(boolean)

Enable/disable grabbing the mouse.

SetGodMode(boolean)

Enable/disable god Mode, you do 255 damage, and take 0 damage. You are still vulnerable to spells.
boolean
#t for on, #f for off
RETURNS
Nothing

Example

    -- Set God mode on
    SetGodMode(#t)

SetHoldClickDelay(delay)

for the wanted hold-click delay (in ms)..

Example

  SetHoldClickDelay(1000)

SetKeyScroll(boolean)

enable/disable keyboard scrolling.

SetKeyScrollSpeed(number)

Set keyboard scroll speed in frames (1 = each frame,2 each second,...)

Example

 SetKeyScrollSpeed(1)

SetLeaveStops(boolean)

Enable/disable stopping scrolling on mouse leave.

Example

SetLeaveStops(true)

SetMaxOpenGLTexture(number)

Limit the size of OpenGL textures. If the game is slower with OpenGL than without it, try setting 1024, 512, or 256 as the limit.

Bos Wars asks OpenGL how large textures it supports, and then splits all of its graphics into pieces of that size or smaller. In some computers however, OpenGL reports support for e.g. 4096x4096 textures but draws those much slower than smaller ones. You can then set a smaller limit with this function. The new limit takes effect on the next InitVideo call.

If the parameter is 0, or greater than the limit reported by OpenGL, then Bos Wars uses the OpenGL limit instead.

Example

SetMaxOpenGLTexture(512)

SetMaxSelectable(number)

Set the maximum number of selectable units. (must be positive value)

Example

SetMaxSelectable(18)

SetMetaServer("host", port)

Set the default server for internet play. If you leave this blank, The Multiplay button will default to LAN game.

Example

SetMetaServer("www.myserver.com", 7775)

SetMinimapTerrain(boolean)

for minimap with/without terrain.

SetMouseScroll(boolean)

enable/disable mouse scrolling.

SetMouseScrollSpeed(number)

Set mouse scroll speed in frames (1=each frame,2 each second,...) This is when the mouse cursor hits the border.

Example

  SetMouseScrollSpeed(1)

SetMouseScrollSpeedControl(speed)

Sets the speed of the mouse scrolling while control is pressed.
speed
Set the number of pixels to scroll per mouse move of 1 pixel. negative = reversed
RETURNS
The old speed that was set

Example

    -- Set Mouse speed to
    SetMouseScrollSpeedControl(4)

SetMouseScrollSpeedDefault(speed)

Sets the speed of the mouse scrolling while the middle mouse button is pressed.
speed
Sets the number of pixels to scroll per mouse move of 1 pixel. negative = reversed
RETURNS
The old speed that was set

Example

    -- Set Speed Scroll to 5
    SetMouseScrollSpeedDefault(5)

SetRevealAttacker(boolean)

Sets if a unit will respond to the attacking unit or not. If set to true, they will respond whether they can see the unit or not. If set to false, they will only response if the attacker is within their reaction range.

SetSelectionStyle(tag)

Set selection style, show what units the user had selected.
"rectangle"
Rectangle around unit
"circle"
Circle around unit
"alpha-rectangle"
Rectangle with alpha around unit
"alpha-circle"
Circle with alpha around unit
"corners"
Draw corners of rectangle

Example

  SetSelectionStyle("corners")

SetShowAttackRange(boolean)

Enable/disable display of attack range of the selected unit on map.

SetShowCommandKey(boolean)

enable/disable the display of the command keys in buttons.

SetShowOrders(boolean or number)

Enable/disable display of the orders of the selected unit on map.
true
to always show unit orders
false
to never show orders.
number
the number of seconds an order should be shown.

Example

  -- show orders for 2 seconds
  SetShowOrders(2)

SetShowReactionRange(boolean)

Enable/disable display of reaction range of the selected unit on map.

SetShowSightRange(tag)

How the sight range of the selected unit is shown on map.
false
None
"rectangle"
Alpha rectangle around unit
"circle"
Alpha circle around unit
true
Rectangle around unit

SetShowTips(boolean)

enable/disable show tips at the start of a level

SetSpeedBuild(number)

Decrease the time to build a unit by this factor.

SetSpeedResearch(number)

Decrease the time to research by this factor.

SetSpeedResourcesHarvest("resource-name", number)

Set the harvesting speed of the resource.

Example

  -- Speeds up gold mining time by a factor of 10.
  SetSpeedResourcesHarvest("gold", 10)

SetSpeedResourcesReturn("resource-name", number)

Set the returning speed of the resource.

Example

  -- Speeds up the time spent returning gold by a factor of 10.
  SetSpeedResourcesReturn("gold", 10)

SetSpeedTrain(number)

Decrease the time to train a unit by this factor.

SetSpeedUpgrade(number)

Decrease the time to upgrade a unit by this factor.

SetSpeeds(number)

Set all speeds. This is equivalent to
  SetSpeedResourcesHarvest("all-resource", number)
  SetSpeedResourcesReturn("all-resource", number)
  SetSpeedBuild(number)
  SetSpeedTrain(number)
  SetSpeedUpgrade(number)
  SetSpeedResearch(number)

SetTitleScreens({tag = value, ...}, ...)

Change the default title screens.

Possible tags:
Image = "filepath"
Image or video to be displayed as title screen, this is the first screen displayed. The image should be a png file with 640x480 8-bit indexed colormap.
Music = "filepath" or "none"
Optional music to be played with the image or video. Use "none" to stop previously playing music.
Timeout = number
The number of seconds we should show this title-screen.(20 by default)
Editor = number
0 - display this title screen in normal startup (default)
1 - display this title screen only when starting Editor from command line
Label = { {Text = "text", Pos = {x, y}, Font = "font-name"}, ... }
Optional text to be displayed. It's a list of elements with three tags:
Text = "text"
The text string to render.
Pos = {x, y}
The text coords to render.
Font = FIXME
Font to use.
Flags = {tag, ...}
The flags that tell us how should be interpretated the pos coords. Possible and only value is "center".

Example

  -- This is the default title displayed.
  SetTitleScreens(
		{Image = "video/int_logo_stratagus.avi", Music =  "video/int_logo_stratagus.ogg",
		Label = {{Text = "~white~Copyright © 1998-2003 The Stratagus Project. All rights reserved.",
                          Pos = {0, 45}, Flags = {"center"}}} },
		{Image = "video/int_logo_bos.avi", Music =  "video/int_logo_bos.ogg"})

SetTrainingQueue(boolean)

enable/disable the training queues. (ability to train several units in a row)

SetXPDamage(boolean)

enable/disable XP to add more damage to attacks. FIXME : damage calculation.

SetUseHPForXp(boolean)

How the Xp is compute : if it is set to true then unit gains Xp equal to damage dealt to enemy unit else unit gains the max HP of the killed enemy unit.

SetVideoFullScreen(boolean)

Sets the video to full screen or windowed mode
boolean
#t, #f for true or false for full screen
RETURNS
the previous state of the full screen

Example

    -- Set Fullscreen
    SetVideoFullScreen(#t)

SetVideoResolution(x, y)

Sets the resolution of the video display, valid options are 640x480, 800x600, 1024x768, 1280x960 and 1600x1200.
x
Resolution in x from the 640,800,1024,1280,1600 list. Must match y
y
Resolution in y from the 480,600,768,960,1200 list. Must match x
RETURNS
Nothing

Example

    -- Set Screen res to 1024x768
    SetVideoResolution(1024, 768)

SetVideoSyncSpeed(speed)

Sets the video render speed for the game. 30 means 30 frames/second. 60 means 60 frames/second. Default is the native monitor refresh rate.
speed
The speed to set the game to as described, default is the monitor refresh rate.
RETURNS
Nothing

Example

    -- Set Speed to 60 frames/second
    SetVideoSyncSpeed(60)

ShowEnergySelectedOnly()

Show decoration only for selected unit.
Adjust options forDefineDecorations().

ShowFull()

Use to show bars or dots also when bar is full.
Adjust options forDefineDecorations().

ShowHealthBar()

Equivalent of ShowHealthVertical()
alias of DefineDecorations().

ShowHealthDot()

Adds a health sprite to the bottom of the unit.
alias of DefineDecorations().

ShowHealthHorizontal()

Show health bars horizontal.
alias of DefineDecorations().

ShowHealthVertical()

Show health bars vertical.
alias of DefineDecorations().

ShowManaBar()

Equivalent of ShowManaVertical()
alias of DefineDecorations().

ShowManaDot()

Show a mana sprite to the bottom of the unit.
alias of DefineDecorations().

ShowManaHorizontal()

Show mana bars horizontal.
alias of DefineDecorations().

ShowManaVertical()

Show mana bars vertical.
alias of DefineDecorations().

ShowNoFull()

Hide decorations when value is full.
Adjust options forDefineDecorations().

SetGroupKeys("0123456789~")

Define the key to use for group on non-us keyborads. It should be placed in preferences1.lua, with the key to use for group 0, 1, 2, ... 9, and the key to unselect all groups ( on the left of the 1 key )
keys
the keys to substitute to the 0 1 2 3 4... keys

Example

For french azerty, use :
	(set-group-keys "à&é\"'(-è_ç²")

(C) Copyright 2002-2015 by The Stratagus Project under the GNU General Public License.
All trademarks and copyrights on this page are owned by their respective owners.