Version 0.1.5 | © 2025 Mord Eagle · MIT License Lead Dev: @Mord-Eagle
GameAssist is a Roll20 API modular Framework: one script that drops into your API sandbox and spins up a guarded event-queue, metrics board and watchdog. Currently it has six bundled modules—Config UI (GM chat controls), CritFumble, Concentration Tracker, NPC Manager, NPC HP Roller and Debug Tools (GM-only, disabled by default)—that hook into that queue, giving you automated fumble tables, concentration checks, death-marker hygiene, one-click HP randomization and on-demand diagnostics. Hot-reload, per-task time-outs and state audits let you run marathon sessions without reloading the sandbox.
| Category | Highlights |
|---|---|
| Core Lift | Serialised queue, per-task timeout, watchdog auto-recovery, state auditor, live metrics. |
| 30-Second Install | ① Paste GameAssist.js ② One-Click TokenMod ③ Add seven roll-tables (list below) ④ !ga-status = green. |
| Flagship Player Commands | !concentration, !cc, !critfail |
| Flagship GM Commands | !npc-hp-all, !npc-hp-selected, !npc-death-report, !ga-conc-status, !ga-config ui |
|
| Admin Controls | !ga-config list\|get\|set\|modules\|ui, !ga-config-ui, !ga-enable, !ga-disable, !ga-status, !ga-metrics, !ga-debug |
| Safety Nets | FIFO queue + watchdog + auditor → zero silent failures. |
| Extensibility | GameAssist.register('MyModule', initFn, { events:['chat:message'], prefixes:['!mymod'] }); |
| Backup Utility | !ga-config list produces a hand-out containing the full JSON config. |
!ga-debugcommands require enabling the DebugTools module first (!ga-enable DebugTools) and remain GM-only.
Required Roll-Tables: CF-Melee, CF-Ranged, CF-Thrown, CF-Spell, CF-Natural, Confirm-Crit-Martial, Confirm-Crit-Magic
- Troubleshooting 15. Upgrade Paths 16. Contributing
GameAssist’s micro-kernel wraps the Roll20 event bus and exposes:
- Task Queue – serialises async work (
sendChat,findObjs, …) and times out stalled jobs. - Watchdog – detects a hung task >
DEFAULT_TIMEOUT × 2and restarts the queue. - State Manager – namespaced storage (
state.GameAssist.<Module>) with auto-seed and audits. Modules must persist only under their own branch. - Metrics Board – live counters (
commands,errors,avgTaskMs) surfaced through!ga-status; persisted history + ring buffer via!ga-metrics. - Hot Reload – guard-based toggles;
!ga-enable|disableflips module handlers on or off without relying on sandboxoff(). - Compatibility Audit – toggle
GameAssist.flags.DEBUG_COMPATto score overlaps against popular mods (TokenMod, ScriptCards, APILogic) and receive hint tables plus the raw known/unknown list. - Dependency Guardrails – modules declare dependencies (e.g. TokenMod); GameAssist refuses to enable them until the requirements are present.
Design goal: zero GM downtime.
📥 1 Copy GameAssist.js → API editor → Save
🛠 2 Install TokenMod (no config needed)
📜 3 Create 7 roll-tables (see §11: Roll-Table Cookbook)
🔄 4 Type !ga-status → each module should report “Ready”
🎲 5 Test • !critfail • !concentration --damage 14
Every inbound Roll20 event is wrapped so the kernel can tally metrics, enforce ACLs and guarantee FIFO execution with a timeout watchdog.
| Scenario | Kernel Response |
|---|---|
| Uncaught exception in module | Error logged, queue continues. |
Infinite sendChat loop |
Watchdog kills task after 60 s (configurable). |
| State manually corrupted | Auditor deletes branch and re-seeds defaults. |
Natural-1 detection on the standard atk, atkdmg, npcatk, spell templates. Auto-prompts attacker with a chat-button menu; GM can trigger manually with !critfail. Internals:
- Helper commands:
!critfumble help,!critfumble-<type>,!critfumblemenu-<player>,!Confirm-Crit-Martial,!Confirm-Crit-Magic. - Config:
debug,useEmojis,rollDelayMs.
(Requires TokenMod API for automated marker/status integration.)
!concentration or the alias !cc opens buttons for normal/adv/dis rolls or takes flags:
--help→ Whispers Concentration Help message--damage X→ Roll vs DC =max(10, ⌊X/2⌋)--mode normal|adv|dis→ Set roll mode--last→ Repeat last check--off→ Remove marker from selected tokens--status→ Who is concentrating--config randomize on|off→ Toggle emote randomization!ga-conc-status(GM) → Whisper a template of the most recent concentration DC/damage per player
Config keys: marker, randomize.
(Requires TokenMod API for automated marker/status integration.)
Watches change:graphic:bar1_value. When an NPC’s HP drops below 1 the deadMarker is applied via TokenMod, and removed when HP rises. !npc-death-report audits for mismatches. Config keys: autoTrackDeath, deadMarker.
(Requires TokenMod API for automated marker/status integration.)
!npc-hp-all rolls HP for every NPC on the player page; !npc-hp-selected works on a token-selection. Parses any NdM±K formula stored in npc_hpformula. Enable autoRollOnAdd (!ga-config set NPCHPRoller autoRollOnAdd=true) to have GameAssist automatically roll HP the instant a qualifying NPC token is dropped onto the map.
!ga-config ui (or the alias !ga-config-ui) whispers a GM-only control panel built entirely from chat buttons. Each module card shows:
- Current enable/disable status with a one-click toggle (
[Disable CritFumble](!ga-disable CritFumble)style buttons). - Boolean config keys rendered as toggles—pressing a button calls
!ga-config set <Module> key=true|falsefor you. - Optional pagination buttons (
⬅ Prev,🔄 Refresh,Next ➡). Change the number of modules per page with!ga-config set ConfigUI pageSize=<N>.
Disable the ConfigUI module if you prefer to manage everything via CLI only.
The DebugTools module is off by default—enable it with !ga-enable DebugTools whenever you need controlled sand-box testing. Commands stay dry-run unless --apply is present:
!ga-debug damage --amount 12 [--token TOKENID|select] [--apply]→ plan or apply HP damage to bar1.!ga-debug marker --marker statusname [--state on|off|toggle] [--token TOKENID|select] [--apply]→ preview/toggle status markers.!ga-debug save --dc 15 [--bonus 3] [--mode adv|dis|normal] [--label Text] [--apply]→ rehearse concentration/other saves.
Dry runs whisper “would do X” summaries so you can confirm the effect before committing. --apply performs the mutation or rolls a whispered result.
I. In Roll20, open Game Settings → API Scripts.
II. Create a new script, paste in your GameAssist.js file and click Save Script.
III. From the Mod Library, install TokenMod (required by several modules).
IV. Using the Rollable Table tool, create these seven tables by name:
- CF-Melee
- CF-Ranged
- CF-Spell
- CF-Natural
- CF-Thrown
- Confirm-Crit-Martial
- Confirm-Crit-Magic V. Click Save Script again to reload the API. As GM, open your chat whisper window and confirm you see one “ready” message for GameAssist itself and one for each module. It will look roughly like this:
(From GameAssist): ℹ️ [10:53:56 PM] [Core] GameAssist v0.1.5 ready; modules: ConfigUI, CritFumble, NPCManager, ConcentrationTracker, NPCHPRoller, DebugTools
VI. To verify end-to-end, type !ga-status as GM. You’ll receive a whispered summary of GameAssist’s internal metrics (commands processed, active listeners, queue length, etc.), which confirms the system is up and running. Use !ga-metrics for the persisted session log (recent toggles, errors, and queue timing ring buffer) or !ga-metrics reset to clear it.
| Scope | Command | Parameters / Flags | Purpose |
|---|---|---|---|
| Admin | !ga-config list |
— | Write full JSON config to a “GameAssist Config” handout |
!ga-config get <Module> <key> |
— | Whisper the current value of one config key | |
!ga-config set <Module> <key>=<value> |
— | Persistently set one config key | |
!ga-config modules |
— | List all modules with enabled/initialized status icons | |
!ga-enable <Module> / !ga-disable <Module> |
— | Enable or disable a module | |
!ga-config ui / !ga-config-ui |
[--page N] |
Open the GM Config UI with module toggles and quick config buttons | |
!ga-status |
— | Whisper live metrics (commands, messages, errors, etc.) | |
!ga-metrics |
[reset] |
Summarize persisted session metrics; append reset to clear history |
|
| GM | !npc-hp-all |
— | Roll & set HP for all NPC tokens on the current page |
!npc-hp-selected |
— | Roll & set HP for the currently selected NPC tokens | |
!npc-death-report |
— | Report NPC tokens whose HP/“dead” marker states mismatch | |
!critfail |
— | Manual fumble prompt menu for active players | |
!critfumble help |
— | Whisper CritFumble help panel | |
!ga-conc-status |
— |
| GM-only snapshot of the last concentration DC/damage per player |
| Debug | !ga-debug <action> | damage|marker|save + flags (--apply to execute)| Dry-run debugging commands (enable DebugTools; GM-only) | | **Player** |!critfumble- |∈ {melee, ranged, thrown, spell, natural} | Trigger the fumble‐type menu for your character | | |!confirm-crit-martial/!confirm-crit-magic| — | Roll the corresponding confirmation table | | |!concentration/!cc |--damage X, --mode normal|adv|dis, --last, --off, --status, --config randomize on|off, --help` | Open UI buttons or perform a concentration save |
| Module | Key | Type | Default |
|---|---|---|---|
| CritFumble | debug |
bool | true |
useEmojis |
bool | true |
|
rollDelayMs |
number | 200 |
|
| ConcentrationTracker | marker |
string | "Concentrating" |
randomize |
bool | true |
|
| NPCManager | autoTrackDeath |
bool | true |
deadMarker |
string | "dead" |
|
| NPCHPRoller | autoRollOnAdd |
bool | false (opt-in) |
| ConfigUI | pageSize |
number | 3 |
showSummaries |
bool | true |
|
| DebugTools | — | — | No persistent config keys; module enables on demand |
| Category | Method | Description |
|---|---|---|
| Module Registration | GameAssist.register(name, initFn, options) |
Register a new module. name: unique ID; initFn: init callback; options: { enabled: bool, events: [], prefixes: [], teardown: fn } |
| Command Handling | GameAssist.onCommand(prefix, handler, moduleName, opts) |
Listen for API chat commands; opts: { gmOnly: bool, acl: [playerIDs] } |
| Event Handling | GameAssist.onEvent(eventName, handler, moduleName) |
Listen for Roll20 events (e.g. chat:message, change:graphic:bar1_value) |
| Listener Cleanup | GameAssist.offCommands(moduleName) / GameAssist.offEvents(moduleName) |
Clear the registries for a module; handlers remain registered but are guarded by enable/disable flags |
| Module Control | GameAssist.enableModule(name) / GameAssist.disableModule(name) |
Enable or disable a module at runtime, running its initFn or teardown |
| Logging & Errors | GameAssist.log(moduleName, message, level?, opts?) |
Whisper a log to GM; level defaults to 'INFO'; opts: { startup: bool } |
GameAssist.handleError(moduleName, error) |
Increment error metric and log an 'ERROR'-level message |
|
| State Management | GameAssist.getState(moduleName) |
Retrieve (and auto-create) persistent state branch: returns { config, runtime } |
GameAssist.saveState(moduleName, data) |
Merge and persist additional data into a module’s state branch | |
GameAssist.clearState(moduleName) |
Reset a module’s persistent state branch (config/runtime container remains namespaced) | |
| Token Helpers | GameAssist.getLinkedCharacter(token) |
Validate a token is on the Objects layer and linked to a character; returns { token, character } or null |
| Chat Helpers | GameAssist.createButton(label, command) |
Build a Roll20 chat button string [Label](!command …) with the label safely escaped for chat menus |
GameAssist.renderConfigUI(playerId, opts?) |
When ConfigUI is active, whisper the GM panel (opts: { page, rawArgs }) |
|
GameAssist.rollTable(tableName) |
Fire /roll 1t[TableName] via sendChat using Roll20’s rollable table syntax |
|
| Metrics Inspection | GameAssist._metrics / GameAssist.getMetricsStore() |
Live counters plus the persisted metrics branch { totals, history, durations, sessionStart, lastUpdate } |
| Metric Logging | GameAssist.recordMetric(type, opts?) |
Append to the metrics store; opts: { mod, note, noHistory, duration } |
Notes:
- Listener lifecycle is guard-based; disabling a module flips its
initialized/activeflags so handlers early-return without sandboxoff().- Persist data under
state.GameAssist.<Module>via the exposed state helpers.DEFAULT_TIMEOUTandWATCHDOG_INTERVALare internal constants and not part of the public API.
Sample CF-Melee roll table:
| Die Roll | Weight | Effect |
|---|---|---|
| 1 | 1 | Sweaty Grip – Disadvantage on next attack |
| 2–4 | 3 | Weapon Twists – Attack deals half damage |
| 5–6 | 2 | Off-Balance – You fall prone |
| 7 | 1 | Lost Grip – Weapon drops at the foot of your opponent; picking it up requires an action or provokes an opportunity attack |
| 8 | 1 | Double Trouble – Roll twice; both effects apply (rerolls of 8 count as new rolls) |
!ga-disable ConfigUI
!ga-disable CritFumble
!ga-disable ConcentrationTracker
!ga-disable NPCManager
!ga-disable NPCHPRoller
!ga-disable DebugTools
These measurements reflect real-world performance on the specified hardware and chart the end-to-end runtime for !npc-hp-all across a moderate token load.
| CPU / RAM | Ryzen 7 7735HS @ 3.2 GHz · 16 GB DDR5-4800 | | OS / Browser | Windows 11 Home 24H2 (build 26100.4061) · Chrome 137.0.7151.55 | | Roll20 sandbox | “Experimental” channel – 2025-04-09 build | | Dataset | 25 NPC tokens on one page |
Timing results (!npc-hp-all, 25 tokens)
| Run group | Samples | Mean | Median | σ (stdev) | Min – Max |
|---|---|---|---|---|---|
| Warm sandbox (runs 1–24) | 24 | 280 ms | 268 ms | 24 ms | 253 – 337 ms |
| Fresh sandbox (runs 25–34) | 10 | 355 ms | 350 ms | 18 ms | 330 – 387 ms |
| Combined | 34 | 298 ms | 300 ms | 39 ms | 253 – 387 ms |
-
GameAssist appears unresponsive Run
!ga-statusand look at Queue Length and Last Update. Follow up with!ga-metricsto review the persisted task history and recent module toggles/errors.- If Queue Length keeps climbing while Last Update does not change, a module is stuck.
- To resolve: either increase
DEFAULT_TIMEOUTin the code or disable modules one by one (!ga-disable <Module>) until you identify the problematic one.
-
Module not enabled Use
!ga-config modulesto view each module’s enabled/initialized status.- If a module shows ❌, enable it with
!ga-enable <Module>. - If you never see a “Ready: …” message for a module during startup, confirm that its
enabledkey in state istrue(run!ga-config get <Module> enabled).
- If a module shows ❌, enable it with
-
API command not working Many common pitfalls:
- Ensure you type commands in lowercase (e.g.
!concentration,!critfail). - For ConcentrationTracker, verify the code is using
GameAssist.onEvent('chat:message', handler)and convertingmsg.content.toLowerCase()before matching against['!concentration','!cc']. - If you forked or edited the module, compare against the official GameAssist (or related module) code to confirm you didn’t accidentally remove key lines.
- Ensure you type commands in lowercase (e.g.
-
Rollable tables missing or typo CritFumble relies on exactly these table names (case-sensitive):
CF-MeleeCF-RangedCF-SpellCF-NaturalCF-ThrownConfirm-Crit-MartialConfirm-Crit-MagicIf any of these do not exist (or are spelled differently), fumble menus and confirm commands will fail. Use the Roll20 Rollable Table tool to create or correct them.
-
TokenMod errors or missing NPCManager and ConcentrationTracker both call
!token-mod. Make sure you have TokenMod installed (from the Mod Library) and that it appears above GameAssist in your API Scripts list. If TokenMod is missing, you will see errors in the API log when running NPCManager or ConcentrationTracker commands. -
No debug output for a module To enable compatibility logs for conflicting scripts, open the API Console and enter:
GameAssist.flags.DEBUG_COMPAT = true;
Then click Save Script to reload.
For module-specific debugging, whisper to GM:
!ga-config set <Module> debug=true -
Markers not toggling correctly
- For ConcentrationTracker, run
!concentration --offon a selected token to clear its marker. - If markers persist, check which token is selected and whether its status name matches the configured marker key. You can verify via:
!ga-config get ConcentrationTracker marker- For NPCManager, HP <1 should apply the deadMarker. If tokens aren’t getting the “dead” marker, confirm:
!ga-config get NPCManager deadMarker - For ConcentrationTracker, run
-
Re-enabling after a Panic disable
!ga-enable ConfigUI !ga-enable CritFumble !ga-enable NPCManager !ga-enable ConcentrationTracker !ga-enable NPCHPRoller !ga-enable DebugTools -
Still stuck? Check the API Log (visible in the Roll20 API Editor) for red error messages. If you see a “SyntaxError” or “ReferenceError,” copy the exact text and search or post on the Roll20 Community API Forum, including your GameAssist version and which module triggered the error.
When a new release appears on GitHub, follow these steps:
I. Backup Your Current Environment
a. In Roll20, open Game Settings → API Scripts.
b. Select your existing GameAssist script, copy all its contents, and paste them into a local file (e.g. GameAssist-backup.js).
c. (Optional) Attempt to back up your current configuration by running !ga-config list.
- NOTE: At the time of writing, !ga-config list may output an empty JSON ({}) instead of your full settings. If you see {}, open the API Console (F12 → “API” tab), then copy the entire state.GameAssist JSON branch to a local file (e.g. GameAssist-state-backup.json).
d. Confirm you have the script backup (and optionally a state/handout backup) before proceeding.
II. Fetch the Latest Release from GitHub
a. Visit the GameAssist repository on GitHub and select the latest tagged release (e.g. v0.1.1.1 → v0.1.1.2).
b. Download or copy the raw contents of the new GameAssist.js to your clipboard.
III. Replace the Script in Roll20
a. In Game Settings → API Scripts, select your current GameAssist entry.
b. Delete all existing code from that script.
c. Paste in the new GameAssist.js from GitHub.
d. Click Save Script.
IV. Verify Core Loading a. Watch your GM Whisper window—look for a banner such as:
GameAssist v0.1.5 ready; modules: ConfigUI, CritFumble, NPCManager, ConcentrationTracker, NPCHPRoller, DebugTools
b. Run !ga-status to confirm there are no errors and that all modules report as active.
c. If you do not see the “ready” banner or encounter errors, immediately revert by replacing the script contents with your GameAssist-backup.js and clicking Save Script.
V. Quick Module Smoke Test
a. CritFumble: Roll a natural-1 on an attack or type !critfail. The fumble menu should appear.
b. NPCManager: Drag an NPC token below 1 HP or run !npc-death-report. Verify correct marker state or mismatches.
c. ConcentrationTracker: Type !concentration --status; you should receive a whisper listing who is concentrating.
d. NPCHPRoller: Select an NPC token and run !npc-hp-selected; the token’s HP bar should update.
VI. Verify Configuration Keys Persist
a. Your existing settings in state.GameAssist.config should carry over automatically.
b. To double-check a few common values, run:
!ga-config get CritFumble debug
!ga-config get NPCManager deadMarker
!ga-config get ConcentrationTracker marker
!ga-config get NPCHPRoller autoRollOnAdd
c. If any values look incorrect or missing (possibly due to the !ga-config list bug), restore your saved state.GameAssist JSON via the API Console.
VII. Rollback Plan (if needed)
a. If an upgrade fails—missing “ready” banner, unexpected errors—open API Scripts and paste in your GameAssist-backup.js.
b. Click Save Script to revert to the last working version.
c. Open the API Console, paste in your saved state.GameAssist JSON under the state object, and click Save State.
d. Run !ga-status to verify you’re back to the previous stable environment.
Summary: Upgrading is simply: Copy → Paste → Save → Verify → (optional Rollback).
Thank you for your interest in improving GameAssist. Please follow these guidelines to streamline reviews and maintain consistency across the codebase.
I. Reporting Issues a. Before creating a new issue, search existing issues to ensure it hasn’t already been reported or resolved. b. When reporting a bug: - Provide a clear, descriptive title (e.g. “NPCManager does not set dead marker when HP < 1”). - In the description, include: 1. Steps to reproduce the problem in a minimal scenario. 2. The exact GameAssist version and Roll20 environment (e.g. browser, API version). 3. Any error messages from the API Console or chat whispers. - If you have a temporary workaround or suspect a specific module/file, include that detail. c. When suggesting a new feature or enhancement: - Describe the problem you’re trying to solve or the use case you envision. - Outline exactly what new commands, configuration keys, or behaviors you propose. - If possible, sketch example API signatures or sample usage to illustrate your idea.
II. Development Environment & Coding Style
a. JavaScript Standards
1. Use ES6+ syntax (e.g., const/let, arrow functions, template literals).
2. Maintain the existing indentation (4 spaces per level) and brace style.
3. Keep helper functions, constants, and variables scoped inside the GameAssist.register(…) callback whenever possible—avoid top-level declarations.
b. Module Structure
1. Each new or modified module should use GameAssist.register(name, initFn, options).
- name must be unique.
- initFn contains all initialization logic.
- options should specify { enabled: bool, events: [eventNames], prefixes: [chatPrefixes], teardown: fn }.
2. Follow the established pattern:
- Helper functions and constants at the top of the callback.
- Core handler functions in the middle.
- GameAssist.onEvent(…) or GameAssist.onCommand(…) at the end.
- A final GameAssist.log(...) announcing readiness.
3. If adding a new module, always call getState(moduleName) to create your own { config, runtime } branch. Do not overlap or delete another module’s state.
c. Linting & Testing
1. Although we don’t enforce a linter or automated tests, please manually verify your changes by:
- Loading the updated script in Roll20’s API Editor.
- Observing the “ready” banner in GM whispers.
- Running !ga-status to confirm no errors.
- Testing any new commands in a sandbox game.
2. If you introduce new Rollable Tables, update the README’s Roll-Table Cookbook (§11) with exact table names and sample entries.
III. Pull Request Workflow
a. Fork & Branch
1. Fork the GameAssist repository on GitHub.
2. Clone your fork locally and create a branch named for your change (e.g. fix-npc-death-marker, feature-add-concentration-log).
b. Commit Messages
1. Use short, imperative titles (e.g. “Fix: NPCManager missing dead marker”).
2. In the body, explain what changed and why. Reference issue numbers like “Closes #123” or “Fixes #123” when applicable.
c. Submitting a Pull Request
1. Push your branch to your fork.
2. Open a PR against the main branch of the upstream GameAssist repository.
3. In the PR description, include:
- A summary of your changes.
- Any new commands, configuration keys, or table names introduced.
- Steps for reviewers to verify (e.g., “Install TokenMod, create a rollable table named CF-NewFeature, and run !newfeature-test).
4. Respond promptly to review feedback and adjust your branch as needed.
IV. Documentation & Examples a. If you add or change a command, update the Command Matrix (§8) to include syntax, parameters, and purpose. b. For any new roll‐table requirements, append them to the Roll-Table Cookbook (§11) with sample entries. c. If you modify or add configuration keys, reflect them in the Configuration Keys table (§9) with type and default values. d. Wherever possible, include a one‐or‐two‐line example usage in the appropriate README section (e.g. “Macro Recipes” or “Troubleshooting”).
V. Communication & Etiquette a. Keep feedback constructive, focusing on solutions rather than blame. We aim to help contributors improve. b. If a proposed change is large or architectural, open a discussion issue first. Community input can guide major decisions. c. Follow the Code of Conduct: be courteous, inclusive, and respectful of everyone’s time and effort.
By adhering to these guidelines, you’ll help keep GameAssist’s codebase clean, consistent, and accessible—whether you’re an experienced developer or new to Roll20’s API. We appreciate your contributions!
Below is a list of upcoming ideas and planned improvements for GameAssist. This isn’t a strict to-do list—priorities may shift as new needs arise and the community offers feedback.
As you browse this list you will notice that, while some of these ideas are well within reach and could be implemented in the next few updates, others are “pie-in-the-sky” concepts that may prove too complex or simply outside my current bandwidth. I want to be transparent: I’ll do my best to tackle each item, but I can’t guarantee every suggestion will make it into the code. If you see something here that sparks questions or if you have a new idea altogether, please let me know—whether it’s to request an addition, raise a concern, or even contribute code. Your collaboration and feedback help shape where GameAssist goes next.
-
Auto HP Roll on NPC Token Add
- Automatically roll and assign HP whenever a new NPC token is placed on the map.
-
Spell-Specific Concentration Integration
- Automatically apply the “Concentrating” marker when a concentration spell is cast.
- Include the spell name (and optionally an icon) in concentration check results and in the
--statusreport. - Track spell duration or expiration by round, and send optional reminders in chat.
- Automatically clear the “Concentrating” marker if the token’s HP drops to 0 or below.
-
Expanded Module Suite
-
Cooldown Tracker: Prototype a module that monitors ability recharge timers (e.g., Legendary Actions, spell slots) and whispers reminders when those resources become available again.
-
Encounter Assistant: Tools for initiative tracking, managing enemy waves, and quick loot distribution.
-
Resource Tracker: A unified way to track spell slots, ki points, sorcery points, and other character resources directly from tokens.
-
Condition Effect Automator: Automatically apply and remove condition markers (e.g., stunned, poisoned) based on triggers or API calls.
-
Rest & Recovery Module:
- Allow the GM to apply a short or long rest to all player characters with a single command.
- Include an “alternate (gritty) rest” option for rules that use longer rest periods.
- Provide customizable, homebrew-friendly rest rules for campaigns that use nonstandard recovery mechanics.
-
Roll Table Integration: Enable quick import/export of custom Rollable Tables so GMs can share or backup table data easily.
-
Dynamic Location Detection: Automatically manage Auras and Area-of-Effect visuals based on token position and map geometry.
-
-
Modular Component Registry & Discovery
- Implement a lightweight “plugin loader” system so third-party modules can register themselves with minimal boilerplate.
- Allow users to enable or disable modules simply by dropping files into a designated folder or directory structure.
-
Configuration & State Editor
- Provide a structured JSON export/import for
state.GameAssistso GMs can back up, share, or restore entire configuration snapshots in one step.
- Provide a structured JSON export/import for
-
Documentation, Examples & Community Resources
- Build a gallery of real-world macro recipes (e.g., auto-casting spells, sequenced multi-attack workflows) that demonstrate best practices with GameAssist modules.
- Expand the “Roll-Table Cookbook” with templates for common third-party content (e.g., random NPC generation, trap effects, ambient encounters).
- Offer suggestions and recommendations for introducing new features to players—tips for communicating changes so everyone stays on the same page.
-
System Enhancements
- Session Metrics & Logging: Track and display per-session statistics (command usage, error rates, module performance) to help diagnose issues or identify hot spots.
- Verbose Mode: Add a runtime toggle that captures more detailed diagnostics—useful when debugging or troubleshooting complex scenarios.
Note on Feedback: I’m eager to hear your thoughts, new ideas, bug reports, concerns, or general feedback. While I can’t promise immediate implementation or a fixed timeline, every request will be reviewed and considered. If you have something to add or see an area that needs improvement, please open an issue or join the discussion—your contributions are what make GameAssist better for everyone.
See CHANGELOG.md.
Below are key terms used throughout GameAssist documentation. Each entry includes a friendly, approachable definition to help you understand how everything fits together.
-
API Command A chat message beginning with an exclamation mark (
!) that the GameAssist kernel listens for. When a player or GM types something like!critfail, GameAssist intercepts it and calls the appropriate module. Think of it as a “chat shortcut” that triggers a module action. -
Command Handler A JavaScript function registered by a module to respond to specific API commands. Under the hood,
GameAssist.onCommand(...)wraps your handler so that when someone types the matching prefix (e.g.!concentration), GameAssist routes the message into your code. -
Event Handler A JavaScript function that runs when a certain Roll20 event occurs (for example, a token’s HP changes or someone sends a chat message). Modules register event handlers via
GameAssist.onEvent(...), and GameAssist makes sure they only fire after the system has fully initialized. -
Kernel The central GameAssist engine that manages the task queue, watchdog timer, metrics collection, and overall coordination between modules. You can think of it as the “operating system” for all GameAssist features.
-
Marker A Roll20 token status icon (e.g., “dead,” “Concentrating,” or any other colored dot or symbol). Modules like NPCManager or ConcentrationTracker toggle these markers on tokens to visually show conditions without manual clicking.
-
Module A self-contained feature package that plugs into the GameAssist kernel. Each module is registered with a unique name and an initialization function—the kernel calls that function when it’s time to turn the module on. Examples include CritFumble, NPCManager, ConcentrationTracker, and NPCHPRoller.
-
Persistent State The JSON object stored in
state.GameAssistwhere each module keeps its configuration and runtime data. This state persists between API script reloads so modules can “remember” settings like whether they’re enabled or when a player last took damage. -
Prefixes The string or strings (like
!critfumbleor!cc) that identify module-specific commands. GameAssist collects all prefixes when you register a module, deduplicates them, and listens for chat messages that start with any of those prefixes. -
Roll-Table (Rollable Table) A built-in Roll20 feature where you define a list of outcomes (entries) each tied to die roll ranges (e.g., “2–4 → Weapon Twists”). Modules like CritFumble automatically roll on these tables (e.g.,
1t[CF-Melee]) to generate a random effect or flavor text. -
Task An asynchronous job placed on GameAssist’s internal queue (via
_enqueue). Tasks can be anything from initializing a module to running a delayed table roll. The kernel serializes tasks, enforces timeouts, and uses a watchdog to prevent the queue from stalling. -
Teardown Function An optional function a module provides when registering. Called by
GameAssist.disableModule(...), teardown typically cleans up event listeners, removes markers, and restores any state to its pre-initialized form. -
Watchdog A periodic check (running every 15 seconds by default) that ensures the task queue isn’t stuck. If a task processor takes longer than twice the default timeout, the watchdog forces a reset so subsequent tasks can continue.
-
Watchdog Interval The frequency (in milliseconds) at which the watchdog timer inspects the queue. By default, it’s set to 15,000 ms (15 seconds). If a task hasn’t finished within
DEFAULT_TIMEOUT * 2, the watchdog logs a warning and resets the busy flag. -
Workspace Your Roll20 game’s API Scripts area where you paste and save
GameAssist.js. This is where the kernel lives, alongside any TokenMod or third-party modules you install via the Mod Library.
Tip: Whenever you see a new term you’re not sure about, check this glossary first. It’s designed to give you the big-picture context without diving straight into code. If the term is not here, please let me know that it ought to be.