isPlayerAlive()

A global function that performs a basic, un-cached check to determine if a player is alive.

Syntax

var alive = isPlayerAlive(playerID);

Parameters

Parameter	Type	Mandatory	Notes	API Version

Parameter	Type	Mandatory	Notes	API Version
playerID	Number		The ID of the player that is to be checked.	1.0

Return value

Value	Type	Notes	API Version

Value	Type	Notes	API Version
`true`	Boolean	Indicates the player is alive	1.0
`false`	Boolean	Indicates the player is dead	1.0
<error>	Error	If an invalid player ID is specified, an error will be thrown.	1.0

Notes

The isPlayerAlive() function is not cached and does not check to see if a player is a spectator or vacant slot – so it's slower and less reliable than using the .isAlive property of Players Objects:

High-speed way to check if player is alive...

// .isAlive uses some tricks and caching to boost performance..
 
var alive = Players[playerID].isAlive; // much faster way to check

Redefining isPlayerAlive()

You can define a custom isPlayerAlive() function if desired, using the following syntax:

Defining a custom isPlayerAlive() function

// must be *after* including Define API
 
Define("isPlayerAlive", function isPlayerAlive(playerID) {
  // handle scavenger id gracefully! (see notes below)
 
  // do not use Players API to find out if a player is alive...
  // ...because it will call this function to find out!
  
  // return true if alive, false if dead
});
 
// and *before* including Players API

The Players API will use your custom function instead of its own if the function is defined as specified in the code above. That means that the .isAlive property of players objects will call your function, so you can't use those (or Players.alive which relies on them) to find out if a player is alive, duh!

Because the Players API includes a players object for Scavengers, regardless of whether they are enabled or present on the map, your function must handle that scenario gracefully. If (playerID >= maxPlayers) then you're being asked if scavengers are alive.

You can see an example script here:

If no custom function has been defined prior to including the Players API, a default definition is created in accordance with standard game rules: A player is deemed to be living if they have either a FACTORY or a CYBORG_FACTORY or a DROID.