[Help] API Development questions

I would like to go Pro for the API so that I can customize things a bit more easily (I am in a group that uses several homebrew rules...), but I'm curious about a few things first. 1 - I'm a web developer by trade (though ASP, not as much js), and I've been poking around the DOM/js for the site. I understand from posts that none of the sheet javascript is exposed, and it is all sandboxed, right? I understand the security issue there, but I'm worried about testing code that I put in as sheetworker js, and that it won't be debuggable. I'm trying to wrap my head around how to develop without ready access to the js. 2 - Currently there are several API scripts for creating mobs, but very few that access the character sheet itself. I would be only interested in an API script that worked with the sheet. What is so difficult about working with the sheet in the API?  To specify, I mean all the API scripts I've seen work with the Ability/Attribute section, not the character sheet section of a character.  Considering all of the benefits of the latter, I would have assumed it would be preferred... Thanks for any and all help.

Hi Jeremy! &nbsp;I'll see if I can clear that up for you. There are two distinctly different sections where you can write custom Javascript: Sheet Workers -- This is embedded into a character sheet and executes in a Player's browser. &nbsp;Though sandboxed, it operates very much like traditional javascript on a web page. &nbsp;You can use console.log() statements to write data to the browser's javascript console, and if you're clever about it, you can even set break points and step through inspecting variables. &nbsp;(If you're using Chrome, you can use the special debugger keyword to force a breakpoint.) &nbsp;Sheet workers are event-based and do not have access to any DOM elements. &nbsp;They can be used to adjust the values in Character sheet fields only. &nbsp;Any changes they make are seen by the system as if the player made those changes. See:&nbsp; <a href="https://app.roll20.net/forum/permalink/2637617/" rel="nofollow">https://app.roll20.net/forum/permalink/2637617/</a> See:&nbsp; <a href="https://wiki.roll20.net/Sheet_Worker_Scripts" rel="nofollow">https://wiki.roll20.net/Sheet_Worker_Scripts</a> The API -- This is executed in a sandbox on the API server. &nbsp;Learning to write API scripts can be a little bit frustrating if you come from a DOM background, as there isn't even a page. &nbsp;(If you've written node.js, it's probably going to feel somewhat similar.) &nbsp;The API is also event-based, and can respond to a wide range of changes to the game (moving and otherwise manipulating tokens, updating characters, changing map pages, rolling dice, typing commands, etc). &nbsp;There is an embedded log panel on the API page where you can write messages using the built in log() function. &nbsp;The API can manipulate the properties of all the objects in the game (tokens/graphics, chat messages, rollable tables, characters (effectively, the first tab), attributes and abilities (effectively, the second tab), etc). &nbsp;Their changes do not cause events in other places (with the exception of writing chat messages). See:&nbsp; <a href="https://wiki.roll20.net/API:Sandbox_Model" rel="nofollow">https://wiki.roll20.net/API:Sandbox_Model</a> See: <a href="https://wiki.roll20.net/API:Objects" rel="nofollow">https://wiki.roll20.net/API:Objects</a> See:&nbsp; <a href="https://wiki.roll20.net/API:Events" rel="nofollow">https://wiki.roll20.net/API:Events</a> See:&nbsp; <a href="https://wiki.roll20.net/API:Debugging" rel="nofollow">https://wiki.roll20.net/API:Debugging</a> Also, some clarifying background: Character Sheets --&nbsp;By and large, character sheets are merely a visual representation of attributes and abilities (there is a bit more with repeating groups and rolls, but this is generally true). &nbsp;All of the fields of a character sheet ARE attributes on the character. &nbsp;This is why the API scripts manipulate Attributes instead of the character sheet. See:&nbsp; <a href="https://wiki.roll20.net/Character_Sheets#Building_" rel="nofollow">https://wiki.roll20.net/Character_Sheets#Building_</a>... Hopefully that clears things up. &nbsp;Definitely post back if you have more questions or want to talk about anything in more detail!

Thank you for the response Aaron! Yes, that helps a lot. &nbsp; Sheet workers not having access to the DOM at all, but manipulating items on the sheet? &nbsp;Interesting. &nbsp;I've seen in other posts that you can't do automated things like creating a character or advancing one with sheetworkers (and this is a separate question, but something that one of those links brought up...) but what about templating a creature? &nbsp;I'm thinking augment summoning/celestial template as a checkbox type thing. &nbsp;Would that be doable? I've been through all of the API docs on the site, and although I don't know about the API page yet, I can see what you are saying. &nbsp;I've never worked with node.js before, so I'll have to give that a shot and see what I can make of it. &nbsp;This seems to be what I need to be focusing on. &nbsp;I don't think there's a lot of sheet options we would need to change, it might be all manipulation for rolls and tokens. &nbsp;I'll have to draw up some plans first. Thanks for the clarification. &nbsp;I did notice that a lot of the character sheet attributes did appear on the attribute page after filling it in, but what got me curious was that it didn't change the other way around (I changed an attribute value on the last page, and it didn't change the relevant box in the charsheet...). &nbsp; Is this supposed to be a two-way link? &nbsp;Should there be some refresh button or something that I can use to sync the box values? edit: word clarification.

