Need a Token? If your script needs to operate on/against a token, there are at least 3 built-in ways to get it, as well as at least 1 from a meta-script. I. Select Tokens If your script can work with tokens you select on the tabletop, you can select the token on the board and call the script directly. The message will contain data on the set of selected tokens that lets the script take whatever actions it needs to. There are limitations to this, however, as you can only select tokens which you can control. Also, the set of selected tokens (also called an array) only exists for a user-generated message. If your script launches *another* script (message A launches message B), then the downstream script will have no array of selected tokens. !sciptcard {{ --@spawn|_name... There, ScriptCards is being call by a user, so it will know about the selected tokens. But when it calls Spawn, that is a script sending a new message, so no array of selected tokens survive. In effect, Spawn has no idea what tokens are selected. II. @{selected|token_id} If your script can accept token IDs in the command line, you could use the Roll20 construct @{selected|token_id} to get it. This has the benefit of resolving more immediately than situations where you might not retain the selected token array -- for instance, a downstream API call as just mentioned. TokenMod is a good example of this kind of ID handoff: !outerscript ##run|token-mod --ignore-selected --ids @{selected|token_id} ... Imagine that outerscript represents a script that can launch other scripts using the "run" argument; we will use that to launch TokenMod. As in the previous, outerscript, called by the user, knows about the selected tokens. TokenMod does not. That doesn't matter since we can pass a token id to it. We can use the @{selected|token_id} formation because that is resolved as a part of the Roll20 parsing, before the outerscript message is handed off to the API. The limitations of this are fairly obvious... only the first selected token's information is returned, no matter how many you have selected. Also, the script to which you intend to feed the results of this call must be setup to expect an id on the line. It doesn't help to tell a script about a token if the script's parser doesn't know to expect it, or what to do with it! III. @{target|Target|token_id} Much like the @{selected...} construction, @{target...} can obtain the token ID of a given token to provide it to the command line of a script that expects it. The advantage of this is that it doesn't have to be a token you control. You can target any token and return the token ID. Also to your advantage is that it resolves as quickly as the @{selected...} calls, above, meaning the data is there for downstream script calls (where one script has called another). While target assignments lend some flexibility, they come with several trade-offs. First, it requires an extra click for each unique targeting statement. Second, all @{target...} statements are read and parsed, and the user is prompted for each of them, whether or not each of them are required for a given usage. Third, a command that contains a targeting statement DOES NOT contain an array of selected tokens, even if it is user-generated (note, the @{selected...} formations of II , above, do still work -- at least to return information about the first selected token). As an example: !scriptcard {{ --@alter|_target|@{target|token_id} ... There, AlterBars is going to be handed the id of the targeted token, and it will receive it in the proper argument to let it know what to do with it. Note, however, that in this case the outer script (ScriptCard) will NOT have an array of selected tokens available to it. Sometimes this will not matter. Other times, it very much will . IV. SelectManager (Meta Script) SelectManager runs as a meta-script, listening to every script call and for those that have an array of selected tokens, tracking those tokens. For an API-generated message (which doesn't have a selected array by default), it can, without user interaction, intercept the message and hand-off the array of selected tokens back to the message before that message reaches the intended-recipient API script. !outerscript ##run|token-mod --set name|Tacos With SelectManager installed, it tracks the tokens that are selected at the time that the OuterScript message is sent. When OuterScript calls TokenMod, that message doesn't have an array of selected tokens (as a script calling a script). SelectManager steps in first and quietly restores the token array to the message so they are there by the time TokenMod picks up the message. (It does not change anything about what is selected on the tabletop; it only tinkers with the message that the scripts are handing off, one to the next.) V. Virtual Selecting (SelectManager) SelectManager looks for syntax structures that tell it to build or add to the set of selected tokens. Since it is a meta-script, it runs before the intended recipient script gets the message: {& select ... } {& inject ... } Both take a comma-separated list of token names or IDs. The difference between them is that {& select ... } resets the selected tokens to nothing before adding the designated tokens, while {& inject ... } simply adds the designated tokens to the selected array. Using either of these formations can give back an array of selected tokens to a message that is lacking it. Note, these do not change what tokens are actually selected on the tabletop; they simply manipulate the message before it reaches the intended recipient script. This method can be a way to hard-code a set of selected tokens for a given macro (perhaps one that affects only the party members) so that the player doesn't actually need to select the tokens before running the command. They would be selected virtually for him/her automatically.
