Roll20 Wiki

Latest revision as of 19:50, 9 March 2022

API ScriptAuthor: Kurt J.
Version: 1.0.14
Last Modified: 2021-01-02
Code: EncounterHelper
Dependencies: None
Conflicts: None

Streamlining Combat with the Encounter Helper (11min, Nov 2021)

Main Page: API:Script Index

[edit] Introduction

EncounterHelper is designed to make the GM's life easier by allowing you to define groups of tokens that can be treated as a single unit for moving between the GM and Tokens layers. Tokens can be part of multiple groups, and groups and be shown and hidden with a single click/command. When an encounter is defined, initial state information is stored for each token in the encounter, and the encounter can be reset, returning tokens to their original positions, bar values, and status markers. Not RPG system specific, though the default values for what columns to display about tokens are for D&D 5E by Roll20. These can be changed through the config.

The API script features support for English, French, Spanish, and German languages with messages and button text translated (currently by Google Translate) into each language - languages are selectable from the OneClick install page after adding the script to your game via the language dropdown.

Demonstration 8min, (audio bit low)
EncounterHelper thread^(Forum)
sourcecode - Development Gist

On any page that you wish to define and use encounters, you will need to create a token called "Encounter Token" This token can be on the GM Layer, and have any graphic you wish. The "gmnotes" attribute on the token will be used to store information about encounters on this map and should not be edited manually.

If no other action is taken, the script will default to working on the page the Player Ribbon is on. However, you can specify an alternate active page using the !eh pagelist command as well.

(Optional) Install the GroupInitiative API so it can be used together with EncounterHelper

[edit] Setting up Encounters

Move the Player Ribbon to the page you wish to work on.
Create a token (any graphic) and set the name to "Encounter Token"
(Optional) Place the Encounter Token on the GM layer
Select one or more tokens on the page that you wish to group into an encounter
Enter !eh create Encounter Name, replacing Encounter Name with the name you wish to assign to the encounter

[edit] Listing, Showing, and Hiding Encounters

Roll20 Mod
Mod Suggestions

Mods by Category

Debug

Other

Move the Player Ribbon to the page you wish to work on OR enter !eh pagelist and click the Activate button if you wish to leave the Player Ribbon in place
Enter !eh list (or simply !eh) in the chat window to display a list of encounters on the active page.
Click the appropriate button associated with the encounter:

S = Show Encounter - Moves the tokens to the Objects/Tokens Layer
H = Hide Encounter - Moves the tokens to the GM Layer
🆔 = Rename Encounter - You will be prompted for a new name to assign to the encounter.
📃 = Display Encounter Mobs - Will display a summary of the tokens in the encounter. The columns displayed are customizable.
⛔ = Delete Encounter - Will remove the encounter definition from Encounter Helper (WILL NOT ALTER OR REMOVE THE TOKENS)
🎲 = Group Initiative - If you have the Group Initiative API script installed, EncounterHelper will roll initiative for the tokens in the encounter (and optionally the players)
↩ = Reset Encounter - Returns the token to its original position and resets bar values and status markers. The attributes that are saved/reset can be customized

[edit] Options

Currently there is a single option that is settable by using the !eh configmenu command.

GroupInit Players : If On, players will be included in a Group Initiative roll. If off, only the encounter tokens will be included.

[edit] Page-Wide Options

At the bottom of the Encounter List is a button labeled "Show Page-Wide Options". Clicking this button will display a sub menu with two options:

Update All Reset Data : Will update the stored reset data for ALL tokens on the page to their current values, including layer, bar values, status markers, and location.
Reset All Encounters : Will reset ALL tokens on the page to their stored reset values.

[edit] Chat Commands

NOTE: All chat command can only be run by the GM. If a player attempts to run an !eh chat command, the GM will be sent a message alerting them to the attempt.

