[Script] Rest and Recovery

Rest and Recovery

Warlocks, and Archers, rejoice!

This is a script to handle recovery of the Resource attributes on the D&D 5th Edition by Roll20 sheet. To use this script, most non-class resources must include a code in their name, separated from the name by a plus sign. You can include standard dice expressions as well. "1d6" is used in all examples, but you can do 2d6+3, 3d20, etc. After it is finished, it will whisper to the person who used the command just which resources were affected and by how much.

This script does not affect Hit Points, Hit Dice or any of the other things that a short or long rest does. The Companion script for the sheet handles those, and I don't want to overlap any functions. This only affects the Resource section.

Here are examples of the commands given and the codes that are affected. All commands affect a selected token that represents a PC sheet.

!r-short

Used for Short Rest

+SR This resource will return to its maximum value

+SR1d6 This resource will add 1d6 to the resource up to its maximum value

!r-long

Used for Long Rest

+LR This resource will return to its maximum value

+LR1d6 This resource will add 1d6 to the resource up to its maximum value

!r-charges

used for restoring charges that are user-controlled, such as "at dawn" or "under a full moon".

+1d6 This resource will add 1d6 to the resource up to its maximum value

!r-ammo

no code is used here. The script looks for common ammo types, specifically: "Crossbow bolts", "Arrows", "Bullets", "Needles", and "Darts". It rolls 1d2 for each piece of ammo expended. If the result is a "2", the ammo is recovered, in accordance with the standard rules for D&D 5e. The max and current values are adjusted to reflect the new total.

!r-help

This will display the basic help syntax in chat.

!r-list

This will list every resource that can be recovered without using a code. Almost everything from an official sourcebook is covered with the exception of ties such as Ravnica or Acquisitions, Inc.

Special Cases

Finally, the following special cases exist. Class Resources that have any of the following names are recognized and handled appropriately:

These are recovered on a Short or Long Rest:

• Spell Slots, Warlock Spell Slots
• Channel Divinity
• Wild Shape
• Superiority Dice
• Ki Points, Ki

These are recovered on a Long Rest.

• Rages
• Lay on Hands
• Sorcery Points

Bardic Inspiration needs a +SR or +LR code, since the recovery rate changes at fifth level

Examples:

This barbarian will regain all of their rages on the command !r-long

The archer will find 1-10 arrows on the command !r-ammo. That will become the new maximum.

This high level warlock will regain all of their spells slots on the command !r-short

This Wand of Fear will regain 1d6+1 charges to a maximum of 7 on the command !r-charges

This boon will gain 1d6 charges on the command !r-short. Since it is already at maximum, it will not change.

This script is now available in One Click install.

Or directly from the Roll20 repo at https://github.com/Roll20/roll20-api-scripts/tree/master/Rest-and-Recovery

I'm sure that it will need some tweaking and patching. I ask patience, since I am not a particularly fast or skilled JavaScript coder. If anyone can think of common class features that I have overlooked, or variant ways to refer to them, please feel free to make suggestions. The same goes for common ammunition types. Remember that special cases can always be handled with an appropriate recovery code, though.

Hey keith! That sounds really cool and quicker to set up rather than a setattr method! 

Do you handle translation? (Maybe through a setup menu?)

Can you explain a bit more about how you handle ammunitions : in your exemple, 10/20... 10 is the number of arrows remaining or used? :)

All of the "special" names are declared near the beginning of the script:

                let shortRestList = ['Spell Slots', 'Warlock Spell Slots', 'Channel Divinity', 'Wild Shapes', 'Superiority Dice', 'Ki', 'Ki Points'];
                let longRestList = ['Rages', 'Lay on Hands', 'Sorcery Points'];
                let ammoList = ['Crossbow bolts', 'Arrows', 'Bullets', 'Sling Bullets', 'Needles', 'Darts'];

... so yeah, it should be pretty easy to localize without any programming knowledge. I haven't yet learned how to work with the state object, so no setup menu.

The ammo algorithm is basically:

