Players.mod()

Extend the Players API and Players Objects with your own features...

Syntax

Players.mod(key, getter, setter, target, refresh, self);

Parameters

Parameter	Type	Notes	API Version
key	String	The name of the property you want to add. Note: You cannot override existing properties (sorry).	1.0
getter	Variant	The getter function, method, or value to associate with the key.	1.0
setter	Function Null Boolean	The type of this parameter determines what sort of property the key will be: `function` – the key will be a getter/setter (accessor) property `null` – the key will be a getter (read-only accessor) property `false` – the key will be either a method (if getter is a function) or a data property (if getter is not a function) Default: `false` If you want `null`, you have to specify `null` – don't just leave the parameter undefined, because if you do it will default to `false`.	1.0
target	Boolean Function	Defines the target of your mod: `true` – the main Players[] array (useful when adding new filters, etc) `false` – all Players Objects function – when passed a players object, return true to mod it or false to leave it alone Default: `false`	1.0
refresh	Function	An optional function to call should Players.refresh() be invoked. Your refresh function will be invoked after the refresh (so all players objects will be available). Useful if you want to reset or update private variables in closures.	1.0
self	Self Descriptor Object	An optional (but recommended) self descriptor object to associate any error messages generated while modding with your script (eg. adding your script name and version to the start of the error).	1.0

Return values

Value Type Notes API Version

undefined Undefined The mod() method doesn't currently return anything. 1.0

<error>

Error

An error occurred whilst applying the mod.

Most likely causes are:

Invalid parameters or parameter combinations
Trying to overwrite an existing "key"

1.0

Example: Read-only accessors

Read-only getters are probably going to be the most common mod because they keep external code concise and easy to read.

Several examples are shown below illustrating the different approaches to targetting where your mod is applied...

Add a read-only accessor property to the Players array

// add a spectators property to the Players[] array
// will return an array of spectators player objects
Players.mod(
  // key name
  "spectators",
 
  // getter function
  function() {
	// note: see Players.js source for examples of caching the list
    return this.filter(function(player) {
      return player.isSpectator;
    });
  },
 
  // read-only accessor
  null,
 
  // target = main Players[] array
  true
);
 
// Let's use our new accessor:
Players.spectators // an array of spectator players objects

Add a read-only accessor property to all players objects

// add .isMe to all players objects (no target specified)
// will return true if that player is me, otherwise false
Players.mod(
  // key name
  "isMe",
  // getter function
  function() {
    return this.id == me;
  },
 
  // read-only accessor
  null
 
  // target = all players objects (default)
);
 
// Let's use our new accessor:
Players.forEach(function(player) {
  player.isMe // true if player.id == me, otherwise false
});

Add a read-only accessor property to specific players objedcts

var isUSM = false; // cache result in the closure
 
// add .isUltimateScavs only to Scavenger players object
// will return true if Ultimate Scavenger Mod is detected
Players.mod(
  // key name
  "isUltimateScavs",
 
  // getter function
  function() {
    // might take several attempts to spot something USM-like
    // so can't really treat isUSM == false as certain
    if (isUSM) return true;
    // only USM has Cranes...
    return (enumDroid(this.id, DROID_CONSTRUCT).some(function(truck) {
      if (truck.name == "Crane") {
        isUSM = true; // cache that we detected USM
        return true;
      }
    }));
  },
 
  // read-only accessor
  null,
 
  // target = only players objects this function approves
  function(player) {
    return player.isScavenger; // approve if player.isScavenger
  }
);
 

// Let's use our new accessor:
Players.scavenger.isUltimateScavs // true if USM, otherwise false
 
// Other players objects didn't get approved:
Players.me.isUltimateScavs // ReferenceError (property not defined)

Example: Normal accessors

Example: Data properties

Example: Method properties

Availability STABLE

Requires:

Warzone 3.1 or above
Players API

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