How can I make an API script return a value for use in a larger macro?

I want to minimize the use of the API and do as much work as possible in macros. This is to allow the character sheet I'm modifying to work even for non-subscribers by substituting the API bits with less convenient but still functional macro substitutes, like replacing an API function to find the range penalty with a query asking the user for the range to their target. This also allows users to modify the macros to handle stuff like houserules or rules exceptions without needing to dig into the API. However, I don't know how I can make an API function that simply returns a value to a macro, rather than sending a message to the chat (and thus needing the entire line to itself). For example, {{attack= [[@{skill} + !rangepenalty + ?{Modifiers|0} - 3d6]]}} where !rangepenalty is an API script that just returns a number like -4 for use in the macro. How would I go about this?

Unfortunately, API commands don't work like that. Messages are only of type "api" if the entire line starts with !, and if the message is an API command, it will only be processed by the API. You can create an API script which performs operations on messages that aren't API commands, however the original message will already be in the chat by the time the script does anything. An example that you can look at is my Exalted Successes script; any chat message which contains a d10 roll will trigger the script, and then the script will post a message to chat ( after the original) with the number of successes.

Hmm. Would it be possible to start a a line with "!api" and then follow it with the entire macro, then substitute keywords from that macro with values, then output it?

The answer is "yes", but the question is overly simple. More specifically, you can write !api to do just about anything you want, and it gets anything you pass it, so you can pass it anything and have it output about anything. However, that probably doesn't really answer your question very well. Something like this will send whatever is passed to !api to the chat, but there is a bunch more code that needs to be added to make this something useful. on('ready',function(){ 'use strict'; on('chat:message',function(msg){ var cmd; if('api' !== msg.type) { return; } cmd=msg.content.split(/\s+/); switch(cmd.pop()){ case '!api': sendChat('The !api Show!', cmd.join(' ')); break; } }); });