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 Log MakeUnit NewColors MoveUnit Player RemoveObjective ReplayLog ResetKeystrokeHelp Selection SetDefaultMap SetDiplomacy SetGameName SetGamePaused SetGroupId SetLocalPlayerName SetObjectives SetResourcesHeld SetSharedVision SetUnitVariable 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/")

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

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

All trademarks and copyrights on this page are owned by their respective owners.
(c) 2002-2007 by The Bos Wars Project