Difference between revisions of "Mod:Cookbook"
From Roll20 Wiki
m (→getCleanImgsrc: added med and original sizes.) |
(→Asynchronous Semaphore: fix semaphore for strict more) |
||
Line 67: | Line 67: | ||
This particular implementation of an asynchronous semaphore also lets you supply a context for the callback (set the value of <code>this</code>), as well as pass parameters to the callback. The parameters can be given either in the constructor or in the call to <code>p</code>. (Parameters in <code>p</code> take precedence over parameters in the constructor.) | This particular implementation of an asynchronous semaphore also lets you supply a context for the callback (set the value of <code>this</code>), as well as pass parameters to the callback. The parameters can be given either in the constructor or in the call to <code>p</code>. (Parameters in <code>p</code> take precedence over parameters in the constructor.) | ||
<pre data-language="javascript">function Semaphore(callback, initial, context) { | <pre data-language="javascript">function Semaphore(callback, initial, context) { | ||
+ | var args = (arguments.length === 1 ? [arguments[0]] : Array.apply(null, arguments)); | ||
+ | |||
this.lock = parseInt(initial, 10) || 0; | this.lock = parseInt(initial, 10) || 0; | ||
this.callback = callback; | this.callback = callback; | ||
this.context = context || callback; | this.context = context || callback; | ||
− | this.args = | + | this.args = args.slice(3); |
} | } | ||
Semaphore.prototype = { | Semaphore.prototype = { |
Revision as of 06:21, 1 February 2016
Roll20 Mod
Use Mods
- Use & Install
- Mod:Script Index & Suggestions
- Short Community Scripts
- Meta Scripts
- User Documentation
- Mod Scripts(Forum)
- Mod Update 2024🆕
- Macro Guide
Mod Development
Reference
- Objects
- Events
- Chat Events & Functions
- Utility Functions
- Function
- Roll20 object
- Token Markers
- Sandbox Model
- Debugging
Cookbook
The following are not full scripts. They are meant to be stitched together along with business logic to assist in the creation of full scripts, not create scripts on their own.
Contents |
Revealing Module Pattern
The Module Pattern emulates the concept of classes from other languages by encapsulating private and public members within an object. The Revealing Module Pattern improves upon the Module Pattern by making the syntax more consistent.
var myRevealingModule = myRevealingModule || (function() { var privateVar = 'This variable is private', publicVar = 'This variable is public'; function privateFunction() { log(privateVar); } function publicSet(text) { privateVar = text; } function publicGet() { privateFunction(); } return { setFunc: publicSet, myVar: publicVar, getFunc: publicGet }; }()); log(myRevealingModule.getFunc()); // "This variable is private" myRevealingModule.setFunc('But I can change its value'); log(myRevealingModule.getFunc()); // "But I can change its value" log(myRevealingModule.myVar); // "This variable is public" myRevealingModule.myVar = 'So I can change it all I want'; log(myRevealingModule.myVar); // "So I can change it all I want"
Memoization
Memoization is an optimization technique which stores the result for a given input, allowing the same output to be produced without computing it twice. This is especially useful in expensive computations. Of course, if it is rare that your function will receive the same input, memoization will be of limited utility while the storage requirements for it continue to grow.
var factorialCache = {}; function factorial(n) { var x; n = parseInt(n || 0); if (n < 0) { throw 'Factorials of negative numbers are not well-defined'; } if (n === 0) { return 1; } else if (factorialCache[n]) { return factorialCache[n]; } x = factorial(n - 1) * n; factorialCache[n] = x; return x; }
In a Roll20 API script, the cached values could potentially be stored in state
, which will persist between game sessions. If you have a large number of potential inputs, however, be aware that Roll20 may throttle your use of state
.
Asynchronous Semaphore
An asynchronous semaphore allows you to fire a callback method after a set of asynchronous operations (such as calls to sendChat) have completed. While you can't guarantee what order the operations will complete in, you can guarantee that all of them have completed when the semaphore's callback fires.
When using a semaphore, call v()
prior to calling each asynchronous operation, and call p()
as the last statement of each asynchronous operation. If the number of operations you're going to perform is known ahead of time, you can also supply that number to the semaphore constructor and omit the calls to v
.
This particular implementation of an asynchronous semaphore also lets you supply a context for the callback (set the value of this
), as well as pass parameters to the callback. The parameters can be given either in the constructor or in the call to p
. (Parameters in p
take precedence over parameters in the constructor.)
function Semaphore(callback, initial, context) { var args = (arguments.length === 1 ? [arguments[0]] : Array.apply(null, arguments)); this.lock = parseInt(initial, 10) || 0; this.callback = callback; this.context = context || callback; this.args = args.slice(3); } Semaphore.prototype = { v: function() { this.lock++; }, p: function() { var parameters; this.lock--; if (this.lock === 0 && this.callback) { // allow sem.p(arg1, arg2, ...) to override args passed to Semaphore constructor if (arguments.length > 0) { parameters = arguments; } else { parameters = this.args; } this.callback.apply(this.context, parameters); } } };
Example of use:
var sem = new Semaphore(function(lastAsync) { log(lastAsync + ' completed last'); log(this); }, 2, { foo: 'bar', fizz: 'buzz' }, 'Sir not appearing in this callback'); sendChat('', '/roll d20', function(ops) { log('Executing first sendChat'); sem.p('First sendChat call'); }); sendChat('', '/roll d20', function(ops) { log('Executing second sendChat'); sem.p('Second sendChat call'); });
Example output:
"Executing second sendChat" "Executing first sendChat" "First sendChat call completed last" { foo: "bar", fizz: "buzz" }
Handouts & Characters
Creating a Handout
Because of the way that Handout text blocks are handled, creating a Handout object needs to be done in two steps: First create the object, then set the text blocks:
//Create a new Handout available to all players var handout = createObj("handout", { name: "The name of the handout", inplayerjournals: "all", archived: false }); handout.set('notes', 'Notes need to be set after the handout is created.'); handout.set('gmnotes', 'GM notes also need to be set after the handout is created.');
Handling Encoding
The text blocks in Handouts (Notes and GM Notes) and Characters (Bio and GM Notes) are that are set through the User Interface are stored in x-www-form-urlencoded
format. You can recognize this by the sequence of %## codes throughout the text:
"Erik%20%28Viking%2BScientist%29%20%5BFighter%3A%203%2C%20Wizard%3A%202%5D"
This text can be sent to the chat and will be translated by the browser, but if you need to make changes to the text, you might want to deal with it as it was entered:
"Erik (Viking+Scientist) [Fighter: 3, Wizard: 2]"
You can decode the encoded text with the following function:
var decodeUrlEncoding = function(t){ return t.replace( /%([0-9A-Fa-f]{1,2})/g, function(f,n){ return String.fromCharCode(parseInt(n,16)); } ); }
Utility Functions
Utility functions complete common tasks that you may want to use throughout many scripts. If you place a function at the outermost scope of a script tab, that function should be available to all of your scripts, reducing your overhead. Below is a selection of such functions.
getCleanImgsrc
Dependencies: None
Given an image URL taken from a token or other resource, get a clean version of it that can be used to create a token via the API, or undefined
if it cannot be created by the API.
var getCleanImgsrc = function (imgsrc) { var parts = imgsrc.match(/(.*\/images\/.*)(thumb|med|original|max)(.*)$/); if(parts) { return parts[1]+'thumb'+parts[3]; } return; };
Note: The API is only capable of creating images whose source is located in a user library. The imgsrc
must also be the thumb version of the image.
getSenderForName
Dependencies: None
Given a string name, this function will return a string appropriate for the first parameter of sendChat. If there is a character that shares a name with a player, the player will be used. You may also pass an options
object, which is structured identically to the options
parameter of findObjs.
function getSenderForName(name, options) { var character = findObjs({ type: 'character', name: name }, options)[0], player = findObjs({ type: 'player', displayname: name.lastIndexOf(' (GM)') === name.length - 5 ? name.substring(0, name.length - 5) : name }, options)[0]; if (player) { return 'player|' + player.id; } if (character) { return 'character|' + character.id; } return name; }
getWhisperTarget
Dependencies: levenshteinDistance
Given a set of options, this function tries to construct the "/w name " portion of a whisper for a call to sendChat. The options
parameter should contain either player: true
or character: true
and a value for either id
or name
. Players are preferred over characters if both are true, and ids are preferred over names if both have a valid value. If a name is supplied, the player or character with the name closest to the supplied string will be sent the whisper.
options
is technically optional, but if you omit it (or don't supply a combination of player/character + id/name), the function will return an empty string.
function getWhisperTarget(options) { var nameProperty, targets, type; options = options || {}; if (options.player) { nameProperty = 'displayname'; type = 'player'; } else if (options.character) { nameProperty = 'name'; type = 'character'; } else { return ''; } if (options.id) { targets = [getObj(type, options.id)]; if (targets[0]) { return '/w ' + targets[0].get(nameProperty).split(' ')[0] + ' '; } } if (options.name) { // Sort all players or characters (as appropriate) whose name *contains* the supplied name, // then sort them by how close they are to the supplied name. targets = _.sortBy(filterObjs(function(obj) { if (obj.get('type') !== type) return false; return obj.get(nameProperty).indexOf(options.name) >= 0; }), function(obj) { return Math.abs(levenshteinDistance(obj.get(nameProperty), options.name)); }); if (targets[0]) { return '/w ' + targets[0].get(nameProperty).split(' ')[0] + ' '; } } return ''; }
processInlinerolls
This function will scan through msg.content
and replace inline rolls with their total result. This is particularly useful for API commands to which the user may want to pass inline rolls as parameters.
function processInlinerolls(msg) { if (_.has(msg, 'inlinerolls')) { return _.chain(msg.inlinerolls) .reduce(function(previous, current, index) { previous['$[[' + index + ']]'] = current.results.total || 0; return previous; },{}) .reduce(function(previous, current, index) { return previous.replace(index, current); }, msg.content) .value(); } else { return msg.content; } }
Here is a slightly more complicated version which also handles converting tableItems to their text:
function processInlinerolls(msg) { if(_.has(msg,'inlinerolls')){ return _.chain(msg.inlinerolls) .reduce(function(m,v,k){ var ti=_.reduce(v.results.rolls,function(m2,v2){ if(_.has(v2,'table')){ m2.push(_.reduce(v2.results,function(m3,v3){ m3.push(v3.tableItem.name); return m3; },[]).join(', ')); } return m2; },[]).join(', '); m['$[['+k+']]']= (ti.length && ti) || v.results.total || 0; return m; },{}) .reduce(function(m,v,k){ return m.replace(k,v); },msg.content) .value(); } else { return msg.content; } }
statusmarkersToObject
The inverse of objectToStatusmarkers; transforms a string suitable for use as the value of the statusmarkers
property of a Roll20 token object into a plain old JavaScript object.
Note that a statusmarker string can contain duplicate statusmarkers, while an object cannot contain duplicate properties.
function statusmarkersToObject(stats) { return _.reduce(stats.split(/,/), function(memo, value) { var parts = value.split(/@/), num = parseInt(parts[1] || '0', 10); if (parts[0].length) { memo[parts[0]] = Math.max(num, memo[parts[0]] || 0); } return memo; }, {}); }
objectToStatusmarkers
The inverse of statusmarkersToObject; transforms a plain old JavaScript object into a comma-delimited string suitable for use as the value of the statusmarkers
property of a Roll20 token object.
Note that a statusmarker string can contain duplicate statusmarkers, while an object cannot contain duplicate properties.
function objectToStatusmarkers(obj) { return _.map(obj, function(value, key) { return key === 'dead' || value < 1 || value > 9 ? key : key + '@' + parseInt(value); }) .join(','); }
Underscore.js
Main Page: API:Cookbook/Underscore.js
The Underscore.js website is more of an API reference than a guide to using the library. While useful for looking up what functions are available and what parameters they accept, it doesn't help someone trying to break into using the library's power to its fullest extent.
This article is a stub. |
Collections
Writing scripts often involves doing *something* to a collection of *things*. When we talk about collections, they can either be arrays:
var foo = [0,1,10,"banana"];
or objects: var bar = { one: 1, two: 2, banana: 'fruit' };
. Arrays are indexed by numbers (usually starting from 0 and counting up), objects have properties which can be used for indexes: bar['banana'] === 'fruit'; // true!
. Objects effectively act like associative arrays from other languages.
Sample Data
// Sample Array: var foo = [0,1,10,"banana"]; // Sample Object var bar = { one: 1, two: 2, banana: 'fruit' };
Calling a function with Each Element [ _.each() ]
It's very common to need to perform some operation with each element of a collection. Usually people will use for
loops or similar. Underscore provides _.each(), a way to call a function with each element of a collection as the argument.
_.each(foo, function(element){ log('element is '+element); });
"element is 0" "element is 1" "element is 10" "element is banana"
What makes this so powerful is that the identical code works regardless of whether you are using an array or object:
_.each(bar, function(element){ log('element is '+element); });
"element is 1" "element is 2" "element is fruit"
Functions do not need to be inline. They also receive additional parameters. (See documentation fore even more parameters.):
var logKeyValueMapping = function( value, key ) { log(key + " :: " + value); }; log("An Array:"); _.each(foo, logKeyValueMapping); log("An Object:"); _.each(bar, logKeyValueMapping);
"An Array:" "0 :: 0" "1 :: 1" "2 :: 10" "3 :: banana" "An Object:" "one :: 1" "two :: 2" "banana :: fruit"
Transforming Each Element [ _.map() ]
The next most common thing to do with a collection is to transform all of the contained items into items of another type. Often people might do this by making another collection, then using a for
loop to iterate across the first collection, transforming the value and pushing it into the new container. That's a lot of code that can be simplified with Underscore's _.map(), a way to apply a function across a collection of elements and get a collection of the results. If that sounds similar to _.each(), that's because it is, in fact, it has the same signature.
var res = _.map(foo, function(element){ return 'element is '+element; }); log(res);
"['element is 0','element is 1','element is 10','element is banana']"
The return of _.map() is always an array of the results (see #Converting Collections below for getting objects.) and just like _.each(), the function gets more arguments and can be separately defined.
var getKeyValueMapping = function( value, key ) { return key + " :: " + value; }; log("An Array:"); var resA = _.map(foo, getKeyValueMapping); log(resA); log("An Object:"); var resB_.map(bar, getKeyValueMapping); log(resB);
"An Array:" "['0 :: 0', '1 :: 1', '2 :: 10', '3 :: banana']" "An Object:" "['one :: 1', 'two :: 2', 'banana :: fruit']"