Find number of spent pieces (max - current)
Roll that many d2s, and then subtract that number (if you spent 10 arrows, then that's [[10d2-10]])
Add that result to the current amount and then set the max to equal the new current value.

So if you started with a max of 20 arrows and shot 12 of them so that you currently had 8 remaining, the formula would be:

(20-8)d2-(20-8) => 12d2-12 => ~6 (most likely result)
Current = (6 + 8) = 14
Max = 14

Whoa, this is awesome! I already have my own jury-rigged long-rest and short-rest recovery macros happening (via ChatSetAttr) but eventually I'll probably want to move to this. 

This is fantastic, keithcurtis. Looking forward to trying it out.

First I gotta say that I really like it ^^ But I ran into something that I wanted ot ask about. When I played with my group, the players couldn't use the retrieve ammo command. They would just get # followed by the macro I set up for it. Is this normal behaviour? I mean I could just use it instead of them, but thought it would be fun for them to retrieve their own shot ammo :)

That sounds like the macro may not being called correctly. Can you post the macro, plus whatever macro might call that macro, and describe where it is stored?

keithcurtis said:

That sounds like the macro may not being called correctly. Can you post the macro, plus whatever macro might call that macro, and describe where it is stored?

Sorry for replying so late but here is the macro. :)

And here is the macro that calls the macro:

