# Bos Wars Scripting API: Game

Stratagus FAQ PREV NEXT LUA Index

AddKeystrokeHelp AddMessage AddObjective AddTip Briefing CenterMap ChangeUnitsOwner CreateUnit DefineBurningBuilding DefineCampaign DefineConstruction DefineEditorUnitTypes DefinePlayerColorIndex DefinePlayerColors DefineRaceNames DefineRanks Diplomacy StratagusMap GetUnitVariable GetCurrentLuaPath Group KillUnit KillUnitAt LibraryPath LoadMap Log MakeUnit NewColors MoveUnit Player RemoveObjective ReplayLog ResetKeystrokeHelp Selection SetDefaultMap SetDiplomacy SetGameName SetGamePaused SetGroupId SetLocalPlayerName SetObjectives SetResourcesHeld SetSharedVision SetUnitVariable ShowMapLocation SharedVision SyncRand Unit

## Intro - Introduction to game functions and variables

Everything around the game.

## Functions

### AddKeystrokeHelp("key", "help")

Add help text in the keystroke help menu.

key
  Name of the key stroke.
help
  Descriptive text telling what the keystroke does.

#### Examples

        AddKeystrokeHelp("+", "- increase game speed")
        AddKeystrokeHelp("Ctrl-T", "- track unit")
        AddKeystrokeHelp("F5", "- game options")
        AddKeystrokeHelp("F10", "- game menu")

### AddMessage(message)

Add a message to be displayed.

message
  Text message to display.

#### Example

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

### AddObjective(objective position)

Add an objective to the scenario objectives text list.

objective
  Objective text.
position
  Optional position (0 offset) to add the objective, default is at the end.

#### Example

        -- Adds the objective text "-Build a barracks" to the end of the objectives
        -- list and adds the objective "-Destroy all enemies" to the first position.
        AddObjective("-Build a barracks")
        AddObjective("-Destroy all enemies", 0)

### AddTip(tip)

Adds a tip. Tips are shown at the start of a level.

tip
  Text of the tip.

#### Example

        AddTip("You can demolish trees and rocks.")

### Briefing

Set the briefing. Type must be "sc" or "wc2". Background and text tags are required.

#### Example

    Briefing("type", "wazoogame",
      "title", "sc",
      "objective", "Kill all aliens on the map.",
      "background", "campaigns/human/interface/introscreen3.png",
      "text", "campaigns/human/level07h.txt",
      "voice", "campaigns/human/level07h-intro1.wav",
      "voice", "campaigns/human/level07h-intro2.wav"
    )

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

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

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

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

### DefineCampaign(ident, "name", campaign-name, [campaign-data])

Define the campaign.

ident
  name identifying the campaign in the scripts.
campaign-name
  name of the campaigned displayed to players.
campaign-data
  TODO.

#### Example

        DefineCampaign()

### DefineConstruction(ident ...)

Defines a construction.
Constructions can specify multiple files and shadow files. Shadows are optional.
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 = {{
        Tileset = tileset,
        File = filename,
        Size = {x, y}}},
      Constructions = {{
        percent = percent,
        file = construction-file,
        frame = frame-number}}
    })

ident
  Unique name of the construction.
tileset
  Name of tileset or default to use with any tileset.
filename
  Path of the graphic.
percent
  Percentage of construction complete.
construction-file
  Can be construction or main, specifies which image should be displayed.
frame-number
  Specfies which frame number to display.

#### Example

        -- Defines construction-land with different graphics for summer and winter
        -- tilesets.  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= {{
                    Tileset = "desert",
                    File = "neutral/buildings/land_construction_site.png",
                    Size = {64, 64}},{
                    Tileset = "winter",
                    File = "tilesets/winter/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}}
        })

### DefineEditorUnitTypes({unit1, unit2, ...})

Creates a sorted list of unit-types for the editor. This is only a temporary hack for better sorted units.

unit
  identifier of the unit.

#### Example

    DefineEditorUnitTypes({
       "unit-vault",
       "unit-apcs",
       "unit-medic",
       "unit-bazoo",
       "unit-assault",
       "unit-grenadier",
       "unit-camp",
       "unit-hosp"
    })

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

### DefineRaceNames("race", {...}, "race", {...}, ... )

Define the race names.

    DefineRaceNames(
      "race", {
        "name", "race-name",
        "display", "race-display-name"
        ["visible"])
      ["race", {...}] ...)

race-name
  Internal race name used by other ccl functions.
race-display-name
  Name of the race that gets displayed to the user.
visible
  If specified the race will be visible in the race menus.

#### Example

        -- Defines the elites and neutral races.  The neutral race is
        -- not visible in the race menus.
        DefineRaceNames(
            "race", {
                    "race", 0,
                    "name", "elites",
                    "display", "Elites",
                    "visible"},
            "race", {
                    "race", 1,
                    "name", "neutral",
                    "display", "Neutral"}
        )

### DefineRanks( race '(score rank [score rank] ...))

