Avoiding API scripts

Hi,

I've just developed a sheet, only I hadn't realised you can't include an API script in its development. >_<
While I understnad you can't use API scripts, can you use the text/worker script in the html?

If so is there a simple example of it?

I believe you can use API scripts in sheets. I know at least a couple have them.

That said, I think its not good practice, unless its made as a hideable option, because roll20 now only allows 1 sheet per game, and most people who use roll20 are not Pro users. So if you include API stuff in your sheet, you are frustrating most of the userbase who cant now get another sheet accepted. 

You can use text/worker scripts, but they aren't the same as API scripts. There's a lot of shared functionality between them, but ultimately, they have different purposes. sheet workers can only affect things on the sheet itself. They cant create output. For output to chat, you are still limited to the normal chat macro system.

What do you want to achieve?

Roll20 doesn't like sheets that exclusively relies on API script to function, because that would make the sheet unusable for free users.

So they wants the sheet to have sheet workers/auto calculated field to fall back on if the user don't have access to the API scripts.

Roll20 staff talking about this

Just to clarify some stuff that isn't perhaps being made completely clear here. There are two completely separate types of scripts that you can create on Roll20. They are both written in Javascript but they serve different functions and have different capabilities:

1. API scripts. These require a Pro subscription for at least the owner of the game they are used in. They run on Roll20's servers and can respond to a variety of events, such as chat messages, token movements, drawing on the canvas, etc. etc. They can manipulate characters and their attributes, but also graphics, pages, tables, decks etc. etc.
2. Sheetworker scripts. These are included as part of a character sheet. They have a much more limited range of capabilities - they are primarily designed to listen for changes made to a character through the character sheet, and then calculate dependent values. For example in D&D they might update a character's Armor Class when you change their Dexterity attribute. You cannot manipulate items on the canvas or respond to changes made there, and you cannot directly interact with the chat window. These scripts are usually run in the user's browser. Free users can take advantage of these scripts it they are included in a "published" character sheet included in the game settings list, but as far as I am aware, you cannot write and test a new character sheet (with or without sheetworkers) without a Pro account - unless something has changed in this regard recently?
   

Character sheets have no direct access to API scripts and they are in no way necessary to build a character sheet. Some character sheets do come with "Companion Scripts" that enhance their behaviour, however. In particular, it is common to have such a script make additional changes when a Roll Button is pushed on the sheet. For example, when you roll on attack from a sheet, a companion script might respond to the resulting chat output, detect that it was a ranged attack using ammunition, and decrement the number of pieces of ammo you have left.  Sheetworker scripts can't do this because they only respond to changes in a character's attributes - not rolls made from the sheet or any chat message that may result.

You can look at the 5e OGL character sheet made by Roll20 to see an example of a character sheet that uses sheetworkers. It also has a Companion Script so you can see the difference in its capabilities. As has been pointed out by others above, creating a character sheet that relies on a API script for basic function (as opposed to providing one for enhanced functionality) is not a great idea and unlikely to be accepted into the Roll20 repository.

Thanks all.

Yeah effectively before submission I hadn't realised that different users couldn't access the API sheet. On submission R20 informed me of the issues, so I'm looking for ways to improve the inline algorithms or if it was possible to simply port all of my API script to a text/worker. Effectively what the API calls did was some advanced calculation that is just easier in JS and also produced custom die and banners depending on the roll result. A lot is done on roll button pressing.

Perfect response Lucian. I hadn't really appreciated the difference between text/work and API.

"not rolls made from the sheet or any chat message that may result." - Being particularly important to my work.

My plan of action now it seems is.
1 - Add a toggle button to change between Free and Pro users.
2 - Update the code so it uses inline rolls in each location or API depending on the toggle.  (This would be enough to get basic functionality back in the system for all users, though I'm going to have to make a user guide due to some peculiarities.)
3 - Then look into how to use text/work to iron out the oddities.

Thank you again all.

Interesting you hadn't caught on to the fact with you having a free account.

Hi FistOfFun,

There's quite a lot of accumulated expertise around here on how to achieve different results with the various tools available to character sheet authors. Before heading down the Free/Pro switch route, I'd encourage you to share a few examples of what you're trying to achieve and see if the community has any suggestions for how to make them work. You may find that you learn a bunch of tricks that mean you can do almost everything without API functionality - which will give your sheet a bigger audience + make it less fiddly to use (only one thing to install).

For example a lot of the time it isn't necessary to have dynamic roll behaviour executed at the point of rolling. Instead you can have sheetworkers listening to relevant attribute changes and building roll expressions in hidden variables that are referenced by the roll buttons. For example. if you have a roll "MyRoll" that needs to be 1d20 + (either optional _modifier_1 or optional_modifier_2 depending on the state of Value3), then you can have a hidden input on the sheet for attr_my_roll_formula. Then you have a sheetworker listening for changes to Value3. It does some logic based on that value and sets attr_my_roll_formula to something like [[1d20+@optional_modifier_1]] or [[1d20+@optional_modifier_2]] respectively. The MyRoll button can then just include @{my_roll_formula} to output the right roll. This is a very simple example but obviously much more complex behaviours are possible using similar techniques. Please do post some of what you're trying to achieve and people can give you some tips.

 I'd also strongly encourage you to spend some time reading the code of some of the other major sheets like the 5e OGL sheet before you commit to any major design decisions. Roll20 character sheets are a somewhat unique coding challenge and you'll save yourself a lot of unnecessary heartache if you don't try and reinvent the wheel. I know that few programmers like reading other people's code, but in this case it really is worth it. Oh, and while you're at it, read TheAaron's scripts as well - you'll learn a lot about API coding that way (and probably a bunch of JS tricks to boot if you're not already a High Scriptomancer yourself)

Not knowing the game you're playing nor what banners may get show based on a roll, you could possibly use a roll template to display banners on a roll if the criteria are pretty straightforward and can be determined based on a rolled over or under sort of criteria.

@Andreas The projects a colab with a couple friends with Pro accounts we had just assumed that once committed it would be auto loaded when people select the sheet in the drop down.

Thank you all I appreciate it.

I managed to get tabs to work using hidden input (I think I saw that in the 5e OGL, which is amazing). Staring at some sheets can get a bit daunting depending on the logic. Thanks for the advice on TheAaron, I'll check it out. My JS is reasonable, but there is always more to learn.

Ah bugger. I've just had a look at the CSS wizardry page and some of the stuff I hadn't understood before (how to do minimums) suddenly makes a lot more sense, annoyingly it is going require a lot of hidden inputs to update the sheet. It would still be nice to get the switch working

@Finderski
That's how I currently display the banners, the issue being in the API script I monitor the number of the successes to update which banner is displayed. I'll have to look to see if I can do that in text/worker.