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.

Syntax

var spectator = isSpectator(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 a spectator	1.0
`false`	Boolean	Indicates the player is not a spectator	1.0
`undefined`	Undefined	The game has been running for more than 5 seconds so no longer able to determine if the player is a spectator or not. For example, a human may have gone in to debug mode and placed a sat uplink... doesn't mean they are a spectator. While there are ways to avoid this ambiguity, they are too crufty to consider.	1.0
<error>	Error	If an invalid player ID is specified, an error will be thrown.	1.0

Notes

The isSpectator() function is not cached and does not do any other validity checks – so it's slower and less reliable than using the .isSpectator property of Players Objects:

Best way to check for spectators...

// .isSpectator uses some tricks and caching to boost performance/accuracy
 
var spectator = Players[playerID].isSpectator; // best way to check

Redefining isSpectator()

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

Defining a custom isPlayerAlive() function

// must be *after* including Define API
 
Define("isSpectator", function isSpectator(playerID) {
  // handle scavenger id gracefully! (see notes below)
 
  // do not use Players API to find out if a player is a spectator...
  // ...because it will call this function to find out!
  
  // return true if spectator, false if not, undefined if not sure
});
 
// 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 when the players objects are being created at the start of the game or refreshed at some later point. So, your function can't use the .isSpectator property of players objects to find out if they are a spectator. Obvious really...

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 a spectator (you should return false!).

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 a spectator if they have a SAT_UPLINK at the start of the game.