Need Architecture Advice for API Script

I'm looking for advice on how to architect the following functionality. I don't need specific code per se. I'm instead looking for advice on the best (good enough?) way to assemble/architect all the pieces. I feel I have enough coding experience to be able to bang all the bits into place, but I'd like advice on how to assemble it all in the best way, keeping in mind possible extensibility. Any advice is appreciated and THANK YOU in advance. I'm building a tactical combat simulator in Roll20. Each combatant is represented by a character sheet and a linked token on the map. At intervals, players will work off the initiative order to declare targets for any/each of their weapons. All weapons are ranged  weapons, listed in a repeating list on their character sheet. Each weapon may be targeted at a different opponent. Players with higher initiative declare their targets after those with lower initiative. The chance to hit any given target is based on the target's range (in hexes) and a firing table. The latter determines the odds of a hit at each range as well as the maximum range for a possible hit.  After all targets are declared, fire is simultaneous.   Here's what I'm thinking the API script should do: The player targets each weapon by clicking a 'target' button in each attack's repeating row on the character sheet. The button click triggers the API script. The API script works off the field data from the character's repeating row. This contains the firing chart designation (represented by a single letter). The script asks(?) the player to select the target for the attack. [ What's the best way to get this info? ] The script determines the range based on the position of the character's token and the target's token. The script then determines the attack's to-hit number from both the attack's firing chart and the range to the target. An attack ChatMenu.js string is generated. This will contain other repeating row field names and values, such as weapon name, damage, etc. This string will be saved  to the character sheet in a hidden field. The name of the target's token will also be displayed in the attack's repeating row, for the player to reference. After all players have declared all their attacks, in game terms, fire is then conducted simultaneously. This is accomplished by each player working through their list of targeted attacks and rolling the attacks one at a time in any order they prefer. To accomplish this, each player clicks a 'fire' button  in each targeted attack's repeating row on the character sheet. This then sends the above generated ChatMenu.js string to the Chat, the attack die is rolled, and the sheet's roll template takes care of the rest. Questions: What's the best way to architect this? Are there better ways to do it than my pseudo-architecture above? What are some of the key architectural elements needed, in the sheet, the API, etc.?

One note on gameplay before I make suggestions about structure... If you're creating this system (and therefore have some flexibility), can I suggest regarding the attacks either some sort of "cycle" mechanic (i.e., a reload or cool down period before the weapon can be fired again) and/or a "bandwidth" mechanic (requiring the player to allocate their offensive capacity... not every weapon can be fired every turn... i.e., this weapons platform can output 100pts of attack per turn, and the user has to decide how to divide that between weapons that require different amounts)? The purpose being that if every turn is "everyone fires everything" then the only tension is reducible to who rolls better and how many bad guys are on the field. On the other hand, a cycle mechanic and/or a bandwidth mechanic creates the requirement of strategic planning and a risk/reward structure to the player's own agency. IOW, the player feels like they can contribute to their chances of winning. Also, a note on script + API integration... It's generally suggested, when you're building a sheet, to not require a script in order to play the system if you're going to release the sheet/script publicly since only Pro users will be able to start a game that can fully implement both (scripts being a Pro perk). However, for some of the things you want to do (that will also survive the process of incorporating suggestions from experienced sheet devs and script devs), you are likely going to be in the realm of requiring a script. For instance, a sheet dev can correct me if I'm wrong about this, but sheets can't determine range between tokens. OK, all that said, here's my general feedback... 1) Targets are (probably) going to have to be gathered via Roll20 @{target} syntax... which means a command line that triggers a message that needs to be caught and parsed... which means a script. That command is going to have to be USER INITIATED. If you want to understand why, you can watch the first 15 min of  this video  (or watch the whole thing if you want to understand metascripts). That means your process will probably be to send a command to the chat (either from the sheet or be having the sheet send a button to the chat output that the user then clicks on), the command line is set to be picked up by your script but prompts the user along the way for the targeted token. 2) You keep mentioning ChatMenu.js... which I'm guessing refers to a script named that? (guessing because there isn't one in the one-click repo that is named that, so maybe this was a bit of code your saved off of the forum/discord somewhere...?) Chat menus can be made without a script, and those menus can even include buttons that fire commands which trigger scripts to run. The vehicle for this is a character sheet template, so since you're already building the sheet (it sounds like), you can do a lot to control the look of the presentation just by building the template the way you want, then populating it with lines and information and buttons to control the various actions you need to incorporate. Bottom line: building a dependency on your own script is already putting you into niche territory; I would suggest *against* also relying on someone else's chat-menu-producing script. That code might change (if it does come from the 1-click) or other people might have it installed but a different/newer version. Either construct your layout as your own template stored in your sheet, or build your script in such a way that it can construct the layout on the fly. 3) YMMV, but I don't like storing ephemeral information in the character sheet. The sheet is for character (or, in this case, weapon platform) data. Separate from that, you have data connected to the fight (really just the turn). Again, it might be just me, but I don't like storing that sort of information in the sheet. My preference would be to share the confirmation of targeting-per-system to a chat menu. The overall flow (imagining a cycle and/or bandwidth mechanic involved, too) I would see would be something like...: ...weapon systems are "enabled" (for inclusion in the attack) on the sheet via a checkbox ...when the Turn Order event is detected, a script checks every player-controlled character sheet and decrements every weapon's "cycle" counter by 1 (or whatever metric). Maybe a weapon can fire once every 5 rounds, so when it fires it gets a "5" in this field. On every Turn Order event, that number is decremented until it reaches "0" and the weapon is ready to be fired again. ...that same code handling the Turn Order change event can now send a whispered message to each sheet controller alerting them to the status of their weapons (enabled, available, or unavailable (cycling) for X more rounds). Each row is a weapon system, and that row has a button to handle enabling/disabling a system for inclusion in the next attack (changing the value on the sheet). The user can configure what is enabled (and the script can report if the amount of attack comes in under the bandwidth limit, if you employ such a mechanic). The script can even monitor (using the messages these button clicks would generate) whether the player is under the bandwidth for the attack so that the targeting phase can begin. The total bandwidth would be those weapon systems that are both enabled AND which sit at "0" as their cycle value (e.g., they are not "reloading"). At the end of the enable/disable phase, the player clicks a "Ready" button. ...the resulting message is a chat button ("Attack!") pre-prepped to be ready to ask for targeting information for each enabled weapon system. If the sheet had four weapon systems enabled, each system would a target designation portion of the line. Maybe the script has already read that System A takes a single target (one targeting statement), while System B can target two (2 targeting statements). The user clicks this button and answers the target requests. ...the resulting message consults the appropriate chart, does the distance calculation, and rolls for damage, presenting it all in a public chat of the results. What you should notice about this approach is that the only data that needs to be tracked/changed on the character sheet is whether the system is enabled or not and how much longer it might be in a "cycle/reload" state. Everything else is handled through chat, tracking the ID of the weapon system in the command line, and passing that back to the script answering the message. Since the only 2 things changing are the "enabled" and "cycle" values, if you don't implement either of these mechanics, you don't even have to worry about this part! The point is, all of the ephemera of the targeting, etc., need not be stored on the sheet. In fact, there are many people who don't like to use a sheet -- especially those who only have a single monitor and limited screen real estate. These are just some random thoughts based on what you posted. If you have any questions or if something wasn't clear, just post back and I'll try to explain more.

