# Bos Wars Scripting API: Config

Bos Wars FAQ PREV NEXT LUA Index

AStarFixedUnitCrossingCost AStarKnowUnseenTerrain AStarMovingUnitCrossingCost AStarUnknownTerrainCost AlliedUnitRecyclingEfficiency DefineDecorations DefineDefaultResourceNames DefineSprites EnemyUnitRecyclingEfficiency EnergyCost GetVideoFullScreen GetVideoResolution MagmaCost MaxCosts Preference preferences RevealMap RightButtonAttacks RightButtonMoves SavePreferences SetAllPlayersBuildingLimit SetAllPlayersUnitLimit SetAllPlayersTotalUnitLimit SetBuildingCapture SetClickMissile SetDamageMissile SetDoubleClickDelay SetFogOfWar SetFogOfWarGraphics SetGrabMouse SetGodMode SetGroupKeys SetHoldClickDelay SetKeyScroll SetLeaveStops SetMaxOpenGLTexture SetMaxSelectable SetMinimapTerrain SetMouseScroll SetMouseScrollSpeedControl SetMouseScrollSpeedDefault SetSpeedBuild SetSpeedTrain SetSpeeds SetTitleScreens SetVideoFullScreen SetVideoResolution

## Intro - Introduction to config functions and variables

General configurations.

## Constants

### Resource type identifiers

These integer constants identify types of resources. They are used as indices in the AlliedUnitRecyclingEfficiency, EnemyUnitRecyclingEfficiency, and UI.Resources tables.

EnergyCost
  The energy resource type.
MagmaCost
  The magma resource type.
MaxCosts
  The total number of different resource types.

## Functions

### DefineDefaultResourceNames("name", ...)

Names the resources in a given order. The engine does not display these names to the user; it uses them in save files only. Consequently, these names should not be localized.

(Although this function is called DefineDefaultResourceNames, there is no mechanism for overriding these "default" names with others.)

name
  Name to give to the resource. There should be two names: first one for EnergyCost, and then one for MagmaCost.
RETURNS
  Nothing

#### Example

    -- Define Resource names
    DefineDefaultResourceNames(
      "energy", "magma")

### DefineSprites({tag = value, ...}, ...)

Define sprites to be shown for variables. You can define multiple sprites in the same DefineSprites call or each sprite in a separate call; the effect is the same either way.

Tag could be :
Name = "sprite-name"
  name of the sprite. This is how the Method parameter of DefineDecorations refers to the sprite.
File = "filename"
  filename containing the sprite
Offset = {x, y}
  offset when drawing the sprite. Positive values move the sprite to the right or down.
Size = {width, height}
  Size of the sprite. The graphic file may contain multiple frames of this size.

#### Example

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

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

Define how to show variables.

Index = variable
  Which variable's value this decoration will show. It can be a predefined variable, or a custom 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.
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. The current engine supports only one method:

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

#### 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. This cancels any previous RightButtonMoves.

RETURNS
  Nothing

#### Example

    RightButtonAttacks()

### RightButtonMoves()

If you prefer fighters are moving by right clicking empty space. This cancels any previous RightButtonAttacks.

RETURNS
  Nothing

#### Example

    RightButtonMoves()

### SavePreferences

Save the user preferences, i.e. the contents of the preferences variable.

RETURNS
  Nothing

#### Example

    SavePreferences()

### SetAllPlayersBuildingLimit(limit)

Set the limit on the number of buildings a player is allowed to have at one time. The engine maintains a separate limit for each player, and this function changes them all to the same value.

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. The engine maintains a separate limit for each player, and this function changes them all to the same value.

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. The engine maintains a separate limit for each player, and this function changes them all to the same value.

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. When enabled, workers can capture low-HP enemy buildings by attacking them. Here, "worker" means the unit is able to repair something (its RepairRange is not zero), and harvesting does not count as attacking.

SetBuildingCapture does not affect the other mechanisms with which units can be captured: the "capture" spell action in DefineSpell, the ChangeUnitsOwner function used in triggers, and the rescuable player types in DefinePlayerType.

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

#### 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 with DefineMissileType.
RETURNS
  Nothing

#### Example

    SetClickMissile("missile-green-cross")

### 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. It must be defined with DefineMissileType and should have Class = "missile-class-hit".
RETURNS
  Nothing

#### Example

    SetDamageMissile("missile-hit")

### SetDoubleClickDelay(delay)

Set the delay of double clicking the mouse.

delay
  The delay in ms.

#### Example

    SetDoubleClickDelay(300)

### SetFogOfWar(boolean)

If true, enable fog of war.

### SetFogOfWarGraphics(graphic)

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

#### Example

      SetFogOfWarGraphics("general/fog.png")

### 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
  true for on, false for off
RETURNS
  Nothing

#### Example

    -- Set God mode on
    SetGodMode(true)

### SetHoldClickDelay(delay)

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

#### Example

    SetHoldClickDelay(1000)

### SetKeyScroll(boolean)

enable/disable keyboard scrolling.

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

number
  The number of units to set the limit to. (must be positive value)
RETURNS
  The limit that was set.

#### Example

    SetMaxSelectable(18)

### SetMinimapTerrain(boolean)

for minimap with/without terrain.

### SetMouseScroll(boolean)

enable/disable mouse scrolling.

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

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

