Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "API:Script Index"

From Roll20 Wiki

Jump to: navigation, search
m (categorize)
(API Best Practices)
Line 108: Line 108:
 
== API Cookbook ==
 
== API Cookbook ==
 
== API Best Practices ==
 
== API Best Practices ==
 +
{{main|API:Best Practices}}
 +
 +
'''Include namespaces for your functions and variables,''' to avoid potential name collisions with other authors.
 +
<pre>var myNamespace = myNamespace || {};
 +
 +
myNamesapce.MY_CONSTANT = 5;
 +
myNamespace.myFunction = function() { /* ... */ }</pre>
 +
 +
'''Use easy, short, readable function and variable names.''' Names like <code>x1</code>, <code>fe2</code>, and <code>xbqne</code> are practically meaningless. Names like <code>incrementorForMainLoopWhichSpansFromTenToTwenty</code> are overly verbose, and the highly descriptive name may end up ''wrong'' as you change your code over time.
 +
 +
'''Keep your code legible,''' especially if you need to ask for help on the forums. Indent code blocks as appropriate, include spaces, etc. Compare the following:
 +
<pre>do if(node.name.toLowerCase()==='foo')break;while(parent=node.parent);</pre>
 +
<pre>do {
 +
    if (node.name.toLowerCase() === 'foo') {
 +
        break;
 +
    }
 +
} while (parent = node.parent);</pre>
 +
 +
'''Comments!''' Commenting can be something of a holy war among programmers. Some say you need more, some say your code should be enough, and so on. However, understand that for a Roll20 API script, the person reading your code may not ''be'' a programmer at all, and is completely bewildered by your black magic... but they still need to make modifications in order to suit their game. At the very least, comments describing your configuration variables are helpful to everyone who installs your script, and comments describing generally what's going on in each section of code can help the layperson trying to struggle his or her way through making the tabletop experience better.
 +
 +
'''Please write your code in English.''' JavaScript keywords are all in English. The majority of JavaScript tutorials on the web are written in English. The majority of threads in the Roll20 forums are in English, and many of the users contributing to those threads may have a tenuous grasp of one other language at best. If you name your variables and functions with another language, you may find it difficult to get assistance debugging your code.
 +
 +
'''Learn to love _.''' You have access to [http://underscorejs.org/ Underscore.js], a library with many useful utility functions. While you can certainly accomplish anything in Underscore yourself, you may find that Underscore can ''drasticaly'' reduce the size of your code. Compare:
 +
<pre>for (var i = 0; i < jossWhedon.shows.length; i++) {
 +
    if (jossWhedon.shows[i].title === 'Firefly') {
 +
        var show = jossWhedon.shows[i];
 +
    }
 +
}
 +
// show = {title: "Firefly", characters: Array[2]}
 +
 +
var characterDistribution = jossWhedon.shows.reduce(function(memo, show) {
 +
    show.characters.forEach(function(character) {
 +
        (!memo[character.role]) ? memo[character.role] = 1 : memo[character.role]++;
 +
    });
 +
    return memo;
 +
}, {});
 +
// characterDistribution = {doll: 1, mad scientist: 2, love interest: 2, slayer: 1, captain: 1, mechanic: 1}</pre>
 +
<pre>var show = _.findWhere(jossWhedon.shows, {title: 'Firefly'});
 +
// show = {title: "Firefly", characters: Array[2]}
 +
 +
var characterDistribution = _.countBy(_.flatten(_.pluck(jossWhedon.shows, 'characters')), 'role');
 +
// characterDistribution = {doll: 1, mad scientist: 2, love interest: 2, slayer: 1, captain: 1, mechanic: 1}</pre>
 +
''Underscore examples courtesy of [http://singlebrook.com/blog/simplify-your-javascript-with-underscorejs Singlebrook.com]''
 
[[Category:API]]
 
[[Category:API]]

Revision as of 22:11, 15 September 2014

Contents


Work in Progress


Scripts By Category

General Purpose Scripts

Combat Scripts

Tokens - Conditions / Status / Health

Tokens - Movement

Lighting and Revealing

  • Light Switch -- Script for turning on and off lights with chat commands.
  • !reveal command -- Automatically moves tokens from the GM layer to objects layer, making them reveal to players.
  • Light is Closing In... -- A light reduction script for token movement.

Characters - Equipment

Generators

System

Roleplay

Misc

Game Specific Scripts

Edge of the Empire

DnD 4th Edition

Zombie Dice

Basic Fantasy Role Playing Game

HERO System

AD&D (Dungeons and Dragons 2e)

Pathfinder

Star Wars Saga

Fantasy Craft 2nd Printing

API Docs

API Cookbook

API Best Practices

Main article: API:Best Practices


Include namespaces for your functions and variables, to avoid potential name collisions with other authors.

var myNamespace = myNamespace || {};

myNamesapce.MY_CONSTANT = 5;
myNamespace.myFunction = function() { /* ... */ }

Use easy, short, readable function and variable names. Names like x1, fe2, and xbqne are practically meaningless. Names like incrementorForMainLoopWhichSpansFromTenToTwenty are overly verbose, and the highly descriptive name may end up wrong as you change your code over time.

Keep your code legible, especially if you need to ask for help on the forums. Indent code blocks as appropriate, include spaces, etc. Compare the following:

do if(node.name.toLowerCase()==='foo')break;while(parent=node.parent);
do {
    if (node.name.toLowerCase() === 'foo') {
        break;
    }
} while (parent = node.parent);

Comments! Commenting can be something of a holy war among programmers. Some say you need more, some say your code should be enough, and so on. However, understand that for a Roll20 API script, the person reading your code may not be a programmer at all, and is completely bewildered by your black magic... but they still need to make modifications in order to suit their game. At the very least, comments describing your configuration variables are helpful to everyone who installs your script, and comments describing generally what's going on in each section of code can help the layperson trying to struggle his or her way through making the tabletop experience better.

Please write your code in English. JavaScript keywords are all in English. The majority of JavaScript tutorials on the web are written in English. The majority of threads in the Roll20 forums are in English, and many of the users contributing to those threads may have a tenuous grasp of one other language at best. If you name your variables and functions with another language, you may find it difficult to get assistance debugging your code.

Learn to love _. You have access to Underscore.js, a library with many useful utility functions. While you can certainly accomplish anything in Underscore yourself, you may find that Underscore can drasticaly reduce the size of your code. Compare:

for (var i = 0; i < jossWhedon.shows.length; i++) {
    if (jossWhedon.shows[i].title === 'Firefly') {
        var show = jossWhedon.shows[i];
    }
}
// show = {title: "Firefly", characters: Array[2]}

var characterDistribution = jossWhedon.shows.reduce(function(memo, show) {
    show.characters.forEach(function(character) {
        (!memo[character.role]) ? memo[character.role] = 1 : memo[character.role]++;
    });
    return memo;
}, {});
// characterDistribution = {doll: 1, mad scientist: 2, love interest: 2, slayer: 1, captain: 1, mechanic: 1}
var show = _.findWhere(jossWhedon.shows, {title: 'Firefly'});
// show = {title: "Firefly", characters: Array[2]}

var characterDistribution = _.countBy(_.flatten(_.pluck(jossWhedon.shows, 'characters')), 'role');
// characterDistribution = {doll: 1, mad scientist: 2, love interest: 2, slayer: 1, captain: 1, mechanic: 1}

Underscore examples courtesy of Singlebrook.com