InsertArgs: Substitution Script with Custom Replacement Hooks

Stop me before I go too far; I might be replicating existing functionality. Then again, as I'm new to R20 and maybe don't know all the ways people typically use it, tell me if there is more that could be done. :-)

I wanted a script that could let me modify parameters for an ability on an ad hoc basis (see below for why I wanted this). So, the implementation of this would look like:

{an ability} ==> [has replaceable parts ("hooks")]
{the script} ==> [has functions that process values for those hooks]

Straightforward. In practice, it would look like this... take an original ability like:

OriginalAbility:
    !some_script --arg1:The Value --arg2:Another Value --arg3:So much value

If that ability also accepted a "target" argument that would parse a list of token IDs separated either by space or by comma, you might at times need options like:

    !some_script --arg1:The Value --arg2:Another Value --arg3:So much value --target: @{target|Target 1|token_id}
    !some_script --arg1:The Value --arg2:Another Value --arg3:So much value --target: @{target|Target 1|token_id} @{target|Target 2|token_id}
    !some_script --arg1:The Value --arg2:Another Value --arg3:So much value --target: @{target|Target 1|token_id} @{target|Target 2|token_id} @{target|Target 3|token_id}
    ...

    !some_script --arg1:The Value --arg2:Another Value --arg3:So much value --target: __target__

    !insertargs --load:OriginalAbility --__target__:[...]

gettargets(#)
targetsel()

!insertargs --load:OriginalAbility --__target__:gettargets(?{Targets|1})

API Call: Call it using either "!insertarg " or "!insertargs ".
Arguments: Structure your arguments as " --key:val" pairs.
        key: your next hook
        val: how to replace that hook
Special Arguments: The first argument tells the script how to operate.
        key: "chat" or other
        val: name of Ability to operate on

That's definitely interesting!  I'll have to read it more thoroughly later. =D

That would be great! I was hoping to ask you about the line that is rem-ed out near the end of the handleInput function... I picked that up from one of your suggestions elsewhere, but I'm not sure what the |$1 is doing near the end. I know that the line as you suggested it would replace character specific references, which might or might not matter for this one... again, inexperience with the R20 objects coming through. I didn't want to implement it before I understood what that end bit was doing and could decide if it would matter.

Other things I'm looking at...

...right now it sends as the player/character who sent the initial !insertargs call. Is there call for something else?

...right now it detects implementing a function just by the presence of parenthesis, which isn't helpful if you wanted to pass through a string containing a paren. So... probably a more robust parse or test of that part?

...the two functions I have right now have a space hard coded into the output of the chained IDs. Maybe let the user supply a delimeter in the arg structure: gettargets(3,",")

A Use Case

I am adding a targeting option to my Hero Roller script. The output will use the images of the targeted tokens to report information specific to that token for the attack. It should look like this:

I have 8 separate Abilities (as part of a character's martial art) that might need me to designate 1 (or more) targets every time I use them. And those targets could be @{target} calls or the set of @{selected}. I might also want to independently assign a game-specific "location" to the attack to drive damage multipliers. That's... a lot to maintain... or alter... or produce as API buttons.Instead I edit each ability to change those arguments to hooks. For example:

!heroll --d:3.5d6 --t:k --pn:Way of the Circle --col:@{Heretic|color1} --n:area effect 4m, selective, -1 OCV per Target to all Targets --tgt:__tgt__ --loc:__loc__

And then I create ONE Ability that lets me pick between those 8 Abilities, feeding the substitutions as necessary:

!insertarg --chat:?{Choose Power|
                        Charity,WayOfCharity|
                        Mountain,WayOfTheMountain|
                        Wind,WayOfTheWind|
                        River,WayOfTheRiver|
                        Briar,WayOfTheBriar|
                        Leaf,WayOfTheLeaf|
                        Edge,WayOfTheEdge|
                        Circle,WayOfTheCircle}
           --__tgt__:?{Choose Targeting Method|
                        Selected,targetsel()|
                        Targeted,gettargets(?{Targets|1})}
           --__loc__:?{Location|
                        None|
                        Random|
                        Head|
                        Shoulder|
                        Arm|
                        Hand|
                        Chest|
                        Stomach|
                        Vitals|
                        Thigh|
                        Leg|
                        Foot|
                        Focus|
                        Headshot|
                        Highshot|
                        Bodyshot|
                        Lowshot|
                        Legshot}

Now, if you're paying attention, you probably caught that the location parameter could have been accomplished as a query in each of the specified 8 Abilities... but that would then be 8 places I would have to touch to update should the query change. Doing it this way gives me 1 location to make a change that affects ALL the Abilities called.

I have achieved... ONE ABILITY TO RULE THEM ALL.

I shall diminish. And go into the west.