Bos Wars Scripting API: Config

Intro - Introduction to config functions and variables

Constants

Resource type identifiers

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

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

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

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

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

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)

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

missile-type

The missile to use, as defined with DefineMissileType.

RETURNS

Nothing

Example

SetClickMissile("missile-green-cross")

SetDamageMissile("missile-type")

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

delay

The delay in ms.

Example

SetDoubleClickDelay(300)

SetFogOfWar(boolean)

SetFogOfWarGraphics(graphic)

Example

  SetFogOfWarGraphics("general/fog.png")

SetGrabMouse(boolean)

SetGodMode(boolean)

boolean

true for on, false for off

RETURNS

Nothing

Example

-- Set God mode on
SetGodMode(true)

SetHoldClickDelay(delay)

Example

SetHoldClickDelay(1000)

SetKeyScroll(boolean)

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)

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)

SetMouseScroll(boolean)

SetMouseScrollSpeedControl(speed)

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)

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)

SetSpeedTrain(number)

SetSpeeds(number)

SetSpeedBuild(number)
SetSpeedTrain(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.

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)

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

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