Page Comparison

Excerpt
The objects returned by the Players API are enhanced versions of Player objects...

Properties

Property	Settable	Type	Notes	API Version
id		Number	The id of the player	0.1
type		Constant	PLAYER_DATA Note: The constant is backported by the Players API for Warzone 3.1 Beta 10 and earlier, so it will always be available regardless of Warzone version.	0.1
name		String	What is the player's name? If Scavengers faction: `"Scavengers"` On Warzone 3.1: the name of the colour associated with the player. On Warzone 3.2: the name of the player taken from their JS API Player object.	0.1
isAI		Boolean Undefined	Is the player an AI? On Warzone 3.1: `true` – the player is an AI or Scavenger faction `false` – the player is human `undefined` – could be human or AI (unable to disambiguate) On Warzone 3.2: `true` – the player is an AI or Scavenger faction `false` – the player is human	0.1
isScavenger		Boolean	Is the player the Scavengers faction? `true` – the player is Scavenger faction `false` – the player is not Scavenger faction	0.1
isHuman		Boolean Undefined	Is the player human? On Warzone 3.1: `true` – the player is human `false` – the player is an AI or Scavenger faction `undefined` – could be AI or human (unable to disambiguate) On Warzone 3.2: `true` – the player is human `false` – the player is an AI or Scavenger faction	0.1
isHost		Boolean	Is the player the game host? `true` – yes, they are the game host `false` – no	0.1
isVacant		Boolean	Is the player slot vacant? `true` – yes, this player slot is empty `false` – no, the player slot is occupied A player is considered vacant if they are not alive when the Players API initialises (either at the start of a new game, or when loading a saved game).	0.1
difficulty		Constant	What Difficulty Level is the player? `EASY` – cannon fodder `MEDIUM` – keep an eye on them `HARD` – be afraid `INSANE` – be very afraid Note: Confirmed human players will have a difficulty of `HARD`, ambiguous human players will have a difficulty of `MEDIUM`.	0.1
colour		Object	An object describing the colour associated with the player – it has two properties: `id` – the numeric colour index `name` – a string containing the canonical name of the colour See Colour Palette for possible values of each property. You can use _(player.colour.name) to localise the colour name.	0.1
team		Object	An object describing the team the player is in – it has two properties: `id` – the numeric team ID `name` – the alphabet letter, in uppercase, associated with the team ID The Scavenger faction has a custom team defined: `id` == "18" `name` == "S" The team is always specified, regardless of alliancesType mode: in ALLIANCES_TEAMS mode, multiple players can be in the same team in ALLIANCES and NO_ALLIANCES modes, each player has their own unique team Note: Maps can specify defaults for teams, see map.ini for details.	0.1
isAlly	3.1 3.2+	Boolean	Is the player an ally of the script player (me)? `true` – yes, they are our ally `false` – no, they are an enemy On Warzone 3.2 and above, you can set this value, for example: `Players[3].isAlly = false;` will make player 3 an enemy.	1.0
isEnemy	3.1 3.2+	Boolean	Is the player an enemy of the script player (me)? `true`– yes, they are an enemy `false`– no, they are not an enemy On Warzone 3.2 and above, you can set this value, for example: `Players[3].isEnemy = false;` will make player 3 an ally	1.0
isAlive		Boolean	Is the player "Alive" according to game rules? `true` – yes, they are alive `false` – no	0.1
position		Number Undefined	What map position did the player start in? `<number>` – the position number, which can be cross-referenced with startPositions array to find the x,y co-ordinates of the position. `undefined` – Scavengers don't have a specific start position and will often have multiple bases on the map	0.1
isSelected		Boolean	Has the localhost human player selected this player? `true` – yes `false` – no For more information, see selectedPlayer.	0.1

Where do the properties get defined?

Most of the properties are defined when a new game is started:

Multiplayer and skirmish games: The game set-up screen
Challenge Games: The .ini file associated with the challenge, and optionally some further customisation via the game set-up screen
Campaign: <not sure!>
Tutorial: <not sure!>
Fast Play: <not sure!>

Other properties, such as .isAlly, .isAlive and .isSelected, can change during the game. The values of such properties will update automatically to reflect the current game state.

Working with `.isAI` and `.isHuman` properties

All properties listed above are always defined, even if their value has been defined as undefined. An undefined value will only occur in Warzone 3.1 on the isAI and isHuman properties if the Players API isn't able to disambiguate whether a player is human or AI.

In JavaScript, undefined typecasts to Boolean false so bear this in mind when working with properties that might be defined as being undefined.

When using switch statements, check the undefined case first:

Code Block

theme	RDark
language	javascript
title	Switch statement pattern
linenumbers	true

Players.forEach(function(player, id) {
	switch (player.isHuman) {
		case undefined: {
			// Could be human or AI
			// Players API wasn't able to disambiguate
			break;
		}
		case false: {
			// they are definitely not human
			break;
		}
		case true: {
			// they are definitely human
			break;
		}
	}
});

When using comparison operators, use strict equality checks:

Code Block

theme	RDark
language	javascript
title	Comparison operators -- use with care
linenumbers	true

Players.forEach(function(player, id) {
	// Using !, == or != is unreliable
	// For example, we can't be certain a non-human player is an AI...
	if (!player.isHuman || player.isHuman == false || player.isHuman != true) {
		// They might still be human!
		// undefined == false
	}
	// So use strict equality checks instead...
	if (player.isHuman === false) {
		// They are definitely not human
		// undefined !== false
	}
});

But its probably better to do something like this:

Code Block

theme	RDark
language	javascript
title	Focus on what is true...
linenumbers	true

Players.forEach(function(player, id) {
	if (player.isHuman) {
		// They are definitely human
	} else if (player.isAI) {
		// They are definitely AI
	} else {
		// Could be human or AI
		// Players API was unable to disambiguate
	}
});

Working with `.colour` and `.team` properties

In addition to the .id and .name properties of the .colour and .team objects, they also have two methods:

.valueOf() – returns the value of the .id property
.toString() – returns the value of the .name property

As such, you can use shortcuts like this:

Code Block

theme	RDark
language	javascript
linenumbers	true

Players.forEach(function(player, id) {
	console("Colour for player #"+id+" is: "+player.colour);
});

In the example above, Javascript will typecast player.colour to a string using its toString() method, thus returning the colour name.

Div

class	box

Availability
Status
colour Green
title Stable

Requires:

Warzone 3.1 or above
Warzone 3.2 recommended
Players API

Div

class	box

Players API

Topics:

Child pages (Children Display)

all	true
depth	all
page	Players API
excerpt	true

Versions Compared

Old Version 23

New Version 24

Key

Properties

Where do the properties get defined?

Working with `.isAI` and `.isHuman` properties

Working with `.colour` and `.team` properties

Availability
Status
colour Green
title Stable

Contents

See also

Players API

Page Comparison

Versions Compared

Old Version 23

New Version 24

Key

Properties

Where do the properties get defined?

Working with .isAI and .isHuman properties

Working with .colour and .team properties

Availability StatuscolourGreentitleStable

Contents

See also

Players API

Working with `.isAI` and `.isHuman` properties

Working with `.colour` and `.team` properties

Availability
Status
colour Green
title Stable