[Script] APISelection -- A library for script developers to easily save persisted lists of ids, and share them between other scripts.

APISelection APISelection adds a simple interface for other scripters to use when creating scripts that operate on a persisted selection of objects, as well as sharing a list of selected objects across multiple scripts. At its heart, it is nothing more than a mapping from a&nbsp; string &nbsp;key, to an array of&nbsp; string s, with an interface to make manipulating those arrays easy. Public Interface APISelection has 5 public functions: getList( id ) &nbsp;-- Returns an array which represents that&nbsp; id . It will always return an array, even if nothing has been saved for that&nbsp; id . The returned array will always only contain strings. Manipulations of the returned array will not change the stored array. setList( id , list ) &nbsp;-- Sets the array for an&nbsp; id . The current array for the id will be replaced. Returns a copy of the stored array, as with&nbsp; getList( id ) . Only one copy of a value in the&nbsp; list &nbsp;will be retained, duplicates are removed. deleteList( id ) &nbsp;-- Removes the array for an&nbsp; id . Returns the emtpy array&nbsp; [] . removeFromList( id, list ) &nbsp;-- Removes the values in the&nbsp; list &nbsp;argument from the stored array for the&nbsp; id . Returns a copy of the stored array with the&nbsp; list &nbsp;arguments removed as with&nbsp; getList( id ) . addToList( id , list ) &nbsp;-- Adds the contents of the&nbsp; list &nbsp;argument to the stored array for the&nbsp; id . All duplicate values are removed. Returns a copy of the stored array with the&nbsp; list &nbsp;arguments added as with&nbsp; getList( id ) . Example Use on( 'ready' ,()=&gt;{ APISelection.setList( 'party-characters' , findObjs({ type :'character'}) .filter( ( c )=&gt; c.get( 'controlledby' ).length) .map( c =&gt; c.id) ); // ... let partyCharIds = APISelection.getList( 'party-characters' ); let partyTokens = findObjs({ type :'graphic'}) .filter( t =&gt; partyCharIds.includes(t.get( 'represents' ))); // ... etc }); Commands !api-selection Lists the current selection lists and their values. Mainly useful for scripters inspecting what is happening. Github Link:&nbsp; <a href="https://github.com/shdwjk/Roll20API/blob/master/APISelection/APISelection.js" rel="nofollow">https://github.com/shdwjk/Roll20API/blob/master/APISelection/APISelection.js</a> Support my work on If you use my scripts, want to contribute, and have the spare bucks to do so , go right ahead. However, please don't feel like you must contribute just to use them! I'd much rather have happy Roll20 users armed with my scripts than people not using them out of some sense of shame. Use them and be happy, completely guilt-free! Disclaimer: This Patreon campaign is not affiliated with Roll20; as such, contributions are voluntary and Roll20 cannot provide support or refunds for contributions.

Thanks to&nbsp; Kastion &nbsp;for prompting me to write it and providing the initial testing!

Interesting. May have to use this when I get around to rewriting easyxp

That would be a great place to use it.&nbsp; If a standard develops in the community for handling parties, that would be great.&nbsp; If you give it a go, try to think toward allowing multiple different parties to be created, with a given party being set to "active".&nbsp; I've been thinking about writing some sort of PartyManager script that would let you do just that.&nbsp; Maybe that needs to happen next as an interface to setting up the parties.&nbsp; It could swap lists into the 'active-character-party' list or some such, and other scripts could just operate on that list. Hmm.. Something I might need to add is a way to get a list of all defined lists. Would be pretty easy, I'll have to think about how/if that should be exposed. =D

Is this a script that end users will need to install as a dependency (like Path Math), or a tool for scripters to use within their own scripts?

A dependency, but easily managed through 1-click hopefully.&nbsp;

Nice! I don't see any use case for me, though :D.

Not yet, but maybe something will come out if it. =D

The Aaron said: That would be a great place to use it.&nbsp; If a standard develops in the community for handling parties, that would be great.&nbsp; If you give it a go, try to think toward allowing multiple different parties to be created, with a given party being set to "active".&nbsp; I've been thinking about writing some sort of PartyManager script that would let you do just that.&nbsp; Maybe that needs to happen next as an interface to setting up the parties.&nbsp; It could swap lists into the 'active-character-party' list or some such, and other scripts could just operate on that list. Hmm.. Something I might need to add is a way to get a list of all defined lists. Would be pretty easy, I'll have to think about how/if that should be exposed. =D Yep, pretty much how I was planning to use it. Now I'm excited to rework easyxp, maybe even into that party manager you mentioned. I might even see a use case for page navigator (once the text editor API issues are resolved).

Thanks again for putting this together The Aaron. I foresee getting&nbsp; a lot of use out of this. My Character List script makes extensive use of APISelection already. Do you have any intention of making a list of commands available in-game or do you intend to leave this solely as an API dependency for use within other API scripts? Example: !selection delete character-party !selection add character-party -LEWlKUgYOARwMZHy3sp !selection remove character-party -LEWlKUgYOARwMZHy3

For now, I see this as a something of a library module that other scripters can use.&nbsp; The only command it has is really intended mainly for assisting development.&nbsp; Currently, it's really just a persisted map of sets of strings.&nbsp; As Jakob implies, someone that has experience with the state could write something custom for their own scripts without much effort.&nbsp; I think the real value in this as a module for other scripts will be in the way it can be shared.&nbsp; The idea of a PartyManager to manipulate an 'active-character-party' is a good example.&nbsp; Scripts could start using the this as the single source of truth for which characters make up the party.&nbsp; Having a consensus that APISelection.getList('active-character-party') gives the list of all characters that are currently adventuring means that the end user doesn't have to configure who's in the party separately.&nbsp; For example, all of these could share the same configuration of party: An XP calculator script An encounter builder script A "move the party here" script A "what's everyone's passive perception" script&nbsp; A "money manager" script A "apply spell effect to only monsters" script A "roll default hit points" script A "apply trap on PCs only" script A "teleport pad" script etc Even scripts like TokenMod could take advantage of this: !token-mod --set statusmarker|+blue --active-party And that's just talking about an active-character-party list.

I think the next thing I'm going to add is observing changes, so that scripts can be notified if a list they care about is changed.

Scott C. said: Yep, pretty much how I was planning to use it. Now I'm excited to rework easyxp, maybe even into that party manager you mentioned. I might even see a use case for page navigator (once the text editor API issues are resolved). It's probably better to have that PartyManager as a separate script.&nbsp; That way people who don't use experience, or use it differently, or don't want that functionality can still take advantage of it.&nbsp; =D

The Aaron said: An XP calculator script A "move the party here" script A "what's everyone's passive perception" script&nbsp; A "money manager" script I never stopped to think of the possibilities this script opened up beyond the original intentions I had for wanting it. I have a GM-Read-Only handout of CR / # of PCs / XP tables that I could move over to APISelection. Also Passive Perception is something I REALLY need to setup ASAP. I'll be working on something for the 4 listed examples in the quote for sure.

Cash Master could be easily updated to use a ground truth party if available. At present, it has its own data in State, but keeping the user from having to reconfigure it would be great. If you can create default lists like this, you might be able to have a faction manager and once you have that, an AoE script might be feasible.

Hmm... FactionManager... me likey.&nbsp; &nbsp;Do you mind going into a bit more detail about how you see that being used, just so we capture the idea in case somebody writes one...

Basically, the idea was that you would create multiple groups using APISelection, and FactionManager would treat them as independent factions.&nbsp; Presumably, you could nest one category within another, or maybe just go the C++ route and have multiple inheritance.&nbsp; Then, if you were to do something like, say, deal 8d6 damage to all Elven Archers in a 20 foot radius, it would hunt through for all nearby creatures for things that are both elves and archers, regardless of whether they are individually named hero units or not. FactionManager might also be able to allow you to see the vision of units ranking beneath you.&nbsp; Say you're in a mass combat situation; you want to be able to see what your 100 grunts do so you can appropriately command them. Because this is API and not UI, you could also have a deeper hierarchy than what the folder nesting allows, which would be AMAZING for tracking what units are where and belong to which organization and are in which city. Maybe FM would also track reputation or rank somehow? (tbh, it wasn't a terribly defined idea lol, mainly just a string of vague wishes)