(info) This AI is still in early stages of development.

Players Objects

Owned by Aubergine
Last updated: Dec 01, 2012Version comment
5 min read
The objects returned by the Players API are enhanced versions of Player objects...

 

Properties

PropertySettableTypeNotesAPI Version
id(error)Number

The id of the player.

Note: For the scavenger player, their id will be >= maxPlayers (see scavengerPlayer for more info)

0.1
type(error)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(error)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(error)

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(error)Boolean

Is the player the Scavenger Faction faction?

  • true – the player is Scavenger faction
  • false – the player is not Scavenger faction
0.1
isHuman(error)

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(error)Boolean

Is the player the game host?

  • true – yes, they are the game host
  • false – no
0.1
isVacant(error)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(error)Constant

What Difficulty Level is the player?

Note: Confirmed human players will have a difficulty of HARD, ambiguous human players will have a difficulty of MEDIUM.

0.1
colour(error)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(error)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:

Note: Maps can specify defaults for teams, see <mapname>.ini for details.

 0.1
isAlly

(error) 3.1

(tick) 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

(error) 3.1

(tick) 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(error)Boolean

Is the player "Alive" according to game rules?

  • true – yes, they are alive
  • false – no
0.1
position(error)

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(error)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.

Availability STABLE

Requires:

Contents

Jump to:

See also

Native JS API features:

  • playerData[] – an array of traditional player objects
  • Player object – traditional player object definition
  • me – the player id of the player your script is associated with
  • selectedPlayer – the player the localhost human is currently looking at (can be changed via Debug Menu)
  • difficulty – difficulty level associated with your script
  • startPositions[] – array of player starting positions (excluding scavengers)

Players API

Topics:

  • isPlayerAlive() — A global function that performs a basic, un-cached check to determine if a player is alive.
  • eventTeamRevived() — A global event triggered when a team is revived (one or more of it's players resurrected).
  • eventPlayerDefeated() — A global event triggered when a player is defeated.
  • eventPlayerRevived() — A global event triggered when a player is revived (brought back to life).
  • Modding Players API — The Players API supports modding...
  • isSpectator() — A global function that performs a basic, un-cached check to determine if a player is a spectator based on presence of a Satellite Uplink at the start of the game.
  • Players[] — Main interface to Players API and an array of all players in the game, including Scavengers.
    • Players.alliesAndMe[] — Returns an array of players objects for living allied players, including me.
    • Players.alive[] — Returns an array of players objects for living players.
    • Players.allies[] — Returns an array of players objects for living allied players.
    • Players.refresh() — Rebuilds all Players Objects, use with care!
    • Players.dead[] — Returns an array of players objects for dead players.
    • Players.scavenger — Returns the players object associated with the Scavenger faction, even if Scavengers are disabled.
    • Players.me — Returns the player object associated with your script.
    • Players.enemies[] — Returns an array of players objects for living enemy players.
    • Players.mod() — Extend the Players API and Players Objects with your own features...
  • Players Objects — The objects returned by the Players API are enhanced versions of Player objects...
  • eventTeamDefeated() — A global event triggered when a team is defeated (all it's players defeated).