First of all, thank you for the thoughtful reply. I really appreciate it!  If you're creating this system (and therefore have some flexibility)... The game system is FASA's Star Trek: Starship Tactical Combat Simulator , a game was last updated in the late 1980s but has survived on the internet over the decades. It has mechanics for power allocation to ships systems (including weapons) and then a 3-phase-per-turn mechanic for movement, targeting, and weapons fire. It's generally suggested, when you're building a sheet, to not require a script in order to play the system if you're going to release the sheet/script publicly This sheet is not intended for public release . I have a long-time group of RPG/Wargamers, and we decided to give ST:STCS a go. I am very open to "working outside the box" to get this done. Targets are (probably) going to have to be gathered via Roll20 @{target} I was thinking of having the player select the target token on the map and then click a "targeted" checkbox on the weapon repeating item to fire off an API targeting script. The script could get the object info in that manner. The name of the targeted ship would then be displayed in a text field in the weapon row to confirm the selection. This is also when the range to target and to-hit number would be calculated and saved to the hidden field. Possibly some trigonometry to determine which target hex-side is impacted (which determines shield defense and damage chart selection) Repeat for each weapon. Then move to the next player in initiative order. You keep mentioning ChatMenu.js... Ah, yes, this is GiGs awesome Universal Chat Menus script I found in the forums. IMO, it allows me to easily output very nice tabular formats to represent data. Again, since this sheet isn't intended for public consumption... I don't like storing ephemeral information in the character sheet I appreciate this and myself don't like the idea of inserting the upcoming roll data in a hidden field. However, since firing each weapon comes later, it would (IMO) simplify everything greatly if the roll is "pre-created", stored on the sheet, and then sent to Chat at the appropriate time (when an action button is clicked). The Chat script would roll the attack die, determine hit location, and a roll-template would take care of the rest. - I'm still open to further analysis and consideration on this approach... I'll add to this thread as I begin implementation in case you or anyone else is interested and/or has additional thoughts. I'm trying to learn as I go and appreciate the input! (And I know my players do, too!)