Hi Jim! For API scripts, all you need to know is vanilla Javascript. API Scripts run in a Node.js based Sandbox, so understanding the difference between writing Javascript in a browser (with a DOM) and writing it in a Node Module would be helpful (there is no DOM in the API). Understanding how event driven software works and asynchronous functions would be a big help. API scripts run on an API server separate from the game and the clients connected to it, so all of your communication will occur though receiving events and responding to them by creating/modifying Roll20 Objects and/or issuing function calls like sendChat(). Here are two small and heavily annotated scripts that you can read through to get an idea what it's like. Drunk Move: Tokens with the overdrive status marker get moved a random direction for half the distance they moved when they are moved. // run this function when the api is fully loaded.
// (like going when the light turns green, instead of one of the yellow ones)
on('ready',function(){
// tells the javascript engine to make certain sloppy coding practices into errors
"use strict";
// starts defining things. first is a distance function
var distance=function(p1,p2) {
// pythagorean theorem for distance between two points
return Math.sqrt(Math.pow(p2[0]-p1[0],2)+Math.pow(p2[1]-p2[1],2));
},
// function to determine how long a move chain was
moveDistance=function(lastMove){
return _.chain(lastMove.split(/,/)) //< break the move string up by commas
.map(parseFloat) //< turn each thing into a number
.groupBy(function(v,k){ //< break up the array into points
return Math.round((k-1)/2);
})
.reduce(function(m,p){ //< walk the points adding the distance between them.
if(m.pp){
m.sum+=distance(m.pp,p);
}
m.pp=p;
return m;
},{
pp:null,
sum:0
})
.value()
.sum; //< return just the sum distance
};
// run this function when graphics (tokens) are changed
on('change:graphic',function(obj,prev){
// setup some variables for later use
var page, move, theta,tprime,lprime;
// determine if we want to affect this object
if( 'objects' === obj.get('layer') /* on the objects layer */
&& -1 !== obj.get('statusmarkers').indexOf('overdrive') /* has the overdrive symbol */
&& (obj.get('top') !== prev.top || obj.get('left') !== prev.left) /* has changed position */
) {
// grab the page object based on the page the token is on (for later use bounding)
page=getObj('page',obj.get('pageid'));
// figure out how far the token moved
move = moveDistance(obj.get('lastmove'));
if(!move){
// if it was just dragged directly, the lastmove field won't give us a distance,
// use the distance between where it is now and where it was instead
move=distance([obj.get('left'),obj.get('top')],[prev.left,prev.top]);
}
// cut move in half. move/=2 is the same as move = move/2
move/=2;
// get a random angle in radians
theta=(randomInteger(360) * (Math.PI/180));
// calculate the new top, bounded by half a unit from the top and bottom edge of the map
tprime = Math.max(35,Math.min((page.get('height')*70)-35,obj.get('top')+move*Math.sin(theta)));
// calculate the new left, bounded by half a unit from the left and right edge of the map
lprime = Math.max(35,Math.min((page.get('width')*70)-35,obj.get('left')+move*Math.cos(theta)));
// set the object's new position
obj.set({
top: tprime,
left: lprime
});
}
});
});
Random FX: select one or more tokens and run the api command !randomfx to cause that token to emit a random fx every 5-15 seconds. // This registers a function to run when the 'ready' event occurs
// 'ready' happens when the API Sandbox has fully loaded all the elements of the current game
// [ <a href="https://wiki.roll20.net/API:Events#Campaign_Event" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Event</a>... ]
on('ready',function(){
// This tells Javascript to enforce certain strict rules when evaluating the code (generally things that avoid errors).
"use strict";
// Setting up variables. These exist in the current function and for all functions defined within it.
// These are in a Javascript Closure, something you may want to read up on.
// [ <a href="https://wiki.roll20.net/API:Events#Campaign_Event" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Event</a>... ]
var affectedTokens={}, //< an object to store tokens that are in the rotation to receive random animations
minSeconds = 5, //< the minimum time to wait before applying another effect
maxSeconds = 15, //< the maximum time to wait before applying another effect
// Arrays of choices for building a random effect
eColor = [ 'acid', 'blood', 'death', 'fire', 'frost', 'holy', 'slime' ],
eType = [ 'bubblingcauldron','burn','burst','explosion','healinglight','holyfire','nova','smokebomb','splatter' ],
// a function that assembles a random effect name
randomEffect=function(){
// _.sample() returns a random subset from a collection. By default, it returns a single value.
// [ <a href="https://wiki.roll20.net/API:Events#Campaign_Event" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Event</a>... ]
//
// This will return a string such as 'burn-acid' or 'nova-frost'
return _.sample(eType)+'-'+_.sample(eColor);
},
// a function that creates a random effect at a particular location (x,y) on a particular page (p)
applyEffect=function(x,y,p){
// spawnFx() creates an effect at a point on a page.
// [ <a href="https://wiki.roll20.net/API:Events#Campaign_Event" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Event</a>... ]
spawnFx(x,y,randomEffect(),p);
};
// This registers a function to run when the 'chat:message' event occurs
// 'chat:message' happens whenever anything is put into the chat box by anyone connected to the game
// [ <a href="https://wiki.roll20.net/API:Events#Campaign_Event" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Event</a>... ]
on('chat:message',function(msg){
// do some checks to make sure we want to run for this message
// 'api' message type is for messages that begin with '!'
// playerIsGM() will insure that only a gm can run this command
// [ <a href="https://wiki.roll20.net/API:Events#Campaign_Event" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Event</a>... ]
//
// .match(/^!randomfx/) checks to make sure the command is the right one.
if('api' === msg.type && playerIsGM(msg.playerid) && msg.content.match(/^!randomfx/) ){
// _.chain() is a powerful functional programming method in underscore.js
// The basic idea is you take a collection as the start of a chain and
// perform various operations on it. The input to an operation is the
// output from the previous and so on.
// [ <a href="https://wiki.roll20.net/API:Events#Campaign_Event" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Event</a>... ]
//
// msg.selected is an array of { _type: <typename> ,_id: <id> } objects which
// describe the currently selected objects.
_.chain(msg.selected)
// .map() takes a collection and call a function on each element, then returns
// an array containing the result of each call. Using .chain(), the first argument
// behind the scenes is the collection in the chain.
// [ <a href="https://wiki.roll20.net/API:Events#Campaign_Event" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Event</a>... ]
//
// msg.selected -> .map() -> all the Roll20 graphics that were selected
.map(function(o){
// This will get the Roll20 graphic associated with the selected id.
// If what was selected wasn't a graphic (a drawing, some text, etc)
// it will return the javascript identifier 'undefined'.
// [ <a href="https://wiki.roll20.net/API:Events#Campaign_Event" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Event</a>... ]
return getObj('graphic',o._id);
})
// .compact() returns the collection it was given without any of the 'falsy'
// entries, things like 'undefined', 'false', 'null', etc. Using .chain(), the argument
// behind the scenes is the collection in the chain.
// [ <a href="https://wiki.roll20.net/API:Events#Campaign_Event" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Event</a>... ]
//
// selected graphics and undefined -> .compact() -> selected graphics
.compact()
// .each() is just like .map(), except what it returns is what it was given.
// Effectively, it gives you the opportunity to do something with each element
// without changing the list. Using .chain(), the first argument
// behind the scenes is the collection in the chain.
// [ <a href="https://wiki.roll20.net/API:Events#Campaign_Event" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Event</a>... ]
//
// selected graphics -> .each() -> selected graphics
.each(function(t){
// Now that we've filtered down the results to just selected graphics, the real work
// starts.
// _.has() is an alias for <object>.hasOwnProperty() which simply takes a given object
// and returns 'true' if it contains the specified property. In this case, I'm using
// the id of the graphic as the property name, effectively treating the affectedTokens
// object as a hash.
// [ <a href="https://wiki.roll20.net/API:Events#Campaign_Event" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Event</a>... ]
if(_.has(affectedTokens,t.id)){
// If affectedTokens has the id in it, it means effects are already happening for
// that token, so I want to remove it from the rotation of things having effects.
// delete <object>[<property name>] removes that property from the object, effectively
// removing this token from the hash.
delete affectedTokens[t.id];
} else {
// If affectedTokens didn't have the id, it means I'm adding it into rotation.
// I set the property for the graphic's id to be true. I considered
// storing an object with some timing information instead of true, which
// is why I made affectedTokens an object instead of a simple array, but
// the implementation went another way.
affectedTokens[t.id]=true;
// This creates another Javascript Closure to capture the id and page number and
// save them for executions of the function I'll be defining within it. Technically,
// the function on each is already a Closure for this function so I probably didn't
// need another one here. I have a tendency to over Closure, but it's not generally a
// problem to do so and likely the encapsulation makes it somewhat clearer... maybe. =D
//
// 'id' and 'p' here are what is passed further down, t.id and t.get('pageid').
// This is an Immediately Invoking Function Expression (IIFE or "iffy")
// [ <a href="https://wiki.roll20.net/API:Events#Campaign_Event" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Event</a>... ]
//
// Basically, this function gets created and executed all in one, making a Closure to
// save the parameters for use internally.
(function (id,p){
// Here I'm creating a function that will apply effects to the current graphic and also deal
// with kicking off the next effect on the current graphic. A different copy of this function
// will get created for each graphic, safely in it's own Closure.
var effectRunner=function(){
// First, check if the graphic is still in rotation. If a later execution of
// !randomfx removed the id from affectedTokens, that means I want to stop
// running the effects. Doing nothing (not going into this if block) means
// no further timers are set and the function stops getting executed.
//
// I could have used _.has() here, or used this style above, they are almost equivalent
// and are interchangeable in almost every circumstance.
if(affectedTokens[id]){
// Grab the graphic for this id
var t = getObj('graphic',id);
// If we found it, we'll do some things (otherwise, it was deleted and we'll stop)
if(t){
// With the graphic in hand, we can now apply an effect to it's current position.
applyEffect(t.get('left'),t.get('top'),p);
// Next we set a timer to run this function again. setTimeout() is asynchronous, so
// we don't need to worry about stack depth for recursion.
//
// randomInteger() returns a number between 1 and the supplied argument, like rolling
// a die. Technically, this means the minimum time between effects is
// (minSeconds seconds + 1 millisecond), but hopefully you'll forgive that oversight!
// [ <a href="https://wiki.roll20.net/API:Events#Campaign_Event" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Event</a>... ]
setTimeout(
effectRunner,
randomInteger((maxSeconds-minSeconds)*1000)+(minSeconds*1000)
);
} else {
// In the case where we didn't find the graphic, it means someone deleted it. For that
// case, we want to stop the rotation on the graphic be removing it from the
// collection of affectedTokens.
delete affectedTokens[id];
}
}
};
// Start the rotation for this graphic by running the created function. This will trigger the
// first effect and set a random timer for the next effect.
effectRunner();
}(t.id,t.get('pageid'))); //< invoking the IIFE to set 'id' and 'p'
}
});
// End of the chain. If we wanted the results, we would call
// .value() to cause _.chain() above to return them. In this
// case we don't need the results.
// [ <a href="https://wiki.roll20.net/API:Events#Campaign_Event" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Event</a>... ]
} // end of the check for !randomfx
}); // end of the on('chat:message')
}); // end of the on('ready')
We're a helpful community, so definitely ask whatever questions you would have. =D Regarding Character Sheets, that's a whole other ball of wax...
