# Bos Wars Scripting API: Game

Bos Wars FAQ PREV NEXT LUA Index

AddMessage AddObjective CenterMap ChangeUnitsOwner CreateUnit DefineBurningBuilding DefineConstruction DefinePlayerColorIndex DefinePlayerColors Diplomacy GetLocalPlayerName GetUnitVariable GetCurrentLuaPath Group KillUnit KillUnitAt LibraryPath NewColors MoveUnit SetDiplomacy SetGamePaused SetLocalPlayerName SetObjectives SetResourcesHeld SetSharedVision SetUnitVariable SharedVision SyncRand

## Intro - Introduction to game functions and variables

Everything around the game.

## Functions

### AddMessage(message)

Add a message to be displayed.

message
  Text message to display.

#### Example

    -- Adds the message.
    AddMessage("This is a message")

### AddObjective(objective)

Add an objective to the end of the scenario objectives text list.

objective
  Objective text.

#### Example

    -- Adds the objectives "-Build a barracks" and "-Destroy all enemies"
    -- to the end of the objectives list.
    AddObjective("-Build a barracks")
    AddObjective("-Destroy all enemies")

### CenterMap(x, y)

Center the current viewport at a certain location.

x
  X tile location.
y
  Y tile location.

#### Example

    -- Centers the current viewport at tile 17x40.
    CenterMap(17, 40)

### ChangeUnitsOwner({x1, y1}, {x2, y2}, oldplayer, newplayer [,unittype])

Changes the owner of a group of units from one player to another.

{x1, y1}
  Upper left location for tilebox to check for units within.
{x2, y2}
  Lower right location for tilebox to check for units within.
oldplayer
  The player that currently owns the units.
newplayer
  The player that the units should now be owned by.
unittype
  Optional; change only units of this type.

      "unit-name"  Unit type of this name
      "any"        Matches any unit type (default if omitted)
      "all"        All units (sum of units and buildings)
      "units"      All non building units
      "building"   All building units

  If you want some other set of unit types, then you just need to call this function once for each unit type.

#### Example

    -- Changes the owner to player 2 for all units owned by player 3,
    -- that are located in the area (0,0)-(10,10).
    ChangeUnitsOwner({0, 0}, {10, 10}, 3, 2)

    -- As above, but affects rocket tanks only.
    ChangeUnitsOwner({0, 0}, {10, 10}, 3, 2, "unit-rtank")

### CreateUnit(type, player, {x, y})

Create a unit at a location. If the location is occupied, the unit will be placed in the closest available spot.

type
  Type of unit to create.
player
  Player number that owns the unit.
x
  X map tile location.
y
  Y map tile location.
RETURNS
  The slot number of the created unit.

#### Example

    -- Creates a footman for player 2 at location 31x34.
    CreateUnit("unit-footman", 2, {31, 34})

### DefineBurningBuilding({"percent", p, "missile", m} ...)

Define the burning animation for buildings. The animation will be laid over the building image.

p
  Hit point percentage.
m
  Fire missile to display.

#### Example

    DefineBurningBuilding(
      {"percent", 0, "missile", "missile-big-fire"},
      {"percent", 50, "missile", "missile-small-fire"},
      {"percent", 75}) -- no missile

### DefineConstruction(ident, {...})

Defines a construction, which controls how the game draws units that are being built. To make use of the construction thus defined, you must also make one or more unit types refer to it; see DefineUnitType.
As the unit nears completion, the game shows the frames of the construction one at a time. This sequence of frames does not repeat. The construction affects only the appearance of the unit, not how long it takes to build. Constructions are not used for units that are being trained rather than built, because those do not appear on the map before they are complete.
The game can load these frames from the graphics files of the unit type or from separate construction-specific files: a primary file and a shadow file. If you omit the shadow file, the unit will not have a shadow in these frames.
The construction frames should be ordered by increasing percentages and the first frame should be 0.

    DefineConstruction(ident, {
      Files = {
        File = filename,
        Size = {x, y}},
      ShadowFile = {
        File = filename,
        Size = {x, y}},
      Constructions = {{
          percent = percent,
          file = construction-file,
          frame = frame-number},
        ...}
    })

ident
  Unique name of the construction. The Construction parameter of DefineUnitType refers to this.