Define ranks for a race.

race
  The race to define the ranks for.
score
  If the player's score is greater than or equal to this number then the rank is displayed. Scores are expected to be sorted in increasing order.
rank
  The rank that gets displayed.

#### Example

        -- Defines the ranks for the alliance race.
        DefineRanks("alliance", {
           0, "Pathetic",
           3000, "Not Bad",
           10000, Great
        })

### Diplomacy(state, enemy)

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

See SetDiplomacy for more details.

### StratagusMap()

Needed to load/save games.

#### Example

    StratagusMap(
      "version", "2.1.0",
      "description", "big brazilian forest",
      "the-map", {
      "terrain", {"tileset-desert", "desert"},
      "size", {128, 128},
      "fog-of-war",
      "filename", "maps/braza.pud",
      "map-fields", {
      -- 0
      {125, 125, "land", "block", "wood",},   {125, 125, "land", "block", "wood",},
      {125, 125, "land", "block", "wood",},   {125, 125, "land", "block", "wood",},
      {125, 125, "land", "block", "wood",},   {125, 125, "land", "block", "wood",},
      {125, 125, "land", "block", "wood",},   {125, 125, "explored", 1, "land", "block", "wood",},
      {125, 125, "explored", 1, "land", "block", "wood",}
      .....
    }})

### GetCurrentLuaPath()

Returns the path of the currenly interpreted lua script.

#### Examples

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

### 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 .. 16     Player number
      "any"        Matches any player
      "all"        All players (Not used)
      "this"       Player on the local computer, Human player in the campaign.

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

#### Example

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

### LibraryPath()

Returns the Stratagus library path. The Stratagus 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/")

### LoadMap(map)

Load a map using any of the supported formats.

map
  Name of the map to load.

#### Example

        -- Loads the map.
        LoadMap("campaigns/human/level01h.pud")

### Log()

Parse a log entry. Used in replay games.

#### Example

        Log({ GameCycle = 10420, UnitNumber = 252, UnitIdent = "unit-assault",
           Action = "move", Flush = 1, PosX = 113, PosY = 104, SyncRandSeed = 614148735 })

### MakeUnit(unittype, player)

Create a unit which can later be placed on the map with PlaceUnit.

unittype
  type of unit to create.
player
  player number for who the unit is created.
RETURNS
  The slot number of the created unit.

#### Example

        unit = MakeUnit("unit-assault", 0)

### 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})

### Player()

Used when loading games.

#### Example

    Player(0,
      "name", "feb",
      "type", "person", "race", "elites", "ai", 0,
      "team", 2, "enemy", "_X______________", "allied", "________________",
      "shared-vision", "________________",
      "start", {0, 0},
      "resources", {"time", 0, "titanium", 2100, "crystal", 1000,},
      "last-resources", {"time", 0, "titanium", 2100, "crystal", 1000,},
      "incomes", {"time", 0, "titanium", 100, "crystal", 100,},
      "revenue", {"time", 0, "titanium", 0, "crystal", 0,},
      "ai-disabled",
     "supply", 1575, "unit-limit", 200, "building-limit", 200, "total-unit-limit", 400,
      "score", 0,
      "total-units", 16,
      "total-buildings", 16,
      "total-resources", {0, 100, 0, 0, 0, 0, 0,},
      "total-razings", 0,
      "total-kills", 0,
      "color", { 160, 0, 0 },
      "timers", {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,}
    )

### RemoveObjective(position)

Remove an objective from the scenario objectives text list.

position
  Position (0 offset) to remove from the objectives list.

#### Example

        -- Remove the first objective from the objectives list.
        RemoveObjective(0)

### ReplayLog()

Used in replay games.

#### Example

    ReplayLog( {
      Comment1 = "Generated by Stratagus Version 2.1",
      Comment2 = "Visit http://Stratagus.Org for more information",
      Comment3 = "$Id: game.html 9000 2007-07-07 20:30:01Z jim4 $",
      Date = "Wed Jul 21 16:22:17 2004",
      Map = "big",
      MapPath = "maps/braza.pud",
      MapId = 4047425872,
      Type = 1,
      Race = -1,
      LocalPlayer = 0,
      Players = {
            { Race = 0, Team = 0, Type = 0 },
            { Race = 0, Team = 0, Type = 0 },
            { Race = 0, Team = 0, Type = 0 },
            { Race = 0, Team = 0, Type = 0 },
            { Race = 0, Team = 0, Type = 0 },
            { Race = 0, Team = 0, Type = 0 },
            { Race = 0, Team = 0, Type = 0 },
            { Race = 0, Team = 0, Type = 0 },
            { Race = 0, Team = 0, Type = 0 },
            { Race = 0, Team = 0, Type = 0 },
            { Race = 0, Team = 0, Type = 0 },
            { Race = 0, Team = 0, Type = 0 },
            { Race = 0, Team = 0, Type = 0 },
            { Race = 0, Team = 0, Type = 0 },
            { Race = 0, Team = 0, Type = 0 },
            { Race = 0, Team = 0, Type = 0 }
      },
      Resource = -1,
      NumUnits = -1,
      TileSet = -1,
      NoFow = 0,
      RevealMap = 0,
      GameType = -1,
      Opponents = -1,
      Engine = { 2, 1, 0 },
      Network = { 0, 9, 2 }
    } )