While almost everything in EncounterHelper can be done via the built-in menus, behind the scenes it works on multiple chat commands that all begin with !eh. This section of the Wiki provides a full list of these commands, though it should be noted that you will likely never need to use most of them.

Command	Description
!eh list	The command that will be used most often in-game. Lists all encounters that have defined on the current page, along with buttons to show, hide, display details, or remove (delete) the encounter. These generally just call the other !eh commands.
!eh pagelist	List all of the pages that have "Encounter Token" tokens on them and allows you to activate any of those pages as the page you will currently be working on. If no page is active, the player ribbon location will be used as the active page.
!eh create <Encounter Name>	Requires one or more tokens to be selected. Will create (or replace) an encounter defined on the current page with the selected tokens and name. Example: !eh create A05 - Ghouls in the West Wing
!eh show <Encounter Name>	Moves all tokens associated with an encounter to the Object/Token layer. Note that you would probably not type this out, but rather pick the show icon from an !eh list output. Example: !eh show A05 - Ghouls in the West Wing
!eh hide <Encounter Name>	Moves all tokens associated with an encounter to the GM Info layer. Note that you would probably not type this out, but rather pick the show icon from an !eh list output. Example: !eh hide A05 - Ghouls in the West Wing
!eh display <Encounter Name>	Outputs a table of all of the tokens associated with the named encounter to the chat window as a whisper to the GM. Includes name, HP, and armor class by default - the columns displayed and the attributes used are configurable. Example: !eh display A05 - Ghouls in the West Wing
!eh remove <Encounter Name>	Removes the encounter from the encounters list. Does not impact the associated tokens. Example: !eh remove A05 - Ghouls in the West Wing
!eh promptreset <Encounter Name>	Creates a button that can be pressed to reset the encounter to its initial saved state. This command is used in the encounter list to allow for a button to reset the encounter.
!eh reset <Encounter Name>	Resets the encounter to its initial state (called by clickikng the button generated by !eh promptreset)
!eh update <Encounter Name>	Does not require tokens to be selected. Updates the tokens for the given encounter by storing the current reset data values back into the encounter. Can be used after adjusting the positions or attributes of tokens that you want to become their defaults on a reset.
!eh update_all_reset_info	Runs !eh update for all encounters on the page, as a one-shot way to store reset data for all page encounters at the same time.
!eh reset_all_encounters	Runs !eh reset for all encounters on the page.
!eh setactivepage <pageid>	Sets the currently active page to the passed page id. You will probably never use this, but it is the command called by the Activate button on the !eh pagelist.
!eh configmenu	Displays the configuration menu.
!eh rename <existing encounter name>\|<new encounter name>	Rename the existing encounter with a new name. This command is called automatically when selecting the Rename button from the encounter list.

[edit] See Also

API:Script Index (partial) list of other APIs
GroupInitiative - API that can be used with EncounterHelper

