gbleaney / roll205esheetimport

API script to import sheets from text copied from PDFs into Roll20

Introduction

If you are like me, you’ve got PDFs that you bought or obtained from friends with lots of monsters. Roll20 makes a lot of things easy but there is always going to be a certain amount of time required to move those monsters into the game so I finally looked into a solution to import those monster blocks into roll20. The base of this code is not mine but the work of someone 7+ years ago that was now outdated based on roll20 changes. I've done my best with little to no JavaScript or regex experience to get what we are able to get out of it.
I believe the API scripts/macros/transmogifier are behind the Pro subscription, so I believe you need it to use these tools.If I knew javascript I would probably not need the extra scripts (though re-writing code is bad so I might still use them) and if I knew regex everything would run a bit better and easier, but as of now I don’t know either. This script was tricky and due to my aforementioned lack of knowledge in the tools used to make it. It was tricky going through seven year old work, updating it for a very changed system and then trying to figure out what parts were already being done elsewhere. It is also hard to not consider that it is in roll20’s best interest to not allow something like this to be easily possible since it could discourage sales on their marketplace - not that most of the PDF’s I wish to import from are even on there. So this does not save as much time and effort as I hoped, but it still cuts out a lot of time for me and hopefully will for you as well.

NOTE: I originally wrote this up as a google doc for friends who likely haven't used any scripts or macros before, sorry if it is a bit for dummies and that I haven't added a lot of formatting here.

I’ll use this example from Monster Manual Expanded II since it was shown on their dmsguild.com store page as an example:

Setup API

First thing to do is add the API script, this is done from here:

We want three scripts, one mine and two from the Script Library. The first one from the Library is called “Tokenmod”, to add Tokenmod just search here:

Just add it, it is by one of the most prolific roll20 scripters and has a lot of uses.

This will allow our Macro to set the token HP/AC on the token bars, assign the token to our character sheet and set it as the default token for the sheet. Do the same for the second script from the library, ChatSetAttr. This is how I am able to set Traits, Legendary Actions, Bonus Actions and Reactions. Next is to add “my” script, select “New Script” next to “Script Library”, and name it something you’ll remember like “StatImport”. Next you need to copy the ImportStats.js file, most current version. Use Ctrl+a and Ctrl+c to select all of that document and copy it, then paste it in your new script in roll20:

Once you save you are ready to setup a Macro in your roll20 campaign, log into your campaign and select Macros in the upper right, you might never have used this tab before now:

Use the add button to create a new Macro. Give it a memorable name like “ImportStats” and you can select the “Show as Token Action” checkbox for ease of use but you will likely want to uncheck it whenever you aren't doing your imports to keep it from appearing while you are running games. Paste the text below in the “Actions” section:

!jf-parse !token-mod {{ --set bar1_link|npc_ac bar3_link|hp defaulttoken }}

It is not necessary to add the Tokenmod, you only need “!jf-parse”, and you can even type that into the chat with a token selected instead of using this macro. But to get all the benefits of Tokenmod I recommend using this macro or at the very least create a second macro with it, as cutting it out can make the process a bit faster when having formatting issues that cause you to start over a lot. I also know some people like HP to be the green bar instead of the red, so you can just switch the “npc_ac” and “hp”, or change one of the bar#_link text lines to bar2_link if you want to use the blue section.

Once you save this, you are ready to go!

Step 1: Get your Monster

First you need your monster. This is two fold. First you need to find it in your PDF, or homebrewery, or wherever else. It will need to be formatted very like that of the original Monster Manual, use the godfatherofassassins.txt file to again copy and paste all into a text editor before roll20's.

Note that spaces and line breaks are VERY IMPORTANT! Roll20’s text editor also kinda sucks, so I recommend not using that to make edits. Here are some of my findings to help with the parsing:

-The expected order of Abilities (everything after the stats section) is: Traits, Actions, Bonus Actions, Legendary Actions, Reactions.
-Sometimes all you need to do is press ‘del’ at the end of each line then ‘enter’ to make sure the line breaks are there. 
-Sometimes copying the end of a line to the beginning of the next and pasting that helps.
-Making all of an ability’s text a single line is often important if you are having issues.
-Traits often isn’t in the text - it can help to add a new line with “Traits” directly between the stat block section and the start of your Traits.
-Apostrophes will mess up Ability names, so leave those out. Devil’s Sight messed me up a lot.
-For Traits\Actions(of any kind) their names are temperamental, so it is important to avoid parentheses or other non-alphanumeric characters as well as very long names, so as you can see in the example above I have moved them to after the period so that they will be part of the text. Having them in the title of a Trait breaks the formatting and I don't know regex so maybe at some point I will learn and fix this if possible.
-For Actions, sometimes you’ll find sheets with the “Spellcasting” under actions instead of traits, I recommend moving it to traits. 
-Actions must also start with letter, so not now I have removed the “+2” for his weapons, ‘+’ seems to really mess with the parsing so remove those from attacks.
-You can leave your (x/day) at the end of the text in the titles of Actions, as long as they have a space before them.  
-There is a limit on the length of names (on in roll20 but the parsing) so you may want to move things like “(Recharges after a Long Rest)” to the description text.
-I’ve found that typically most errors happen with sheets with a very large number of Actions that are particularly verbose.
-Sometimes some Actions (or entire sheets) just refuse to parse. Remember, don’t fight too long with formatting your text to parse- if you are just running into issues with Actions in particular, if you can't fix it in a few seconds\tries it is better to just remove that Action’s text from your token and add those yourself. Don’t spend more time making the text the right format than it would have taken to just copy/paste it into the sheet!
-Remember to delete your sheet between each attempt. 
-If you want to include a Bio section, do so at the end of your import text, but at least three lines down. This is useful for things like Lair Actions in particular. Sometimes though, this can still match the right format to get caught by the parse, if you notice it appearing in your reactions/legendary actions just remove it. Adding an apostrophe at the beginning of the bold character blocks is good for stopping this.