Files = {...}
  The construction-specific graphic file. Needed only if some construction-file is "construction". Although this section is tagged "Files", you cannot specify multiple files.
filename
  Path of the graphic.
x, y
  The size of each frame in the graphic.
ShadowFile = {...}
  The construction-specific shadow graphic file. Needed only if some construction-file is "construction" and you also want shadows for those frames.
percent
  Percentage of construction complete.
construction-file
  Can be "construction" or "main", specifies which image should be displayed.
frame-number
  Specifies which frame number to display.

#### Example

    -- Defines construction-land with a construction-specific graphics file.
    -- Buildings 0-24 percent complete use frame 0 of the construction
    -- image, 25-49 percent complete use frame 1 of the construction image, and 50-99
    -- percent complete use the frame 1 of the main building graphic.
    DefineConstruction("construction-land", {
        Files = {
    	    File = "neutral/buildings/land_construction_site.png",
    	    Size = {64, 64}},
        Constructions = {{
    	    Percent = 0,
    	    File = "construction",
    	    Frame = 0},{
    	    Percent = 25,
    	    File = "construction",
    	    Frame = 1},{
    	    Percent = 50,
    	    File = "main",
    	    Frame = 1}}
    })

### DefinePlayerColorIndex(colorstart, numcolors)

Define the graphic color indexes to be replaced by the player color.

colorstart
  Index of the first color
numcolors
  Total number of colors

#### Example

    DefinePlayerColorIndex(10, 5) -- for indexes 10-14

### DefinePlayerColors({"color", {{R, G, B}, {R, G, B}, {R, G, B}, {R, G, B}}, ...})

Define the player colors. There should be 16 colors defined and 4 shades of each color.

color
  Name of the player color
R, G, B
  Red, green, blue values for each color

