A Novice's Guide to Using APIs

Hi I've just upgraded my account to be able to use APIs... but (not being particularly technical) I'm not quite sure how to use them. :(  The first one I used was the "5th Edition OGL by Roll20 Companion" - but that seems to fit in behind the scenes and work automatically. However, I have a group that's constantly lighting and extinguishing torches and lamps, so I'd love to use the Torch API as it would seem to solve my issue of having to manually set and reset the lighting sources on each token (and restoring dark vision etc.). But *how* do I use it???  Is there somewhere on the Wiki or the Forums that explains this? Perhaps for each API we need a "Dummies Guide to using..." section? Steve

A lot of the scripts have this information already in them and it becomes available once you install the script in your API library. For example this is what I see after loading Torch into my campaign from the API screen.

Most of my scripts also whisper you help if you run their command with no arguments or with --help !torch --help There does need to be a bit better system for this and I'm working on one... but there never seems to be enough time...  The forums are also a great place to go for help.  Usually, you can search the API Forum for a particular script and find where it was initially published with instructions.

Your best bet for Torch specifically would be to create a macro that could be used either as a campaign macro (if you're going to be doing the snuffing and lighting of torches) or as an ability macro that would be a token action (if players will be snuffing and lighting their own torches).  The text of the macro could look something like this - assuming a standard 5e 40 ft. torch radius with a dim at 20 ft.  If you want different light radii, you need to specify it in the macro.  For thoroughness, I'll fill in all the defaults: /em "@{selected|token_name}" lights a torch! !torch 40 20 yes @{selected|token_id} 360 or you could just make that second line: !torch @{selected|token_id} Then you would make another macro to turn off the torch: /em 's torch burns out! !snuff @{selected|token_id} Both of these macros assume that you've already selected the token that you want to be carrying the torch.  the line with the /em could be customized as you like, or removed - it's just there for flavor.  If you'd prefer the light to flicker, replace !torch with !flicker-on, and !snuff with !flicker-off. Hope this helps, and if I've made an error in my macro, hopefully someone will correct me.  It's been a while since I've used this script (I do all my lighting with TokenMod these days).

Thanks - managed to get it working... Would be so very nice if the torch could also be in a color though (ie make a torch an orangey color)... ;-) 

That would be great.  The common work around is to give the torch token an aura of an orange color with the same radius as the light.  The biggest issue with that is that auras are not blocked by walls.

Yeah... I thought of that too. Not tried it though. Hmmmm. If you use dynamic lighting, would that help? I guess that would stop the PCs "seeing" through the wall, but I guess the light would bleed through into other open areas? That is, would the torch light bleed through to the other side of the wall it's on (potentially lighting up the room on the other side)?

The torch light wouldn't bleed, but the orange aura would.

Yeah. That's what I figured :(