Players.mod()

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

Syntax

Players.mod(key, value, accessor, 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
value	Variant	The getter function, method, or value to associate with the key.	1.0
accessor	Function Boolean	Should the key be an accessor (getter/setter) or data (value/function) property? `true` – the key is an accessor property, value must be a function (the "getter") `function` – same as `true`, and use this accessor function as the "setter" `false` – the key is a data property, with a read-only value Default: `false`	1.0
target	See notes	Does your mod target Players Objects? `false` – no, it targets the main Players[] array (useful when adding new filters, etc) `true` – yes, it targets all Players Objects within the array a function – yes, it targets specific Players Objects within the array (function passed an object, if it returns true the object is targeted) 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, invalidate caches, etc. Specify `null` or leave undefined if you don't want a refresh function. Default: `null` (no refresh function)	1.0
self	Self Descriptor Object	An optional (but recommended) self descriptor object to associate any error messages generated while modding with your script (your script name and version will be used as the error prefix). Default: Use Players API's self descriptor object	1.0

Return values

Value

Type

Notes

API Version

true

Boolean

The mod() was successfully applied.

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

Examples: Accessor properties

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 .spectators accessor 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",
 
  // value: getter function
  function() {
	// note: see Players.js source for examples of caching the list
    return this.filter(function(player) {
      return player.isSpectator;
    });
  },
 
  // accessor? true = read-only (no setter function)
  true,
 
  // target players objects?: false = target main Players[] array
  false
);
 
// Let's use our new accessor:
Players.spectators // an array of spectator players objects

Add a read-only .isMe accessor 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",
  // value: getter function
  function() {
    return this.id == me;
  },
 
  // accessor? true = read-only (no setter function)
  true
 
  // target not specified, so default to all players objects (true)
);
 
// Let's use our new accessor:
Players.forEach(function(player) {
  player.isMe // true if player.id == me, otherwise false
});

Add a read-only .isUSM accessor to only the scavenger players object

var found = false; // cache result in the closure
 
// add .isUSM only to Scavenger players object
// will return true if Ultimate Scavenger Mod is detected
Players.mod(
  // key name
  "isUSM",
 
  // value: getter function
  function() {
    // might take several attempts to spot something USM-like
    // so can't really treat isUSM == false as certain
    if (found) return true;
    // only USM has Cranes...
    return (enumDroid(this.id, DROID_CONSTRUCT).some(function(truck) {
      if (truck.name == "Crane") {
        found = true; // cache that we detected USM
        return true;
      }
    }));
  },
 
  // accessor? true = read-only (no setter function)
  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.isUSM // true if USM, otherwise false
 
// Other players objects didn't get approved:
Players.me.isUSM // ReferenceError (property not defined)

In the previous examples we focussed on adding read-only accessors to different bits of the Players API.

In this next example, we'll add a read-write accessor (getter/setter) and illustrate how to properly encapsulate your mod in a sandbox, complete with dependency checking...

Add a .notes accessor to all players objects

void (function exampleMod() { // sandbox
 
  // self descriptor object
  var self = {
    file: "exampleMod.js",
    ver : 0.1
  };
  // define dependencies
  var dependencies = {
    "Players.js": 1.0 // obviously set to the right version
  }
  // check dependencies available (throws error if not)
  uNeed(self, dependencies); // Util.js
 
  // a place to store some values
  // will be accessible to all functions in this sandbox,
  // even when they are put in to the Players API
  // (learn about 'closures' if you don't know why)
  var values = {};
  
  // define our getter function
  var getter = function() {
    // 'this' will be the players object the getter is invoked on
    return values[this.id];
  }
 
  // define or setter function
  var setter = function(value) {
    values[this.id] = value;
  }
 
  // define a refresh function that clears all our notes
  // this will be invoked after Players.refresh() is invoked
  // so we can safely use Players.forEach()
  var refresh = function() {
    Players.forEach(function(player) {
      values[player.id] = null;
    });
  }
 
  // initialise our values (set them all to null)
  refresh();
 
  // mod the players API (will throw an error if something is wrong)
  Players.mod(
    "notes", // key name
    getter,  // value: getter function
    setter,  // accessor? yes, with setter function
    true,    // target = all players objects
    refresh, // refresh function
    self     // self descriptor
  );
 
  // indicate our mod is available
  uProvide(self);
 
})(); // close sandbox and run it
 
// Let's use our new accessor:
Players.me.notes = "This is me!!";
 
console(Players.me.notes); // "This is me!!"
 
Players.refresh(); // invokes our refresh function, so all notes cleared
 
console(Players.me.notes); // "null"
 
// Optionally we can check the mod was applied before using the 'notes' accessor:
if (uHas("exampleMod.js")) {
  // this code only runs if the mod was applied
  Players.scavenger.notes = "Those pesky marauders!";
  console(Players.scavenger.notes); // "Those pesky marauders!"
}

The Check.has() function, part of Util API, allows other scripts to check if your mod is available.

Examples: Data properties

Data properties are read-only values added on to the desired target. Let's keep this example simple:

Add a .fish data property to Players[] array

Players.mod(
  "fish",    // key
  "haddock", // value
  false,     // accessor? no, it's a data property
  false      // target = Players[]
);
 
console(Players.fish);   // "haddock"
Players.fish = "kipper"; // .fish is read-only
console(Players.fish);   // still "haddock"

Method properties are just data properties where the value is a function...

Add a .fish() method to Players[] array

var method = function() {
  // note: 'this' in a method = object the method is added to
  return "halibut";
}
 
Players.mod(
  "fish", // key
  method, // value: function
  false,  // accessor? no, it's a data property
  false   // target = Players[]
);
 
console( Players.fish   ); // "function" because treated as a data property
console( Players.fish() ); // "halibut"  because invoked as a method() property