_________ __                 __
        /   _____//  |_____________ _/  |______     ____  __ __  ______
        \_____  \\   __\_  __ \__  \\   __\__  \   / ___\|  |  \/  ___/
        /        \|  |  |  | \// __ \|  |  / __ \_/ /_/  >  |  /\___ \
       /_______  /|__|  |__|  (____  /__| (____  /\___  /|____//____  >
               \/                  \/          \//_____/            \/
    ______________________                           ______________________
                          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

Intro - Introduction to config functions and variables

Functions

AStar(tag, value, ...)

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()

RETURNS

Nothing

DefineDefaultActions("name", ...)

"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, ...])

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

"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", ...)

name

Name to give to the resource

RETURNS

Nothing

Example

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

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

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()

RETURNS

True if full screen, false if in windowed mode

Example

    -- Get Fullscreen
    fullscreen = GetVideoFullScreen()

GetVideoResolution()

RETURNS

Width and Height of current resolution

Example

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

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

"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

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

"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

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

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()

RETURNS

Nothing

Example

    RevealMap()

RightButtonAttacks()

RETURNS

Nothing

Example

    RightButtonAttacks()

RightButtonMoves()

RETURNS

Nothing

Example

    RightButtonMoves()

SavePreferences

RETURNS

Nothing

Example

    SavePreferences()

SetAllPlayersBuildingLimit(limit)

limit

The maximum number of buildings a player can have.

RETURNS

The limit that was set.

Example

    SetAllPlayersBuildingLimit(200)

SetAllPlayersUnitLimit(limit)

limit

Number of non-building unit the player can have

RETURNS

The limit that was set.

Example

    SetAllPlayersUnitLimit(200)

SetAllPlayersTotalUnitLimit(limit)

limit

The number of units to set the limit to.

RETURNS

The limit that was set.

Example

    SetAllPlayersTotalUnitLimit(400)

SetBuildingCapture(boolean)

boolean

true or false, depending on if you want building capture enabled.

RETURNS

Old value of Building Capture

Example

  SetBuildingCapture(true)

SetClickMissile("missile-type")

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)

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)

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)

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")

"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)

delay

The delay in ms.

Example

SetDoubleClickDelay(300)

SetEditorSelectIcon("icon-name")

"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")

icon

The name of the icon.

Example

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

SetEditorStartUnit("unit-start")

unit

The name of the unit.

Example

  SetEditorStartUnit("unit-start-location")

SetFancyBuildings(boolean)

SetFogOfWar(boolean)

SetFogOfWarColor(red,green,blue)

Example (white fog of war)

  SetFogOfWarColor(255,255,255)

SetFogOfWarGraphics(graphic)

Example

  SetFogOfWarGraphics("general/fog.png")

SetFogOfWarOpacity(number)

Example

  SetFogOfWarOpacity(128)

SetForestRegeneration(number)

SetGrabMouse(boolean)

SetGodMode(boolean)

boolean

#t for on, #f for off

RETURNS

Nothing

Example

    -- Set God mode on
    SetGodMode(#t)

SetHoldClickDelay(delay)

Example

  SetHoldClickDelay(1000)

SetKeyScroll(boolean)

SetKeyScrollSpeed(number)

Example

 SetKeyScrollSpeed(1)

SetLeaveStops(boolean)

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)

Example

SetMaxSelectable(18)

SetMetaServer("host", port)

Example

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

SetMinimapTerrain(boolean)

SetMouseScroll(boolean)

SetMouseScrollSpeed(number)

Example

  SetMouseScrollSpeed(1)

SetMouseScrollSpeedControl(speed)

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)

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)

SetSelectionStyle(tag)

"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)

SetShowCommandKey(boolean)

SetShowOrders(boolean or number)

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)

SetShowSightRange(tag)

false

None

"rectangle"

Alpha rectangle around unit

"circle"

Alpha circle around unit

true

Rectangle around unit

SetShowTips(boolean)

SetSpeedBuild(number)

SetSpeedResearch(number)

SetSpeedResourcesHarvest("resource-name", number)

Example

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

SetSpeedResourcesReturn("resource-name", number)

Example

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

SetSpeedTrain(number)

SetSpeedUpgrade(number)

SetSpeeds(number)

  SetSpeedResourcesHarvest("all-resource", number)
  SetSpeedResourcesReturn("all-resource", number)
  SetSpeedBuild(number)
  SetSpeedTrain(number)
  SetSpeedUpgrade(number)
  SetSpeedResearch(number)

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

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)

SetXPDamage(boolean)

SetUseHPForXp(boolean)

SetVideoFullScreen(boolean)

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)

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)

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()

ShowFull()

ShowHealthBar()

ShowHealthDot()

ShowHealthHorizontal()

ShowHealthVertical()

ShowManaBar()

ShowManaDot()

ShowManaHorizontal()

ShowManaVertical()

ShowNoFull()

SetGroupKeys("0123456789~")

keys

the keys to substitute to the 0 1 2 3 4... keys

Example

	(set-group-keys "à&é\"'(-è_ç²")