You could definitely apply a template (in the D&D3.5 style) with Sheet Workers, provided you had some way of telling it which one. A checkbox change could trigger an event where you could adjust attributes as needed. You could also use a select box if you don't need more than one template active at a time.&nbsp; Sheet Workers are not well suited to making characters as they don't have a means of prompting the player. You could probably create a random NPC maker, maybe have a form tab with some inputs to seed the system.&nbsp; As far as the API being similar to programming Node.js, just understanding the process is probably sufficient; no need to become a fully qualified Node engineer or anything! Fields on the character sheet are backed by attributes except in a few important cases: &nbsp;1) fields with default values won't have an attribute associated with them yet. 2) auto-calc fields don't have an attribute. Other than that, changing one should change the other. There may be an issue with case, or you may have the attribute twice for some reason (and it's looking at the other one).&nbsp; If you wanted to make a character builder, the API would be the place to do it. For personal use you could build in any details you wanted. If you decide to share the script you'll want to separate any copyrighted information into data files and not share those. Check licensing for your game to be sure.&nbsp; Cheers! &nbsp;Let me know if you have more questions!

Thanks to an incredibly nice GM who gave me temporary GM access to a game with pro and the API, I have been playing with API scripts, and I have just one more question - You mentioned specifically that changing attributes through API doesn't call sheet worker change events, right? Is there any way to call a change even from the API? &nbsp;Specifically a way to call a "recalc" on the pathfinder sheet? I'm running into the issue that I suspect most people who have tried this have run into - I can set the backing fields, but the auto-calc fields don't auto-calc, and that messes with some of the calculations, and forces the player to re-confirm something on the character sheet for values to "stick" and macros to work. If there's any way around this problem, I'd love to hear it!

So, autocalc fields should be able to be evaluated via sendChat() in the API. If the ALI sets an attributes, autocalc fiends should be up to date, at least for calculations.&nbsp;

I'm sorry, I accept that perhaps they should, but some of them aren't. &nbsp;Specifically, in the pathfinder sheet, I'm having to go in and adjust a field just to get things like AC, perception, Init and attack modifiers in the repeating sections to update. &nbsp;The AC isn't as big a problem, but the init and perception are driving me crazy. &nbsp;Perception is an auto-calc, it seems, but also, when changed, seems to have a straight backing field. &nbsp;I can set that attribute in the API, but if the sheet re-calcs, it overwrites the attribute. &nbsp;While that may be expected, the field still doesn't calc until a change call is made to the sheet, making any auto-set futile. &nbsp;What is most annoying about this, is that after the sheet is recalc'd, you can set the backing field of perception to the total, and it won't change. &nbsp;There seems to be a "dirty" setting to the field, and when changed on a manual input, that isn't set, but when done through API, it is? &nbsp;What really makes a difference is the repeating section, where bonuses aren't always apparent. &nbsp;Here, even after I set BAB and Attributes, the repeating weapons section reads '0' in the base attack. &nbsp;Once I tab over base attack, or I adjust some other field the entire sheet recalcs, and the values are good. &nbsp; After reading over what I've written, I'm probably just missing something simple and basic. &nbsp;I'm getting frustrated, only because some parts work so well (attributes, text fields and size for instance) but others are causing tremendous problems. &nbsp; Thanks again for all your help. &nbsp;

Ah, I see. &nbsp;When you're saying "auto-calc fields", I think what you mean is "Sheet Worker Calculated fields." &nbsp; Auto-calc fields will have in them the text representation of the calculation: &lt;input type="number" name="attr_StrModLeveled" value=" @{StrMod}+@{Level} " disabled="true" /&gt; They are evaluated when used, so: /em hits savagely with his axe for [[ 1d12+@{StrModLeveled}]] is calculated correctly. &nbsp;When accessing this from the API, you would get the string "@{StrMod}+@{Level}", and would need to use sendChat() to get it's value: sendChat('','[['+StrAttr.get('value')+']]',function(msg){ /* use the value in msg.inlinerolls */ }); See:&nbsp; <a href="https://wiki.roll20.net/Character_Sheets#Auto-Calc" rel="nofollow">https://wiki.roll20.net/Character_Sheets#Auto-Calc</a>... What you are describing sounds more like a field that is being calculated by a sheet worker. &nbsp;In that case, the logic for calculation is entirely in the javascript in the character sheet. &nbsp;For those input fields, the calculation is performed based on some event defined by the sheet worker. &nbsp;In the case of the above, there would likely be something like: on('change:strmod change:level',function(){ /* update StrModLeveled */ }); &nbsp; ( Note : Attribute names for events in sheet workers must be lowercase, regardless of the case of the attribute. ) This function will get called for one of two circumstances (as applied to either of the attributes StrMod & Level): 1) If a player loads the character sheet and makes a change to the attribute. 2) If a sheet worker makes a change to the attribute. See: <a href="https://wiki.roll20.net/Sheet_Worker_Scripts#Event" rel="nofollow">https://wiki.roll20.net/Sheet_Worker_Scripts#Event</a>... I'm not aware of a way to cause sheet workers to run when an attribute is changed by the API. =(

That was exactly what I wanted to do (run a sheetworker on api change). Sad that it can't be done. From my perspective then, I need to build this into the sheet, then I can call sheetworker from within the sheet. Thanks again for all the help, and maybe the devs can consider adding sheetworker calling functionality to the api at some point to make this easier? &nbsp; If that's even possible.&nbsp;

I'm sure it is possibly, but it probably wouldn't be easy, mainly because you'd have to introduce cycle detection (Sheet worker change causes API change causes Sheet worker change causes API change causes ...). This does seem like it could be a bit of a problem for heavily sheet workered character sheets and heavy api use. &nbsp;If you're using an API script to set some bonuses on a character because of a spell, and then using a sheet attribute in a macro which should have that benefit calculated but doesn't because there was no event for the change from the API, it could be a problem.