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.