#### Example

    DefinePlayerColors({
      "red", {{164, 0, 0}, {124, 0, 0}, {92, 4, 0}, {68, 4, 0}},
      "blue", {...},
      ...
    )

### Diplomacy(state, enemy)

Does the same as SetDiplomacy(currentplayer, state, enemy).

See SetDiplomacy for more details.

### GetCurrentLuaPath()

Returns the path of the currenly interpreted lua script.

#### Examples

    print(GetCurrentLuaPath())
    Load(GetCurrentLuaPath().."unit.lua")

### GetLocalPlayerName()

Returns the name of the player playing on this computer. The name is used in both network games and single-player games. When the engine is starting up, it chooses a default name. Lua scripts can change the name by calling SetLocalPlayerName.

RETURNS
  The name of the local player: either set with SetLocalPlayerName or chosen by the engine.

### GetUnitVariable(unit, VariableName)

Get a unit's mana.

unit
  Unit to get info for.
VariableName
  Name of the variable to get info for.

#### Example

    -- Get mana of the unit (slot #11).
    GetUnitMana(11, "Mana");

### Group(group, quantity, {unit0, unit1, ...})

Create a group of units.

group
  Group number.
quantity
  How much units are in the group.
unitX
  unit slot number.

### KillUnit(unit, player)

Kill a unit.

unit

      "unit-name"  Unit type of this name
      "any"        Matches any unit type
      "all"        All units (sum of units and buildings)
      "units"      All non building units
      "building"   All building units

player

      0 .. 8       Player number
      "any"        Matches any player
      "all"        All players (Not used)
      "this"       Player on the local computer, Human player in the campaign.

RETURNS
  true if it killed one unit; false if there is no matching unit.

#### Example

    -- Kills a peasant of the player on the local computer.
    KillUnit("unit-peasant", "this");

### KillUnitAt(unit, player, quantity, location1, location2)

Kills units at a specific location.

unit

      "unit-name"  Unit type of this name
      "any"        Matches any unit type
      "all"        All units (sum of units and buildings)
      "units"      All non building units
      "building"   All building units

player

      0 .. 16     Player number
      "any"        Matches any player
      "all"        All players (Not used)
      "this"       Player on the local computer, Human player in the campaign.

quantity

      0 ... oo    Number for the quantity

location1

      {x1, y1}    Upper left corner

location2

      {x2, y2}    Lower right corner

RETURNS
  integer: how many units it killed.

#### Example

    -- Kills any units in the rectangle (5,12) to (9,15).
    KillUnitAt("any", "any", 9, {5, 12}, {9, 15});

### LibraryPath()

Returns the Bos Wars library path. The Bos Wars library path points to the game data directory.

#### Example

    path = LibraryPath()

### ListDirectory(path)

Returns a list with all files and subdirectories found in the directory pointed by path. If the given path starts with '~', then the path is relative to the user stratagus preferences directory. The path cannot include any special character.

#### Example

    list = ListDirectory("music/")

### ListFilesInDirectory(path)

Returns a list with all files found in the directory pointed by path. The path is relative to the game directory. If the given path starts with '~', then the path is relative to the stratagus' user preferences directory. The path cannot include any special character.

#### Example

    list = ListFilesInDirectory("music/")

### ListDirsInDirectory(path)

Returns a list with all subdirectories found in the directory pointed by path. The path is relative to the game directory. If the given path starts with '~', then the path is relative to the user stratagus preferences directory. The path cannot include any special character.

#### Example

    list = ListDirsInDirectory("music/")

### NewColors()

Change players colors.

#### Example

    NewColors()

### MoveUnit(unit-slot, {x, y})

Place a unit on map. If the location is occupied, the unit will be placed in the closest available spot.

unit-slot
  slot number of the unit to be placed
x
  X map tile position.
y
  Y map tile position.

#### Example

    MoveUnit(0, {10, 12})

### SetDiplomacy(player, state, enemy)

Alters the diplomacy setting between two players. eg enemy, allied

player
  Player to effect change of diplomacy on.

state
  State of relationship between players ("allied", "enemy", "neutral", "crazy").

enemy
  Other player involved in diplomacy.

#### Example

    -- Sets player 1 to be an enemy of player 0.
    SetDiplomacy(0, "enemy", 1)

### SetGamePaused(paused)

Pause or unpause the game.

paused
  true for paused, false for unpaused.

#### Example

    -- Pauses the game.
    SetGamePaused(true)

### SetLocalPlayerName("name")

Sets the name of the player playing on this computer. Does not save the name in preferences; the caller can do that if desired. Lua scripts can read the name back by calling GetLocalPlayerName.

"name"
  The name of the player, limited to 16 characters.
RETURNS
  Nothing

#### Example

    -- Set Player Name to mr-russ
    SetLocalPlayerName("mr-russ")

### SetObjectives({ objective, ... })

Set the mission objectives. This will overwrite any previous objectives.

objective
  Mission objective text.

#### Example

    -- Sets the mission objectives.
    SetObjectives({"Build 4 farms", "Mine 500 gold"})

### SetSharedVision(player, state, opponent)

Sets shared vision.

player
  Player number to set shared vision.
state
  Use true to turn on shared vision, false to turn off.
opponent
  Player number to change.

#### Example

    -- Sets shared vision for player 0 to on with player 2.
    SetSharedVision(0, true, 2)

### SetResourcesHeld(unit, resources)

Set the amount of resources available in a unit. Mostly used for harvestable resources.

unit
  unit identifier obtained via for example CreateUnit.
resources
  amount of resources held by the unit.

#### Example

    unit = CreateUnit("unit-crystal", {10,45})
    SetResourcesHeld(unit, 2500)

### SetUnitVariable(unit, VariableName, amount)

Set the amount of VariableName of the unit.

unit
  Unit to set the info for.
VariableName
  Variable to set.
amount
  New amount of VariableName for the unit.

#### Example

    --  Set mana of the unit (slot 11)
    SetUnitVariable(12, "Mana", 255)

### SharedVision(state, opponent)

Sets shared vision for the player at the computer.

state
  Use true to turn on shared vision, false to turn off.
opponent
  Player number to change.

#### Example

    -- Sets shared vision on with player number 3.
    SharedVision(true, 3)

### SyncRand(number)

Get a value from the Stratagus syncronized random number generator. Used to allow the AI to make syncronized choices with multiplayer, and during replays.

number
  Number to create random from, eg 10
RETURNS
  the number randomly generated, eg 0-9 for input 10.

#### Example

    if(SyncRand(10) < 5) then
      -- Do this
    else
      -- Do that
    end

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