### ResetKeystrokeHelp()

Clear all keystroke help menu.

#### Example

        ResetKeystrokeHelp()

### Selection(numselected, unit0, ...)

Define the current selection.

numselected
  How many units are selected.
unitX
  slot number of the unit to add in the selection.

#### Example

        Selection(1, 0)

### SetDefaultMap(path)

Set the default map path.

path
  Path to the map.

#### Example

        -- Sets the default map to "puds/default.pud".
        SetDefaultMap("puds/default.pud")

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

### SetGameName("name")

Sets the name of the game so savegames, maps, settings and logs can be set differently for different games used.

"name"
  The name the game has for loading and saving files

#### Example

        -- Set Name to bos, ~/.stratagus/bos is location of files
    	SetGameName("bos")

### SetGamePaused(paused)

Pause or unpause the game.

paused
  true for paused, false for unpaused.

#### Example

        -- Pauses the game.
        SetGamePaused(true)

### SetGroupId(id)

Set the current group id. (Needed for load/save).

id
  new group id.

#### Example

        SetGroupId(0)

### SetLocalPlayerName("name")

Sets the name of the player playing on this computer. Also saved in preferences, and a default used when the game is started.

"name"
  The name of the player, limited to 16 characters"

#### Example

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

### SetObjectives(objective [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)

### ShowMapLocation(x, y, radius, cycles, unit)

Show an area on the map for the given player.

x (integer)
  X position on the map to show.
y (integer)
  Y position on the map to show.
radius (integer)
  Radius of vision to show.
cycles (integer)
  The number of game cycles that the area should be shown for
unit (string)
  The unit to use for displaying the sight range. Most properties of the unit will be used in the display, whether they can see cloaked units or not. Square Vision can also be achived by creating a large unit, say 10x10 and specifying the radius to be 1

#### Example

        -- Show an area of 6 tiles around location (10,10) for 500 cycles using 'unit-revealer.
        ShowMapLocation(10, 10, 6, 500, "unit-revealer")

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

### Unit()

Needed to save/load games.

#### Example

    Unit(0, "type", "unit-vault", "player", 0,
      "tile", {116, 120}, "refs", 6, "stats", 0,
      "pixel", {0, 0}, "seen-pixel", {0, 0}, "frame", 1, "not-seen", "direction", 0,
      "attacked", 0,
      "current-sight-range", 4, "seen-by-player", "X_______________",
      "seen-destroyed", "________________",
      "seen-state", 0,  "active", "mana", 0, "hp", 1800, "xp", 0, "kills", 0,
      "ttl", 0, "bloodlust", 0, "haste", 0, "slow", 0,
      "invisible", 0, "flame-shield", 0, "unholy-armor", 0,
      "HitPoints", {Value = 1800, Max = 1800, Increase = 0, Enable = true},
      "Mana", {Value = 0, Max = 0, Increase = 0, Enable = false},
      "Transport", {Value = 0, Max = 0, Increase = 0, Enable = true},
      "Research", {Value = 0, Max = 0, Increase = 0, Enable = true},
      "Training", {Value = 0, Max = 0, Increase = 0, Enable = true},
      "UpgradeTo", {Value = 0, Max = 0, Increase = 0, Enable = true},
      "Resource", {Value = 0, Max = 0, Increase = 0, Enable = true},
      "group-id", 0,
      "last-group", 0,
      "value", 0,
      "sub-action", 0, "wait", 2, "state", 2,
      "blink", 0, "rs", 35, "units-boarded-count", 0,"order-count", 1,
      "order-flush", 0,
      "order-total", 4,
            "orders", {
        {"action-still", "flags", 0, "range", 0, "width", 0, "height", 0, "min-range", 0, "tile", {-1, -1},},
        {"action-none", "flags", 0, "range", 0, "width", 0, "height", 0, "min-range", 0, "tile", {0, 0},},
        {"action-none", "flags", 0, "range", 0, "width", 0, "height", 0, "min-range", 0, "tile", {0, 0},},
        {"action-none", "flags", 0, "range", 0, "width", 0, "height", 0, "min-range", 0, "tile", {0, 0},},},
     "saved-order",
        {"action-still", "flags", 0, "range", 0, "width", 0, "height", 0, "min-range", 0, "tile", {-1, -1},},
     "new-order",
        {"action-still", "flags", 0, "range", 0, "width", 0, "height", 0, "min-range", 0, "tile", {-1, -1},}
    )

Last changed: $Id: game.html 9000 2007-07-07 20:30:01Z jim4 $
All trademarks and copyrights on this page are owned by their respective owners.