Players Objects

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. Note: For the scavenger player, their id will be >= maxPlayers (see scavengerPlayer for more info)	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 Scavenger Faction 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 The Scavenger faction has a custom colour defined: `.id` == -`1` `.name` == "`Random"` 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 <mapname>.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. If the value cannot be set for some reason, eg. on Warzone 3.1 or if alliancesType != ALLIANCES, the value will remain unchanged.	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. If the value cannot be set for some reason, eg. on Warzone 3.1 or if alliancesType != ALLIANCES, the value will remain unchanged.	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. You'll need to use the strict equality operators (=== and !==) to avoid confusion between false and undefined...

Comparison operators -- use with care

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

Switch statements automatically use strict equality, so you can do something like this:

Switch statement pattern

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

But its probably better to do something like this:

Focus on what is 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:

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.