New Official API Repository

1420654464

Edited 1421088598
Steve K.
Roll20 Dev Team
Sheet Author
API Scripter
Compendium Editor
We're excited to launch the Roll20 API Repository . The goal of the repository is to keep an up to date list of community created API scripts that's both healthy and easily accessible for new mentors. This is the first step toward better integrating API scripts into the user experience. Our vision is to have API scripts as accessible as character sheets, with automatic script dependency and conflict checking. We want users to be able to get access to your scripts with a click of the button, without installation guides or intimidating set up lists. For now we're asking that after a script is merged into the API Repository that the contributor add their listing to the API Script Index wiki. Please take special care to read the instruction on contributing in the README.md file. Please provide all the information and in the format we're requesting so that we can showcase your work in the future of Roll20's API interface. Once the Repository and the Script Index have several contributions we'll begin to publicly advertise them for use.
1420664407
Brian
Pro
Sheet Author
API Scripter
I'm certainly excited! =D
1420674541
Nice. One enhancement I might like to see is a "recommended" list in the package file parallel to the dependencies list. For example, some of my scripts make use of Aaron's isGM module if it's present, but do their own guessing if it isn't. Obviously one can just say "this will work better if you also install the following modules: ..." in the readme, but it would be nice to have those recommended modules use the same kind of interface that'll presumably exist to point people to dependencies.
1420679674
GenKitty
Roll20 Mod Team
Query: Will scripts continue to be GM-editable, or will the act of installing via repository lock down the script against editing?
1420680391
Riley D.
Roll20 Dev Team
GenKitty said: Query: Will scripts continue to be GM-editable, or will the act of installing via repository lock down the script against editing? Right now this is literally just a place to store everything. So we're just trying to get more organized than "posting gists on a forum". So for now, it will be the same exact process (GM gets code from repository and copy and pastes it into their own API thing, modifying as they desire), only hopefully the package.json file, WIki, and README might provide some better, more standardized instructions, help them track down dependencies easier (now that it's all in one place), etc. In the future, we're working on a system that is similar to npm or other package repositories. So you would just be able to say "I want to use the 'isGM' script" and the system would automatically handle fetching the latest version, resolving all dependencies, and running that script. No need for copying and pasting. In addition, we would automatically notify you when a new version is out and you would be able to click a button to update to the newest version (again, updating all necessary dependencies automatically). When we reach that stage, my assumption is that we'll have a tool where script authors can provide a listing of variables that GMs can customize (configuration options, etc.). So you'd have a page you go to that says "Here's what you can change for isGM (if anything). Here's what you can change for DarknessClosingIn. Here's what you can change for BloodSplatter. Etc." And of course if you want to make further modifications than that, you can still do the old copy+paste method, you just don't get the handy automatic one-click installation. And you'll be able to mix-and-match one-click installed scripts with your own custom stuff, of course, as well.
1420709690
Brian
Pro
Sheet Author
API Scripter
I stayed up waaaay too late being happy about this and updating/uploading a bunch of my scripts. x_x
1420729599
Riley D.
Roll20 Dev Team
Brian said: I stayed up waaaay too late being happy about this and updating/uploading a bunch of my scripts. x_x Much appreciated! We'll get that merged in here shortly.
1420955623

