Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
Excerpt |
---|
Extend the Players API and Players Objects with your own features... |
Syntax
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
Players.mod(key, gettervalue, setteraccessor, target, refresh, self); |
Parameters
Parameter | Type | Mandatory | Notes | API Version | |||
---|---|---|---|---|---|---|---|
key | String | The name of the property you want to add. Note: You cannot override existing properties (sorry). | 1.0 | ||||
gettervalue | Variant | The getter function, method, or value to associate with the key. | 1.0 | ||||
setteraccessor | Function Null Boolean | The type of this parameter determines what sort of property Should the key will be: function – the key will be a be an accessor (getter/setter (accessor) or data (value/function) property?
Default: If you want | 1.0 | target | 1.0 | ||
target | See notes | Defines the target of Does your mod : true – target Players Objects?
Default: | 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 Default: | 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. addingyour script name and version to the start ofwill be used as the error prefix). 1Default: Use Players API's self descriptor object | 1.0 |
Return values
Value | Type | Notes | API Version |
---|---|---|---|
undefined true | UndefinedBoolean | The mod() method doesn't currently return anythingwas successfully applied. | 1.0 |
<error> | Error | An error occurred whilst applying the mod. Most likely causes are:
| 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...
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
// 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 accessor (no setter function) nulltrue, // target = main players objects?: false = target main Players[] array truefalse ); // Let's use our new accessor: Players.spectators // an array of spectator players objects |
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
// 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 accessor (no setter function) nulltrue // target = not specified, so default to all players objects (defaulttrue) ); // Let's use our new accessor: Players.forEach(function(player) { player.isMe // true if player.id == me, otherwise false }); |
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
var isUSMfound = false; // cache result in the closure // add .isUltimateScavsisUSM only to Scavenger players object // will return true if Ultimate Scavenger Mod is detected Players.mod( // key name "isUltimateScavsisUSM", // value: getter function function() { // might take several attempts to spot something USM-like // so can't really treat isUSM == false as certain if (isUSMfound) return true; // only USM has Cranes... return (enumDroid(this.id, DROID_CONSTRUCT).some(function(truck) { if (truck.name == "Crane") { isUSMfound = true; // cache that we detected USM return true; } })); }, // accessor? true = read-only accessor (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.isUltimateScavsisUSM // true if USM, otherwise false // Other players objects didn't get approved: Players.me.isUltimateScavsisUSM // 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) but focus on and illustrate how to properly encapsulate your mod in a sandbox, complete with dependency checking...
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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 = {}; // initialisedefine our values (set them all to null) Players.forEach(function(playergetter function var getter = function() { values[player.id] = null; }); // 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 var// refresh so we can safely use Players.forEach() var refresh = function() { Object.keys(values)Players.forEach(function(keyplayer) { values[keyplayer.id] = null; }); } // modinitialise theour players APIvalues (willset throwthem anall errorto ifnull) something is wrongrefresh(); // 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 false 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(); // willinvokes clearour allrefresh ourfunction, notesso dueall tonotes refreshcleared function 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 uHasCheck.has() function, part of Util API, allows other scripts to check if your mod is available.
ExampleExamples: Data properties
Data properties are read-only values added on to the desired target. Let's keep this example simple:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
Players.mod( "fish", // key "haddock", // getter = the property value false, // setteraccessor? = treat asno, it's a data property truefalse // target = Players[] ); console(Players.fish); // "haddock" Players.fish = "kipper"; // .fish is read-only console(Players.fish); // still "haddock" |
Method properties
Basically the same as a data property, only our data is a function so we end up defining a methodare just data properties where the value is a function...
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
var gettermethod = function() { // note: 'this' in a method = object the method is added to return "halibut"; } Players.mod( "fish", // key gettermethod, // gettervalue: =function the method we're adding false, // setteraccessor? = treat asno, it's a data property true false // target = Players[] ); console( Players.fish ); // "function" because treated as a data property console( Players.fish() ); // "halibut" because invoked as a method() property |
Div | ||||||
---|---|---|---|---|---|---|
| ||||||
Availability
Requires:
|
Div | ||||
---|---|---|---|---|
| ||||
ContentsJump to:
|
Div | ||
---|---|---|
| ||
See alsoRelated articles:
|
Div | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
Players APITopics:
|
...