#### Example

    -- Set Speed Scroll to 5
    SetMouseScrollSpeedDefault(5)

### SetSpeedBuild(number)

Decrease the time to build a unit by this factor.

### SetSpeedTrain(number)

Decrease the time to train a unit by this factor.

### SetSpeeds(number)

Set all speeds. This is equivalent to

    SetSpeedBuild(number)
    SetSpeedTrain(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.
StretchImage = boolean
  If true (default), stretch the image so it fills the screen, possibly changing the aspect ratio. If false, display the image in its original resolution in the center of the screen.
Timeout = number
  The number of seconds we should show this title-screen if the user does not dismiss it first. If zero (default), then the timeout is very long.
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"})

### SetVideoFullScreen(boolean)

Sets the video to full screen or windowed mode

boolean
  true or false for full screen
RETURNS
  Nothing

#### Example

    -- Set Fullscreen
    SetVideoFullScreen(true)

### SetVideoResolution(x, y)

Sets the resolution of the video display (in full-screen mode) or the size of the game window (in windowed mode).

The engine tries to support whatever resolution you specify. However, at resolutions smaller than 640x480, some things might not fit on the screen; and at resolutions greater than 1920x1200, background images might not cover everything they should.

x
  Resolution in x.
y
  Resolution in y.
RETURNS
  Nothing

#### Example

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

### SetGroupKeys("0123456789`")

Define the keys to use for selecting groups of units. Those should normally be the digit keys; however, at least the French AZERTY layout requires pressing Shift to get digits, and the engine then might not automatically recognize those keys as digit keys. In such cases, you should use this function to tell the engine what characters the keys generate without Shift.

On Windows, the default setting is reported to work correctly even with an AZERTY keyboard.

On X11 with GNOME 3 and SDL 1.2.15, the default setting works if the first keyboard layout (i.e. first XKB group) uses unshifted digits, even if some other keyboard layout is active.

We hope SetGroupKeys will become unnecessary when the engine is changed to use SDL 1.3 or 2.0. The engine should then be able to recognize the digit keys from the scancodes provided by SDL. This cannot be easily done with SDL 1.2, which may use different scancodes for the same key on different operating systems or different X servers.

There is no GetGroupKeys function. Lua scripts that call SetGroupKeys should also save the new value of the setting in preferences so that the engine will save it to disk.

keys
  The keys to use for selecting groups of units. The string should consist of 11 characters. The first ten characters are for groups 0, 1, 2, ... 9. The last character is for unselecting all groups; typically, this is the key on the left of the 1 key.

#### Example

For french azerty, use :

    SetGroupKeys("à&é\"'(-è_ç²")

## Variables

### AStarFixedUnitCrossingCost = integer

Cost to move over a unit that is standing still. (Must be greater than 3.)

The pathfinder generally computes the total cost of each movement step (whether straight or diagonal) in this way: 1 + (either AStarUnknownTerrainCost or the cost from the map patch) + (possibly AStarFixedUnitCrossingCost or AStarMovingUnitCrossingCost). However, there are exceptions for flying units, and for units that span multiple map fields.

### AStarKnowUnseenTerrain = boolean

Whether the pathfinder treats unknown terrain as visible when calculating paths or not. Setting AStarKnowUnseenTerrain = false 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, set it true.

### AStarMovingUnitCrossingCost = integer

Cost to move over a unit that is moving to somewhere. (Must be greater than 3.)

### AStarUnknownTerrainCost = integer

Extra cost to move on unseen terrain, makes units tend towards known areas when finding paths.

### AlliedUnitRecyclingEfficiency

What percentage of resources you get back when recycling your buildings or other harvestable units of allied players.

The value of this variable is a table. The indices of the table are resource type identifiers, i.e. integers between 0 and MaxCosts-1 (even though indices typically start from 1 in Lua). The values of the table are the percentages.

#### Example

    AlliedUnitRecyclingEfficiency[MagmaCost] = 42

### EnemyUnitRecyclingEfficiency

What percentage of resources you get when recycling enemy buildings.

The value of this variable is a table in the same format as AlliedUnitRecyclingEfficiency.

### Preference

This variable refers to an object that has the following properties: ShowAttackRange ShowReactionRange ShowSightRange ShowOrders

#### Preference.ShowAttackRange = boolean

Whether to show the attack range of the selected unit as a red circle. See the AttackRange variable.

Even if the ShowAttackRange, ShowReactionRange, and ShowSightRange properties are false, the player can display the ranges by holding the left mouse button for a moment. In any case, the game never shows ranges if the player has selected more than one unit.

#### Preference.ShowReactionRange = boolean

Whether to show the reaction range of the selected unit as a blue circle. See the ComputerReactionRange and PersonReactionRange parameters of DefineUnitType.

#### Preference.ShowSightRange = boolean

Whether to show the sight range of the selected unit as a green circle. See the SightRange variable.

#### Preference.ShowOrders = integer

How long to show the orders of selected units on the map, after the player gives an order. Measured in seconds. If this is negative, or the player presses the Shift key, then the engine shows the orders no matter how old they are.

### preferences

This table contains the user preferences that SavePreferences will save. The engine does not otherwise interpret the contents of this table. Instead, when the engine is starting up, a Lua script should read the preferences from this table and pass each preference to the appropriate function so that it takes effect.

All trademarks and copyrights on this page are owned by their respective owners.