Edited 1420955705
so awesomeQQ I am sooooo bad at API's so if the instructions are not written in the easiest terms ever I generally install it on a test server and then proceed to pull out my hair for a few hours because it wont do what I want it to! Also, I spend far too much time looking for the most amazing API's(not much hair left after all the pulling), or I find out there is some better way to do something while randomly searching through the forums for a completely unrelated thing!(curse you door control API! My final bits of hair shall soon be gone!) So, I'm glad that it's all going to be in one place and eventually easy! Then I can put them all in!!! I don't care if they aren't useful for D&D! I need the ability to have a spaceship...for...reasons... Good job guys! Glad I went for the mentor level! LOVE what you guys are doing and this site! Can't wait to see where you go from here!
1421007940
This is a big improvement, especially for those of us, like myself, who are Java Illiterates.
1421080926
Brian
Pro
Sheet Author
API Scripter
Could we get another property added to the package.json schema to indicate deprecation of the script? For example, Aaron's isGM authentication is deprecated by the changes recently pushed to dev. Something like "deprecated": false for regular scripts and "deprecated": "reason" for scripts which are of marginal use due to changes/additions to native Roll20.
1421082789
The Aaron
Pro
API Scripter
Or perhaps assume deprecated false unless the property is present.
1421082998
Brian
Pro
Sheet Author
API Scripter
Also a possibility.
1421096155
Steve K.
Roll20 Dev Team
Sheet Author
API Scripter
Compendium Editor
I don't see anything wrong with adding that but it should be documented primarily in the help documentation and probably also the description.
1421098841
Brian
Pro
Sheet Author
API Scripter
Currently, yeah, documenting deprecation in the help would be the most visible means to make people aware. But eventually you guys are talking about making a distribution platform for this similar to the character sheets, at which point something in the json would be more important. The distribution platform could make it clear that a script is deprecated, and it could report on scripts with dependencies on deprecated scripts.
1421326577
GenKitty
Roll20 Mod Team
Tweak Requested: There needs to be an easy way for someone to get in touch with the script writer for help. Writers should be strongly urged to put contact info (Email, forum thread, Roll20 id) in their help/readme file at a minimum. Beyond that, I'm not sure how a newbie user can easily get help for issues, aside from starting a new thread in a forum.
1421339714
Steve K.
Roll20 Dev Team
Sheet Author
API Scripter
Compendium Editor
GenKitty said: Tweak Requested: There needs to be an easy way for someone to get in touch with the script writer for help. Writers should be strongly urged to put contact info (Email, forum thread, Roll20 id) in their help/readme file at a minimum. Beyond that, I'm not sure how a newbie user can easily get help for issues, aside from starting a new thread in a forum. Script contributors are encouraged to make a Wiki entry for their scripts, which include a profile link so they can send private messages to the authors. That way they don't need to share their email address in a public space. However, I'm all for authors putting their preferred contact information in their help documentation.
1421341409
Brian
Pro
Sheet Author
API Scripter
Indeed, there is a template available on the wiki to make this fairly simple: {{script overview |name=Dynamic Lighting Animation |author={{user profile|235259|Brian}} |version=2.0 |dependencies={{api repository link|splitArgs}}, {{api repository link|IsGM Auth Module}} |conflicts={{api repository link|Store Commands}} |lastmodified=2015-01-08}} (The dependencies and conflicts parameters can be omitted and they'll be filled in as "None") The {{ script overview }} template makes a little sidebar menu with relevant information about the script. {{ user profile }} links to a user's profile page (not their wiki userpage); you need to supply their userid (mine is 235259), and you ought to supply the name or else the link will appear as the id number. {{ api repository link }} links to an API script on the GitHub repo. You can either link to a file directly, or link to a directory. Other useful templates available for documenting a script on the wiki include {{ API command }}, {{ API parameter }}, {{ changelog version }}, {{ deprecated }}, {{ formal API command }}, {{ param description }}, {{ param description bottom }}, {{ param description top }}, {{ syntaxbox bottom }}, and {{ syntaxbox top }}.
I'd like to contribute my Mob-gen script, but I'm a big GPL, FSF guy.
1421673628
Brian
Pro
Sheet Author
API Scripter
Ken L. said: I'd like to contribute my Mob-gen script, but I'm a big GPL, FSF guy. Scripts submitted to the repo use the MIT license, which is FSF-approved, as well as being GPL-compatible. I believe the biggest difference between MIT and GPL is that something with a GPL license can't be used in a piece of proprietary software. Meaning, to pull a relevant example out of my hat, if you submitted a useful and popular script, Riley wouldn't be able to use any of that code to incorporate the idea into Roll20 natively. (Granted, I'm sure native additions have better options than the API library affords us scripters and so using any of the submitted code would be unnessary, but the sentiment stands.)
Brian said: Scripts submitted to the repo use the MIT license, which is FSF-approved, as well as being GPL-compatible. I believe the biggest difference between MIT and GPL is that something with a GPL license can't be used in a piece of proprietary software. I've been around the IP park more times than once. The biggest difference is that the MIT is not copyleft and also for the reasons you mentioned. I'm a pretty strong believer in keeping FLOSS in the public domain, including changes to it. In respect to the licensing I highly doubt that Roll20 would integrate a stat block parser as statblocks constantly change with the times. It's a small thing but hey, gotta have principles right? Either way, I don't see how GPL isn't compatible in this format since it's publicly available, and it's compatible with GPL in it can use MIT for integration purposes which I see hints of in the assets. It's module-blocked so having some blocks be GPL or MIT or even BSD won't raise any issues. That's just my 2 cents. I'd probably release it under GPL v3 sometime in the future whenever I get the time to wrap up some edge cases. Just won't be part of the repo.
1421681958
Riley D.
Roll20 Dev Team
If we decided to implement something akin to the functionality of a popular API script directly into Roll20, we would do so with our own code (e.g. the new playerIsGM() function, while doing the same thing as Aaron's isGM() script, shares no code in common, and is in fact done using a completely different method). However, the way that the new "one-click code" install process will work requires that we load all submitted API scripts onto our servers and redistribute them to all users, where (depending on your reading of the GPL) they would "attach" to Roll20. So basically just by offering any sort of integration with the API scripts, we would be exposing ourselves to potential copyright issues. Hence the MIT license. And I'm sure the argument could be made that it doesn't attach to Roll20 at that point, but the fact of the matter is that it's a gray area. If you don't want to license under MIT, I totally understand and respect that, but we won't be able to include it in this collection or offer the one-click install process with it when that feature is made available.
That's cool, I'll just share it the old fashioned way.
1422137003
Natha
KS Backer
Sheet Author
API Scripter
Great plans! How should be referenced/documented scripts for specific games which require specific attributes ? In the readme.md ?
1422150288
The Aaron
Pro
API Scripter
I'd be tempted to have my scripts do a quick check for the existence of any attributes with the required name, then /w GM detailed instructions if you don't find them, along with a log message stating similar. Certainly doesn't hurt to put it in the Readme, but if the script can detect the deficit and inform the user it will make using it much easier. Stephen S.'s latest dungeon script does a fantastic job of detecting missing requirements and instructing the user regarding how to correct the issue.
Someone can refresh me, but I was recently told during a conf that GPL-MIT dual licensing can work in this situation.
1426171089
Could we get a better display of these scripts? The titles aren't always very specific as to what the script will do. What is after the title is pretty much the first few strings of the scrip, rather than a description.
1426171550
The Aaron
Pro
API Scripter
Technically, what is after the title is the commit message from the last update that changed a file in that directory. There is a package.json file in each folder that contains a description of the script. I believe the devs have mentioned that they are working on a better system, for which this is just the first step. Here is a current list of the names and their descriptions: Ammo -- Provides inventory management for ammunition stored in an attribute of a character. AmmunitionTracker -- A bunch of commands to track ammunition. AnnounceRoll -- Prints an extra announcment of a critical or fumble to the chat when using /roll APIHeartBeat -- Provides an API Heartbeat by setting the requesting player's color continuously. Base64 -- Base 64 encoding for Roll20 Scripts. (Adapted from http://www.webtoolkit.info/ ) BashDice -- Rolls the Bash UE Dice format with exploding. Blood-and-Honor -- Automatic blood spatter, pooling and trail effects. Bloodied and Dead Status Markers -- This script automatically adds the Red marker to represent the 'bloodied' state for any tokens that drop below half their health, and the 'dead' marker for any that drop to 0 or less. It's assumed that health is stored in Bar 1. Collision Detection -- Watches for collisions between player-controlled tokens and a specified subset of path objects. When a collision is detected, the script may return the token to its position prior to the move, send a warning message to the token's controller, and/or halt the token at the path acting as a barrier to movement. CommandShell -- Framework for chat commands DarknessClosingIn -- A command wrapped version of the Darkness Closing In API sample script. Dynamic Lighting Animation -- Animates paths on the Dynamic Lighting layer. Emas -- Provides player !emas and !as commands. EotE Dice Roller -- A Dice roller for the Edge of the Empire/Age of Rebellion/Force and Destiny Roleplaying Game Escalation -- Simple Escalation Die handling script, using the new custom entries with formulae. Exalted Successes -- Reports successes on d10 rolls for use with the Exalted game system. FateDots -- Provides numbered multi dots for Fate stress boxes. Flight -- Adds 'fluffy-wings' status icon to selected token to represent some height. Flip Tokens -- Flips selected graphics horizontally and/or vertically. Especially useful for games with side-view tokens, and for players who do not have access to the same context menu as GMs. GMCode -- Generates a unique code to authenticate the GM. Has no use on it's own, to be used with other code to provide more power to the GM. GroupInitiative -- Adds the selected tokens to the turn order after rolling their initiative + configurable data. InitiativeTracker -- Initiative and status tracker. Round counter, optional round and turn announcements, management of limited-duration status effects (with countdown of last 9 rounds in status icon) Interpreted sendChat -- Provides a function for other scripts to use to assist in sending messages to the chat. This script is not intended to stand alone. InventoryManager -- A graphical inventory manager. Inspired by John C. IsGM -- Adds a function, isGM(id), which returns true for gms and false for players. GM database is built in the state object automatically as players and gms send chat messages. IsGreater -- Trivial little script to check if the first value is greater than the second and report it to chat. Its A Trap -- Provides a simple means to set traps and detect when tokens move across them. levenshteinDistance -- Provides a levenshteinDistance function for comparing strings. This script is not intended to stand alone. ManualAttribute -- Creates a manual copy of an autocalculated field, and assigns it to the bar of a token. MapLock -- Provides locking of graphics to prevent moving/resizing/rotating them. Also highlighting. Mark -- Places a numbered Marker under tokens, clears on turn change/close, and page change. Marking Conditions -- Sets and removes statusmarkers on tokens. Measure -- Measure distances between multiple tokens, both from the corners and the center. MonsterHitDice -- Set Monster hit dice on add, usually via drag from journal. MonsterHitDice5e -- Set Monster hit dice on add, usually via drag from journal. Configured for Dungeons and Dragons 5e Character Sheet MotD -- Greets players that log in with the contents of a particular note. MovePlayers -- Allows macros to move the player ribbon for players. No Token Rotation -- Prevents tokens from being rotated by anyone. Raise Count -- Counts raises for the Savage Worlds system. Random Turnorder -- Shuffles items in the turnorder window, and adds any selected tokens if they are not already present. RandomDepth -- Randomly adjusts the depth of selected tokens. RandomRotate -- Allows the GM to easily rotate all selected tokens to a random angle. SizeLock -- Toggles a state which reverts any size changes automatically. Slide Tokens -- Move tokens with an API command, while showing the path and waypoints as though it had been moved manually. SpellLevel5e -- SpinTokens -- Allows the GM to toggle spinning of selected tokens. splitArgs -- Provides a function for splitting arguments of an API command. This script is not intended to stand alone. Store Commands -- Stores a series of commands (potentially with delays between them) to be executed in sequence later. Opens up GM-only commands such as /direct and /emas to players. TableExport -- A script for exporting Rollable Tables between accounts. TableTokenSizer -- Simple script to scale rollable tokens added to the tabletop to a given size (defaults to 3x3) an set them as not drawings. TempHPAndStatus -- Temp hit point manager and bloodied/dying/dead status markers. The Darkness is Closing In -- This script reduces the light radius of a token by 10% every time that token moves. Great for simulating 'lamps running out of oil' or similar high-stress situations. Tile -- Create tiled arrays of grpahics on the map layer. Token Collisions -- A small library for detecting collisions among tokens. TokenLock -- Allows GMs to selectively lock the movement of Player Tokens. TokenMod -- An interface to adjusting properties of a token from a macro or the chat area. TokenNameNumber -- Automatic Numbering of tokens with special placeholder. Torch -- A simple script for giving lights to tokens and turning off and on dynamic lighting. TurnMarker1 -- Round counter and a moving marker that shows who's turn it is. Twins -- Links two tokens so that they mirror each other across pages. UsePower -- A script for instrumenting and tracking the use of encounter and daily powers. Vector Math -- Walls -- Builds dynamic lighting walls with an exported SVG path file. WeightedDice -- Automated creation of rollable tables where a minimum value is weighted with values it replaces. (example d6min4 possible values: 4 4 4 4 5 6) ZombieDice -- Rolls canceling Zombie Dice
1426171614
The Aaron
Pro
API Scripter
You can also find descriptions of most of these scripts by searching the forum for their name, though some are a bit inocuous.
1426171659
The Aaron
Pro
API Scripter
Additionally, there is an effort underway to document each of these scripts in the wiki: https://wiki.roll20.net/API:Script_Index
1427086311
Granted: I don't understand some of the licencing issue etc or even the coding impact of the following, but 2 cents is still 2 cents - so here's mine... Why can't there just be a section of server space dedicated to holding the API code directly at Roll20 (instead of outer sources like GitHub). When a person would like to use any specific API, they go to a page of categories and open folder or something - Then they could possibly have a list and select check-boxes on the ones they want used in their campaign. Instead of uploading a copy of the same API over possibly thousands of campaigns, have a single version that can run in multiple instances from one set of codes. Example (under campaign details/API selection) (Checkboxes or radio buttons) Version Title System Author Catagory Brief description # users @ 1.0 MassInit.js Any SomeDude Combat / Tracker Allows initiative rolls for multiple selected tokens ??? @ 3.6 TurnTracker.js Any AnyGuy Combat / Tracker Highlights active token from Init Tracker ??? O F RollEffects.js D&D3.5 CodeMan Dice Roll Handling Selects random effects following Critical or Fail rolls ??? O 2.1 CharSheetPopulate.js Pathfinder GMGod Character Sheets Populates blank character sheets to create NPCs ??? O Etc Etc Etc Etc Etc Etc Or possibly having it similar to now, but from the central location (as long as the script title is the exact same as in the campaigns) there could be an update push to get the changes made from behind the scenes. Or maybe upload the current version to the campaign temporarily when the campaign is actively launched and gone when there are no people logged into it. Either of these options would be able to track which APIs are being used and by how many for the scriptwriters to focus/cater better to the users. Maybe allow the users to sort by popularity (or whichever column). There may be scripts out there with abilities they don't even know about but if many are using it, they might see it and not even realize some cool option existed. Not sure how campaign specific customization would work, unless you went with the option of getting pushes and perhaps only offered a notice of possible upgrade with a option to follow through or stay with current. (I don't know how many out there are going in and tweaking pre-made coding that would cause them to want to keep an old version going) This would make it so when a script gets updated, users would get a update to use instead of some not having a bug fix or upgrade due to not knowing one was available (unless the notify version and they chose to keep the older version). Or should this be moved over to Suggestions?
1427090366
Brian
Pro
Sheet Author
API Scripter
John K. said: Why can't there just be a section of server space dedicated to holding the API code directly at Roll20 (instead of outer sources like GitHub). When a person would like to use any specific API, they go to a page of categories and open folder or something - Then they could possibly have a list and select check-boxes on the ones they want used in their campaign. Instead of uploading a copy of the same API over possibly thousands of campaigns, have a single version that can run in multiple instances from one set of codes. Something like this is exactly why the GitHub repo was created. Much like how you can select a character sheet (which was created by the community and uploaded to GitHub), the intent is to eventually have a similar system for API scripts.
1427125305
Brian: I understand the tie-ins that are created (Roll20 / Roll20 Repository / Script Wiki Index / Campaign API) but is there a way to be notified if/when a script gets updated or do I just have to constantly keep checking on the ones that I use?
1427133810
Steve K.
Roll20 Dev Team
Sheet Author
API Scripter
Compendium Editor
John K. said: Brian: I understand the tie-ins that are created (Roll20 / Roll20 Repository / Script Wiki Index / Campaign API) but is there a way to be notified if/when a script gets updated or do I just have to constantly keep checking on the ones that I use? The idea is to create a one-click implementation of API scripts similar to Character sheets. This would include whenever an update is made to an API script you're notified as to whether you'll want to use the new version or keep your existing one. As for the present moment, there is the ability to follow folders and even specific files in a git repository where you will be emailed whenever changes are made.
Can we host our own repos? I'd like to be able to enter an address, a public key, and a branch name and have it load any .js file contained.
1429917822
The Aaron
Roll20 Mod Team
API Scripter
Matt O. said: Can we host our own repos? I'd like to be able to enter an address, a public key, and a branch name and have it load any .js file contained. Currently, there is no facility to automatically load API scripts into a Campaign.
1430196223
Black Falcon
Pro
Sheet Author
Aaron - that is a ridiculous amount of scripts. Steve - What is the expected time table of having this released?
1430196706
The Aaron
Pro
API Scripter
They aren't ALL mine... =D
1430233520
Steve K.
Roll20 Dev Team
Sheet Author
API Scripter
Compendium Editor
Black Falcon said: Steve - What is the expected time table of having this released? The Repository is live. I'm assuming you mean one-click integration? The answer to that is "yes..."
1430243054
Black Falcon
Pro
Sheet Author
Steve K. said: Black Falcon said: Steve - What is the expected time table of having this released? The Repository is live. I'm assuming you mean one-click integration? The answer to that is "yes..." So what does "yes..." mean? lol Yes - I mean the one-click integration? And did I miss the link of where the repository sits? Will it be in the API section of the campaign?
1430245711
The Aaron
Roll20 Mod Team
API Scripter
The repo is in Github: https://github.com/Roll20/roll20-api-scripts
1430247572
Steve K.
Roll20 Dev Team
Sheet Author
API Scripter
Compendium Editor
The Aaron said: The repo is in Github: https://github.com/Roll20/roll20-api-scripts There is also the wiki: https://wiki.roll20.net/API:Script_Index
1430387530
How do I use the measure API script?
1430395712
The Aaron
Pro
API Scripter
Scott S. said: How do I use the measure API script? Select 2 or more tokens and type !measure to display the distance in chat, or !wmeasure to whisper it to the GM.
this is what I have been looking for. thanks folks.
I  wonder How everything will look with this new Skin...very excited a little nervous but If it makes my games look cooler lets get cracking!!!
Is this "one-click script installation" functionality in place? I only found mention of it in this thread and one other, and can't seem to find any mention of it in the wiki help docs. I also can't seem to find how the "requires script X" is supposed to work. I'm referring to scripts that state they require other scripts, such as Vector Math and Token Collisions, suggesting they need those to function properly. Should I be able to install "script X" as a separate script so "script Y" can use it, or would they need to be stitched together into a single script to function properly? If this stuff is already explained elsewhere, please point me in the right direction.
1442494258
The Aaron
Roll20 Mod Team
API Scripter
One-click script installation has not yet been created.  Getting a collection of scripts in a standard format in a github repo was the first step to doing that. As for scripts that require other scripts, you can put each script in it's own tab within the API Scripts area.  When the API starts, all script tabs that are active are concatenated into a single script which is executed.
Ahhh...OK thanks The Aaron, very helpful.