Confirmation on what's possible with macros and api scripts

I looked around but most of the information is a few years old so I just want to confirm 2 things:

- It's not possible to call an api script from a macro? Unless doing macro -> chat message -> api script listening for a chat message

- It's not possible for an api script to return a value to a macro? Specifically what I was trying to do here is have a roll query call a macro which would then call the api script with some parameters and the api script would return a value which would end up being used in a roll template.

This might be vague, if needed I can provide an example as to what I'm trying to do.

The former is absolutely possible, and is the basis of an awful lot of macros. It is common for instance to put API calls into an API command button, and call that from a macro, either by itself, or within a Roll template.

The format for an API Command Button is:

[name of button](!some API command)

As for the latter, I'm honestly not sure, but I don't think so. I think the macro has to resolve and then an API command is or is not sent as a result of the macro. I don't think that the macro can run part of itself, resolve an API call and then act on it.

Keith is pretty much spot on.

The API is Event Driven, the only way to interact with it is to cause some event which it listens for and responds to. The most common event for it to respond to is the chat event. Any chat message causes an event, but usually an API command is used for making an explicit request of an API script. There is not some way of making a direct function call or anything. (You can think of API command messages as a poor man’s Remote Procedure Call (RPC), if you’re familiar with that.)

Interacting with an API script is purely forward, it does not return any values (as you can’t call it directly so there’s be nothing to return it to or from). API scripts can only change the general state of the game, and allow those state changes to propagate to all the clients. The API is asynchronous. Everything in a Macro/Ability/Chat Command gets fully evaluated in the client before the API even sees it. That’s all inline rolls, all roll queries, all macro and ability references, etc. the API will see the data from these (what was rolled, how it was modified by options, which roll template is being used, etc.), but the evaluation has taken place. Any sort of back and forth dialogue between the macro and the API will need to take place across multiple events. Often it’s easier to just implement the logic in the API script and use the macro for gathering the initial input. For really complicated things, having the API whisper further queries to the user that caused the event and continue with their answers is the best way to go. 

I don't think an API command button is what I'm looking for, ok let me go into specifics to see if there's a way to do what I want to do. I have a custom character sheet and when rolling an attack there are multiple possibilities, the attack can hit, miss, dodge or critical. Right now the way I'm doing it is rolling 1d100 for the hitRoll and then I calculate the hit threshold and the dodge threshold. All of that is sent to my roll template which then determines if the 1d100 result was a hit/miss/dodge/critical.

For example:

hitRoll = 50

hitThreshold = 75

dodgeThreshold = 85

Using the helper functions of the roll template such as {{#rollBetween()}} the roll template determines the result of the attack, 1-75 is a hit, 76-85 is a dodge, 86-100 is a miss. Then the critical comes in but no need to talk about that I think you get the gist of it.

Now, I would like to find a way to replace this whole thing by having an api script that would return either hit, miss, dodge or critical which could then be sent to the roll template. The main reason being it's much more simpler to do this logic in javascript than in the roll template and would be cleaner because it avoids the necessary repetition that I have in my roll query.

API command button would probably work, but can the roll template react to the result? Or would the api script have to output a message to announce the result HIT/MISS/DODGE/CRITICAL

What you might look into is bypassing the rolltemplate altogether, and have your sheet button send an API script message, and write a script to catch that message, and perform all the calculation and formatting you need. 

You might be able to avoid writing your own script - maybe the Power Cards script does what you need.

It may help for you to understand that all a macro is, is a series of chat commands that you have entered prior, and can now call up with a shortcut.  The macro is not a program, it simply silently dumps its contents to chat, and chat executes what it finds.  A macro functions exactly like you just typed in its contents, or perhaps pasted its contents from your handy dandy text editor.

Meanwhile, an API is a scripted program that is running as a separate process alongside roll20, and can look, listen, output, and generally interact with roll20 as if it was a user, just an artificially programmed one.

More or less.

Thanks for the replies everyone I'll stick with what I have for now, power cards seems useful I'll keep it in mind.

I think one way to do what I want would be something like this:

- Have the roll query do a chat command with a bunch of parameters that my api script will listen to

- Have an empty roll template so it doesn't generate anything in chat (not 100% sure about that one)

- Api script would do the calculations and then do sendChat using /direct to format it just like my roll template

Which also has disadvantages (maintaining html in the api script) but would work, I'll stick with what I have for now :)

Well, you don't actually need direct. API sent chat messages use inline css/html without issues, but more importantly, it's actually simpler than that:

• Have your roll button on your character sheet just be an api command (e.g. !roll ?{your query parameters answers here|option 1|option 2})
• Have your script react appropriately to the message, then use send chat to send the answers directly in the roll template (e.g. &{template:sf_generic} {{title=...)

That does exactly what I want thanks! I didn't realize the roll template is simply a chat message (it's actually written in the first few paragraphs of the roll template wiki page).

I think I understand everything better now, everything goes through chat essentially.