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
playerID	Number		The ID of the player that is to be checked.	1.0

Return value

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: Define.isSpectator.js

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.

Availability STABLE

Requires:

Warzone 3.1 or above
Define API – if defining your own function
Players API – if using the default function or faster .isSpectator property of Players Objects

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