Author: johns98@gmx.net

             _________ __                 __
            /   _____//  |_____________ _/  |______     ____  __ __  ______
            \_____  \\   __\_  __ \__  \\   __\__  \   / ___\|  |  \/  ___/
            /        \|  |  |  | \// __ \|  |  / __ \_/ /_/  >  |  /\___ \
           /_______  /|__|  |__|  (____  /__| (____  /\___  /|____//____  >
                   \/                  \/          \//_____/            \/
        ______________________                           ______________________
                              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 sync speed for the game. 100 is equivilent to 30 frames/second. 200 is equivilent to 60 frames/second.

speed
  The speed to set the game to as described, 100 is default
RETURNS
  Nothing

#### Exmaple

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

### 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.