@@ Line 1: / Line 1: @@
+{{revdate}}
+{{script overview
+|name=EncounterHelper
+|author=[[Kurt J.]]
+|version=1.0.14
+|lastmodified=2021-01-02
+|conflicts=None}}
+{{#evp:youtube|gKtKXa8HxOE|Streamlining Combat with the Encounter Helper (11min, Nov 2021) |right|600}}
+{{main|API:Script Index}}
 == Introduction ==
+'''EncounterHelper''' is designed to make the [[GM]]'s life easier by allowing you to define groups of [[tokens]] that can be treated as a single unit for moving between the GM and Tokens [[layers]]. Tokens can be part of multiple groups, and groups and be shown and hidden with a single click/command. When an encounter is defined, initial state information is stored for each token in the encounter, and the encounter can be reset, returning tokens to their original positions, bar values, and status markers. '''''Not RPG system specific''''', though the default values for what columns to display about tokens are for [[D&D 5E by Roll20]]. These can be changed through the config.
-[[File:Eh-axeholm encounterlist.png|right]]
-'''EncounterHelper''' is designed to make the GM's life easier by allowing you to define groups of tokens that can be treated as a single unit for moving between the GM and Tokens layers. Tokens can be part of multiple groups, and groups and be shown and hidden with a single click/command. When an encounter is defined, initial state information is stored for each token in the encounter, and the encounter can be reset, returning tokens to their original positions, bar values, and status markers.
 The API script features support for English, French, Spanish, and German languages with messages and button text translated (currently by Google Translate) into each language - languages are selectable from the OneClick install page after adding the script to your game via the language dropdown.
+[[File:Eh-axeholm encounterlist.png|right|thumbnail|400px]]
-== Requirements ==
+* {{yt.be|tPdyRIcpeVY Demonstration}} 8min, (audio bit low)
+* {{forum|permalink/8988154/ EncounterHelper thread}}
+* {{gist|kjaegers/0885fa7d308fdb4b4f82bb4471b96487 sourcecode}} - Development Gist
+__TOC__
+=== Requirements ===
 On any page that you wish to define and use encounters, you will need to create a token called "Encounter Token" This token can be on the GM Layer, and have any graphic you wish. The "gmnotes" attribute on the token will be used to store information about encounters on this map and should not be edited manually.
 If no other action is taken, the script will default to working on the page the Player Ribbon is on. However, you can specify an alternate active page using the '''!eh pagelist''' command as well.
+'''(Optional)''' Install the [[GroupInitiative]] API so it can be used together with EncounterHelper
 == Setting up Encounters ==
@@ Line 21: / Line 32: @@
 * Enter '''!eh create ''Encounter Name''''', replacing Encounter Name with the name you wish to assign to the encounter
-== Listing, Showing, and Hiding Encounters ==
+=== Listing, Showing, and Hiding Encounters ===
+{{apiboxRec}}
 * Move the Player Ribbon to the page you wish to work on '''''OR''''' enter '''!eh pagelist''' and click the Activate button if you wish to leave the Player Ribbon in place
 * Enter '''''!eh list''''' (or simply '''''!eh''''') in the chat window to display a list of encounters on the active page.
@@ Line 28: / Line 39: @@
 :* S = Show Encounter - Moves the tokens to the Objects/Tokens Layer
 :* H = Hide Encounter - Moves the tokens to the GM Layer
-:*
+:* 🆔 = Rename Encounter - You will be prompted for a new name to assign to the encounter.
+:* 📃 = Display Encounter Mobs - Will display a summary of the tokens in the encounter. The columns displayed are customizable.
+:* ⛔ = Delete Encounter - Will remove the encounter definition from Encounter Helper ('''WILL NOT ALTER OR REMOVE THE TOKENS''')
+:* 🎲 = Group Initiative - If you have the [[GroupInitiative|Group Initiative]] API script installed, EncounterHelper will roll initiative for the tokens in the encounter (and optionally the players)
+:* ↩ = Reset Encounter - Returns the token to its original position and resets bar values and status markers. The attributes that are saved/reset can be customized
+=== Options ===
+Currently there is a single option that is settable by using the '''''!eh configmenu''''' command.
+* GroupInit Players : If On, [[players]] will be included in a Group Initiative roll. If off, only the encounter tokens will be included.
+=== Page-Wide Options ===
+At the bottom of the Encounter List is a button labeled "Show Page-Wide Options". Clicking this button will display a sub menu with two options:
+* Update All Reset Data : Will update the stored reset data for ALL tokens on the page to their current values, including layer, bar values, status markers, and location.
+* Reset All Encounters : Will reset ALL tokens on the page to their stored reset values.
+=== Chat Commands ===
+'''NOTE: All chat command can only be run by the [[GM]]. If a [[player]] attempts to run an !eh chat command, the GM will be sent a message alerting them to the attempt.'''
+While almost everything in EncounterHelper can be done via the built-in menus, behind the scenes it works on multiple chat commands that all begin with '''''!eh'''''. This section of the Wiki provides a full list of these commands, though it should be noted that you will likely never need to use most of them.
+{| class="wikitable"
+|-
+! Command !! Description
+|-
+| style="white-space:nowrap" | !eh list || The command that will be used most often in-game. Lists all encounters that have defined on the current page, along with buttons to show, hide, display details, or remove (delete) the encounter. These generally just call the other !eh commands.
+|-
+| style="white-space:nowrap" | !eh pagelist || List all of the pages that have "Encounter Token" tokens on them and allows you to activate any of those pages as the page you will currently be working on. If no page is active, the player ribbon location will be used as the active page.
+|-
+| style="white-space:nowrap" | !eh create <Encounter Name> || Requires one or more tokens to be selected. Will create (or replace) an encounter defined on the current page with the selected tokens and name.
+    Example: !eh create A05 - Ghouls in the West Wing
+|-
+| style="white-space:nowrap" | !eh show <Encounter Name> || Moves all tokens associated with an encounter to the Object/Token layer. Note that you would	probably not type this out, but rather pick the show icon from an !eh list output.
+    Example: !eh show A05 - Ghouls in the West Wing
+|-
+| style="white-space:nowrap" | !eh hide <Encounter Name> || Moves all tokens associated with an encounter to the GM Info layer. Note that you would probably not type this out, but rather pick the show icon from an !eh list output.
+    Example: !eh hide A05 - Ghouls in the West Wing
+|-
+| style="white-space:nowrap" | !eh display <Encounter Name> || Outputs a table of all of the tokens associated with the named encounter to the chat window as a whisper to the GM. Includes name, HP, and armor class by default - the columns displayed and the attributes used are configurable.
+    Example: !eh display A05 - Ghouls in the West Wing
+|-
+| style="white-space:nowrap" | !eh remove <Encounter Name> || Removes the encounter from the encounters list. Does not impact the associated tokens.
+    Example: !eh remove A05 - Ghouls in the West Wing
+|-
+| style="white-space:nowrap" | !eh promptreset <Encounter Name> || Creates a button that can be pressed to reset the encounter to its initial saved state. This command	is used in the encounter list to allow for a button to reset the encounter.
+|-
+| style="white-space:nowrap" | !eh reset <Encounter Name> || Resets the encounter to its initial state (called by clickikng the button generated by !eh promptreset)
+|-
+| style="white-space:nowrap" | !eh update <Encounter Name> || Does not require tokens to be selected. Updates the tokens for the given encounter by storing the current reset data values back into the encounter. Can be used after adjusting the positions or attributes of tokens that you want to become their defaults on a reset.
+|-
+| style="white-space:nowrap" | !eh update_all_reset_info || Runs !eh update for all encounters on the page, as a one-shot way to store reset data for all page encounters at the same time.
+|-
+| style="white-space:nowrap" | !eh reset_all_encounters || Runs !eh reset for all encounters on the page.
+|-
+| style="white-space:nowrap" | !eh setactivepage <pageid> || Sets the currently active page to the passed page id. You will probably never use this, but it is the command called by the Activate button on the !eh pagelist.
+|-
+| style="white-space:nowrap" | !eh configmenu || Displays the configuration menu.
+|-
+| style="white-space:nowrap" |	!eh rename <existing encounter name>|<new encounter name> || Rename the existing encounter with a new name. This command is called automatically when selecting the Rename button from the encounter list.
+|}
+==See Also==
+* [[API:Script Index]] (partial) list of other APIs
+* [[GroupInitiative]] - API that can be used with EncounterHelper
+<br>
+<br>
+[[Category:User API Scripts]]
+[[Category:Featured articles]]
+[[Category:Tokens]]
+[[Category:Combat/Initiative]]

Roll20 Wiki

Navigation

Personal tools

Toolbox

Difference between revisions of "Script:EncounterHelper"

From Roll20 Wiki