The second part of this is getting a token, I’d recommend using http://rolladvantage.com/tokenstamp/ Once you have your token in roll20, copy your monster text as into the GM’s Notes of the token:

Step 2: Click the button!(2x)

Because of our previous setup, this is typically the easiest step- though sometimes it is the most frustrating because the formatting of your monster stats might be a bit off and you may need to delete the created character sheet and try again. Select your token and click the macro button you created during setup- remember you might want to disable the “show as a token action” when not doing your imports so if you don't see it just go back to your macro and so you may need to enable that again!

It may take a few seconds, but you will then get a message in the roll20 chat and the new character sheet will be at the bottom of your journal:

If you have issues with the token being set as default or having the bars set, I’d recommend having a second marco for doing that. I’ve found sometimes particularly long sheets after the stats you are importing can cause it to not be able to set the token. This next part I hope to be able to remove at some point- but so far as I know there isn’t a way around it. There is a bug(?) where if you create a sheet and give it either Traits or Reactions (since they are defined with a similar structure) before opening the sheet they will lose their descriptions. So, to get around this you have to open the sheet before we can add those. It will be at the bottom of your journal, easy to find but much faster and easier since the script made this token represent the sheet you can just double click it while holding the Shift or Alt keys. You can close it right away but I recommend checking your sheet to make sure your sheet imported everything else (all but Traits and Reactions) first:

Now you just select your token again and click your macro button, you’ll see the notice your sheet has been updated:

Note that the first click (Create) will assemble the entire sheet except Traits and Reactions and the second (Update) will only create your Traits and Reactions- so when first making your sheet if you are having trouble importing your data you will have to delete the sheet to try again. If you have the Create down and are only having issues with Update to make the Traits and Reactions (and they aren’t affecting the rest of the sheet) you can just manually delete any of the bad Traits/Reactions yourself and try updating. If you are having more issues with it you may need to delete the sheet to start over.

Step 3: Finish the Sheet

Now that the sheet is complete you can move it to where you want in the roll20 journal and add the missing details. One of the minor things I have not yet found a way to fix (maybe I’ll figure out a way eventually) is the Skill Checks and Saving Throws will display as just modifier rolls instead of the correct roll unless you edit the sheet and change a value yourself. Usually I just create a new save and skill of 0, stop editing then end again to remove it. But you could just enter a value that is just their modifier and it would still be a valid roll. You can see the way it looks before fixing to know if you need to bother:

Note the Charisma and Arcana roles added so the sheet notices a change and thus updates the roles to be correct along with our added Traits:

If you click Edit for your new sheet, you will also notice that your token has been selected as the default token, so it is already ready for you to use in the future. You can also now take the time to add any Traits, Actions, Spells, Legendary Actions that wouldn’t parse, as well as any spells.
You’ll also notice a +0 on some Actions that were not Attacks- I’ve taken the liberty of checking for damage dice roles in the text of abilities and while Roll20 doesn’t (currently) support saving throw attacks, you can just roll it like an attack to view the damage. That’s it! Once You’ve set it up it really is just as easy as creating a token, pasting the stat block, clicking a button, opening\closing the sheet, clicking the button again and then adjusting the saves/skills if the creature had any. I hope it helps! Here is our completed sheet for the Godfather of Assassins:

Transferring Sheets Between Games

Sadly, you will have to do this for each campaign you want to be able to use the script- however I think a lot of users don’t know about the Transmogifier - with that you only really need one campaign setup because you can use this roll20 tool to move your monster sheets (or handouts and maps as well). You could create a character sheets campaign and only import into that campaign, then use the Transmogifier to move a sheet to a campaign when you need it. Go to the Settings tab and at the bottom under Miscellaneous you can find it:

While powerful, the UI is (currently) TERRIBLE. You can select two of your games and just drag and drop between them- which is very easy and nice. However there is no search or filter capabilities so if you have a large campaign you will have to do a lot of scrolling and then since there is no multiselect you will have to drag each thing individually:

I hope all these can help you for your game!