&{template:default} {{name=Player Menu}} {{
Movement=[Moving](!
#Move)}} {{
Actions=[Initiative](!
#Initiative) - [Short Rest](!
#Short-Rest) - [Long Rest](!
#Long-Rest) - [Retrieve Ammo](!
#Retrieve-Ammo)}} {{
Checks=[Ability](!
#Ability-Check) - [Skill](!
#Skill-Check) - [Saving](!
#Saving-Throws)}} {{
Money=[CashMaster](!
#CashMaster)}}

Now seeing it again, I'm thinking it could also just be a call to the script instead of having it call a macro that calls the macro :P

Hope this helps figuring out what happend (I did something wrong probably)

The screen shot shows that the retrieve ammo macro is not visible to the players, i.e. it can be used only by you. Put "All Players" in the Visible to Players field and that should put you right. And yeah, those buttons are actually built with API calls in mind. Hence the rigmarole with the html replacements. Here are some useful posts for building macro systems and chat menus:

Macro Character Sheet

Chat Menu

Wow, I feel stupid for missing that xD Totally forgot doing that. Thanks for pointing that out.
A macro character sheet sounds pretty handy, gonna look into that!

Thanks again for helping and for the awesome scripts.   

Glad it was a simple fix.

Update.

I have gone through every official sourcebook (with the exception of some of the tie-in products like Ravnica or Acq. Inc) and added just about every ability I could find that recovers on a short or on a long rest. The script now includes a !r-list command that will give you the name of everything available.

I have updated the code at the link in top post.

Hey, thanks for the cool script! I have a question: is there a reason that a token must be selected to call the help command (and the list as well)?

And a second hint: you described in this post the commands as "!r-Help" but actually your script only supports "!r-help" atm. Maybe a .toLowerCase() at the if statement at the bottom of the script might improve usability :)

Oh, and one other hint you might be interested in (if not ignore it :) ) - if you use while(...) {...} instead of do {...} while(...) you don't need those if-statements in the loops

Oh and I just discovered another bug: your script whispers the messages to only the part of the name after the first space. So I have a Character called "Astaroth Malphas" and the whisper command sends it to "Malphas". Even worse, if a player has only one word, like for one player of mine called "Meriel", I don't see any whispering in the chat at all.

Edit: I think I found the solution to this: if whispering, you need to enclose the name in ""

I'll put those in the next version. Thanks!

Fortunately, I caught the capitalization before submitting to the repo.

The need for the token being selected is just laziness on my part. I added the help rather late in the writing process and just decided to tack it onto the list of routines after testing for selection had already been done.

This script is now available in One Click install.

I can't seen to find this script. One click install means the script library, correct? Is it called something not obvious? Where to I find it? Daddy wants.

Same, I can't seem to find it in the API section.

Yes, I have contacted the devs about this. It is in the official Roll20 repo, but I forgot you have to make a special request for the One-Click. I have not yet heard back. I'm still hoping it will be available by next Tuesday's merge.

I didnt know you had to make a special request. I assumed it would be automatic, like the character sheet repo. That's what its for, after all.

There has been talk of that, but I do not think it is the case. It's very difficult to find the info on the new Help Center.

Good catch. I have added it back into the top post, but here is the direct link:

https://github.com/Roll20/roll20-api-scripts/tree/master/Rest-and-Recovery

It's going to be one more week for One-Click. I missed a hoop to jump through and forgot to validate the script.json. Live and learn.

Now that the bug that has been keeping One-Click scripts from installing properly has been fixed by the devs, this script is now finally and truly available for quick and easy installation and updating.

Okay just came across this and I'm loving it. I have my own Short rest macros already but this will streamline so much. You da best.

Only question I have is, is there any way to track ammo that's not one of the basic types. For example, my rogue has arrows, bolts, and a set of walloping arrows she found a while back. Could I track the walloping arrows the same way I can track the regular ones?

Edit: I suppose, since the walloping arrows lose their magical property once shot, that they would be recollected as regular arrows. Which presents more complications. So i get it if that's just a "keep track yourself" kinda thing.

I have some ideas for that. Now that One Click is finally working, I can look into giving that capability.

I'm already editing the script to include racial abilities like the orc's Relentless Rage, tiefling's Hellish Rebuke, etc., as well as Luck Points from the Lucky feat. Any chance you will be adding these changes to the script yourself?

Long rest adds so far: 'Relentless Rage', 'Arcane Recovery', 'Hellish Rebuke',  'Healing Light,'

Short rest adds: 'Breath Weapon,'

Yeah, if you have anything you can think of that needs adding. I have some time this weekend.

I made a list of racial abilities from non-setting specific sources, but added Genasi. Some are just spell names, like a Drow gets Faerie Fire, and Darkness once per long rest.

'Fey Step', 'Hidden Step', 'Firbolg Magic', 'Stones Endurance', 'Saving Face', 'Grovel Cower and Beg', 'Hungry Jaws', 'Fury of the Small', 'Breath Weapon', 

'Necrotic Shroud', 'Radiant Soul', 'Radiant Consumption', 'Healing Hands', 'Duergar Magic', 'Dancing Lights', 'Faerie Fire', 'Darkness', 'Blessing of the Raven Queen', 'Mingle with the Wind', 'Merge with Stone', 'Reach to the Blaze', 'Burning Hands', 'Githyanki Psionics', 'Jump', 'Misty Step', 'Githerazi Psionics', 'Shield', 'Detect Thoughts', 'Control Air and Water', 'Poison Spray', 'Animal Friendship', 'Hellish Rebuke', 'Relentless Endurance', 'Luck', 

I had decided against using spell names in the resources section, since the spell section not only seemed the likelier place, but has a field for placing innate "1/day", and source "drow magic" notations. Still, these are not technically tracked in any meaningful way, and the script is not slowed to any realistic degree by their inclusion.

I didn't know it did that. I've been adding more of the class features, but I haven't been very picky. Thank you for this script that. It was really something missing from the OGL Companion.

Do you have any advice on muting that message, or changing the message to a public "so-and-so took a rest" instead? I've messed around with it and I break it everytime.

For the message, changing line 20 to 

                sendChat("Rest and Recovery", header + messageText + footer);

I liked your idea of putting the character name in the report. The script now does that, so you can tell whom is recovering.:

you can still edit the line as above to remove the whisper. After the update it will be:

                sendChat("Rest and Recovery", header + '<b>'+(getObj('character', characterID)).get('name') + '</b><BR>' + messageText + footer);

The Devilish DM said:

Okay just came across this and I'm loving it. I have my own Short rest macros already but this will streamline so much. You da best.

Only question I have is, is there any way to track ammo that's not one of the basic types. For example, my rogue has arrows, bolts, and a set of walloping arrows she found a while back. Could I track the walloping arrows the same way I can track the regular ones?

Edit: I suppose, since the walloping arrows lose their magical property once shot, that they would be recollected as regular arrows. Which presents more complications. So i get it if that's just a "keep track yourself" kinda thing.

Actually, I wasn't thinking the first time you asked this. For anything you put in there to be treated as ammo, just change the name like so:

walloping arrows+ammo

and the script will recover it using the ammo rules upon issuing !r-ammo

Of course, you will need to change the name of the ammo resource on the attack to match.

Thanks for your work! I pulled the new code and it looks much more complete, and the change in message is working out fine. Added the " took a rest" bit before the </b> so it works seamless with the new name addition. Very cool. 

I've got !longrest and !r-long built into a macro with ChatSetAttr to clear any death saves (and !r-short with the same). Both in a drop-down token macro called Rest. It's nifty. I dabble with the API and way too complicated macros every few years before I get discouraged. My next step is a "are you sure you want to rest" query to discourage accidents. Then, onward to figuring out how to add rolling short rest dice along with the !r-short macro... I'll get there.

There are two other "rest" scripts that came out within two weeks after this one*. I know at least one of them does hit dice. I think the only thing mine does that isn't duplicated by one or both of them is ammo recovery. You could take a look at them. I believe they are both in the One Click.

*They're like busses that way, apparently.

How does !r-ammo track the ammo that has been expended? EDIT - Figured it out. Amazing script!

Thank you. Ammo recovery is about the only thing this script does that is not done by the other resting scripts. (And they each have things that this one doesn't do). :D