From 31b03af0a23109d20f794d626530aecd0ce80e9e Mon Sep 17 00:00:00 2001 From: alicekb Date: Wed, 26 Jun 2024 15:43:59 -0400 Subject: [PATCH] CSC: Update Rolls page --- config/production/hugo.toml | 2 +- content/docs/components/InitRelay.md | 11 +- content/docs/components/roll.md | 67 ++++++++++-- hugo_stats.json | 9 ++ public/docs/components/index.xml | 2 +- public/docs/components/initrelay/index.html | 12 +-- public/docs/components/rolls/index.html | 113 +++++++++++++++++--- public/search-index.json | 2 +- 8 files changed, 180 insertions(+), 38 deletions(-) diff --git a/config/production/hugo.toml b/config/production/hugo.toml index 48a67cf..65cf4f4 100644 --- a/config/production/hugo.toml +++ b/config/production/hugo.toml @@ -1,2 +1,2 @@ # Overrides for production environment -baseurl = "https://roll20.github.io/beacon-docs/" +baseURL = "https://roll20.github.io/beacon-docs/" diff --git a/content/docs/components/InitRelay.md b/content/docs/components/InitRelay.md index f672fa7..eba445b 100644 --- a/content/docs/components/InitRelay.md +++ b/content/docs/components/InitRelay.md @@ -50,12 +50,8 @@ These components are crucial for handling actions, computations, macros, and rol href="/docs/components/handlers/" target="_blank" >}} - {{< /card-grid >}} - - - {{< card-grid >}} {{< link-card title="Computed" @@ -69,10 +65,9 @@ These components are crucial for handling actions, computations, macros, and rol href="/docs/components/handling-legacy-macro-attributes/" target="_blank" >}} - {{< /card-grid >}} - +{{< card-grid >}} {{< link-card title="Rolls" description="The Rolls component allows for advanced dice-rolling mechanics within the VTT. It supports both simple and complex rolls, providing flexibility in how roll results are displayed and computed." @@ -80,10 +75,10 @@ These components are crucial for handling actions, computations, macros, and rol target="_blank" >}} - {{< link-card title="Dispatch" description="The dispatch object provides methods for sending commands from the character sheet back to the host. Except when specified every method returns a promise." href="/docs/components/dispatch/" target="_blank" ->}} \ No newline at end of file +>}} +{{< /card-grid >}} \ No newline at end of file diff --git a/content/docs/components/roll.md b/content/docs/components/roll.md index 8a1cd16..b1772a9 100644 --- a/content/docs/components/roll.md +++ b/content/docs/components/roll.md @@ -15,32 +15,63 @@ seo: canonical: "" # custom canonical URL (optional) noindex: false # false (default) or true --- +The Roll20 Tabletop and Roll20 Characters (both refered to as host throughout the rest of this page) have several new features that enhance the way rolls are handled and displayed. These features include attributes and elements that allow for dynamic roll results and interactivity within the host. +[Vist the Roll20 help center to learn more about Roll20's Dice Rolling system](https://help.roll20.net/hc/en-us/articles/360037773133-Dice-Reference) -The VTT (Virtual Tabletop) has several new features that enhance the way rolls are handled and displayed. These features include attributes and elements that allow for dynamic roll results and interactivity within the VTT environment. +The most command way to trigger a dice roll is through the dispatch object returned from the `initRelay`, but it could also be called from [actions](/docs/components/actions): +```typescript +dispatch.roll({ + rolls: { [rollName: string]: string } // Ex. {attack: '1d20+4', damage: `3d6+2`} + messageId?: string +}): Promise<{messageId: string, results: RollResults }> +``` + +The `roll` method takes one or more rolls in the form of an object, where the keys are unique roll names and the values are roll strings. + +`messageId` can be provided to attach the roll to an existing chat message, either overriding it or appending to it in the chat log. +If `messageId` is omitted, the roll will be associated with a new chat message and a new `messageId` for that message will be returned with the roll results. +The method returns a promise that resolves with an object containing the `messageId` and the [RollResults](#rolls-results-format). The roll result is returned in the same format as in the non-beacon dice rolls computed roll system. + +{{< callout context="tip" >}} +The dispatch roll method and the actions roll section do not post to the chat, instead they will return a promise which will resolve to the roll results and the message id. +{{< /callout >}} + +## Posting A Roll to the Chat + +The roll method does not send or post any data to the chat on it's own. We instead have to use [dispatch's post](/docs/components/dispatch/#post) method to send our roll results along with any other content to the chat. + +```typescript +dispatch.post({ + characterId: '-O0KZhMTxLkn2HArFj8f', + content: `I rolled a ${diceRoll.results.attack.results.result} to hit and did ${diceRoll.results.damage.results.result} damage!`, + }) +``` + +## Additional Roll Posting Options ## data-rollname -The `data-rollname` attribute tells the VTT that this HTML element is displaying the result of a roll. +The `data-rollname` attribute tells the host that this HTML element is displaying the result of a roll. ```html ``` -The VTT will both add the Quantum Roll signature tooltip to the element and replace the contents of the element with the result from the roll. +The host will both add the Quantum Roll signature element and replace the contents of the element with the result from the roll. -This is the preferred method for displaying roll results wherever possible, that is, sending the whole roll formula to the roll server and allowing the VTT to display the result. +This is the preferred method for displaying roll results wherever possible, that is, sending the whole roll formula to the roll server and allowing the host to display the result. ## data-computed -Tagging an element with both a `data-rollname` and a `data-computed="true"` tells the VTT that this element is associated with a roll, but the results of that roll were computed by the author, as opposed to the roll server computing the result. +Tagging an element with both a `data-rollname` and a `data-computed="true"` tells the host that this element is associated with a roll, but the results of that roll were computed by the author, as opposed to the roll server computing the result. ```html 25 ``` -The VTT will add the Quantum Roll signature tooltip, but the content of the element will not be modified. Generally, this should only be used when the roll server does not support a particular dice mechanic. +The host will add the Quantum Roll signature tooltip, but the content of the element will not be modified. Generally, this should only be used when the roll server does not support a particular dice mechanic. -## Roll Buttons +### Roll Buttons Roll buttons are interactive elements that trigger sheet actions, such as damage rolls, when clicked. These buttons use the `data-sheet-action` attribute to specify the action to be executed. @@ -48,4 +79,24 @@ Roll buttons are interactive elements that trigger sheet actions, such as damage ``` -Additional arguments can be provided using the `data-args` attribute, and the character, `messageId`, and original rolls will be included automatically. \ No newline at end of file +Additional arguments can be provided using the `data-args` attribute, and the character, `messageId`, and original rolls will be included automatically. + +## Rolls Results Format +```typescript +type RollResults = { + [name: string]: { + expression: string //The original expression (i.e. 1d20+3d6) + rollName: string //The name of the roll + results: { //The results of the roll(s) + expression: string + dice?: number[] // + result: number //The final result of the roll + rolls?: { //Detailed results of each part of the roll (i.e. 3d6) + sides: number //The type of die for this part of the roll (i.e. 6) + dice: number //The number of dice (i.e. 3) + results: number[] //The result of each die (i.e. [4, 2, 5]) + }[] + } + } +} +``` \ No newline at end of file diff --git a/hugo_stats.json b/hugo_stats.json index eee4187..ec890b9 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -225,6 +225,11 @@ "ids": [ "TableOfContents", "addactionstohost", + "additional", + "additional-options-for-posting-messages", + "additional-options-when-posting-messages", + "additional-roll-html-options-when-posting-messages", + "additional-roll-posting-options", "addtotracker", "autolinktext", "background", @@ -276,6 +281,8 @@ "opendialogfromlink", "perform", "post", + "posting-a-roll-to-the-chat", + "posting-to-chat", "prerequisites", "quantum-roll", "query", @@ -285,6 +292,8 @@ "roll", "roll-buttons", "roll-template", + "rolls-results", + "rolls-results-format", "running-tests", "setcomputed", "setcontainersize", diff --git a/public/docs/components/index.xml b/public/docs/components/index.xml index 002be52..300f686 100644 --- a/public/docs/components/index.xml +++ b/public/docs/components/index.xml @@ -49,7 +49,7 @@ http://localhost:1313/docs/components/rolls/ Sun, 07 Jan 2024 16:12:37 +0200 http://localhost:1313/docs/components/rolls/ - The VTT (Virtual Tabletop) has several new features that enhance the way rolls are handled and displayed. These features include attributes and elements that allow for dynamic roll results and interactivity within the VTT environment. + The Roll20 Tabletop and Roll20 Characters (both refered to as host throughout the rest of this page) have several new features that enhance the way rolls are handled and displayed. Dispatch diff --git a/public/docs/components/initrelay/index.html b/public/docs/components/initrelay/index.html index b6c799c..e0a883c 100644 --- a/public/docs/components/initrelay/index.html +++ b/public/docs/components/initrelay/index.html @@ -482,7 +482,6 @@
- @@ -522,12 +521,12 @@
+ -
@@ -543,10 +542,9 @@
-
+ -
@@ -562,9 +560,11 @@
-
+ + +
diff --git a/public/docs/components/rolls/index.html b/public/docs/components/rolls/index.html index 5d3df3a..894068b 100644 --- a/public/docs/components/rolls/index.html +++ b/public/docs/components/rolls/index.html @@ -44,7 +44,7 @@ > - + @@ -52,7 +52,7 @@ - + @@ -402,9 +402,15 @@
Beacon SDK

On this page

 @@ -429,18 +435,72 @@

Rolls

-

The VTT (Virtual Tabletop) has several new features that enhance the way rolls are handled and displayed. These features include attributes and elements that allow for dynamic roll results and interactivity within the VTT environment.

+

The Roll20 Tabletop and Roll20 Characters (both refered to as host throughout the rest of this page) have several new features that enhance the way rolls are handled and displayed. These features include attributes and elements that allow for dynamic roll results and interactivity within the host. +Vist the Roll20 help center to learn more about Roll20’s Dice Rolling system

+

The most command way to trigger a dice roll is through the dispatch object returned from the initRelay, but it could also be called from actions:

+ + + +
+
+
+ +
+ 
dispatch.roll({
+  rolls: { [rollName: string]: string } // Ex. {attack: '1d20+4', damage: `3d6+2`}
+  messageId?: string
+}): Promise<{messageId: string, results: RollResults }>
+
+
+

The roll method takes one or more rolls in the form of an object, where the keys are unique roll names and the values are roll strings.

+

messageId can be provided to attach the roll to an existing chat message, either overriding it or appending to it in the chat log. +If messageId is omitted, the roll will be associated with a new chat message and a new messageId for that message will be returned with the roll results. +The method returns a promise that resolves with an object containing the messageId and the RollResults. The roll result is returned in the same format as in the non-beacon dice rolls computed roll system.

+
+ +
+ +
+

The dispatch roll method and the actions roll section do not post to the chat, instead they will return a promise which will resolve to the roll results and the message id.

+ +
+
+
+ +

Posting A Roll to the Chat

+

The roll method does not send or post any data to the chat on it’s own. We instead have to use dispatch’s post method to send our roll results along with any other content to the chat.

+ + + +
+
+
+ +
+ 
dispatch.post({
+    characterId:  '-O0KZhMTxLkn2HArFj8f',
+    content: `I rolled a ${diceRoll.results.attack.results.result} to hit and did ${diceRoll.results.damage.results.result} damage!`,
+  })
+
+
+

Additional Roll Posting Options

data-rollname

-

The data-rollname attribute tells the VTT that this HTML element is displaying the result of a roll.

+

The data-rollname attribute tells the host that this HTML element is displaying the result of a roll.

@@ -452,10 +512,10 @@

data-rollname
<span data-rollname="attack"></span>
-

The VTT will both add the Quantum Roll signature tooltip to the element and replace the contents of the element with the result from the roll.

-

This is the preferred method for displaying roll results wherever possible, that is, sending the whole roll formula to the roll server and allowing the VTT to display the result.

+

The host will both add the Quantum Roll signature element and replace the contents of the element with the result from the roll.

+

This is the preferred method for displaying roll results wherever possible, that is, sending the whole roll formula to the roll server and allowing the host to display the result.

data-computed

-

Tagging an element with both a data-rollname and a data-computed="true" tells the VTT that this element is associated with a roll, but the results of that roll were computed by the author, as opposed to the roll server computing the result.

+

Tagging an element with both a data-rollname and a data-computed="true" tells the host that this element is associated with a roll, but the results of that roll were computed by the author, as opposed to the roll server computing the result.

@@ -467,8 +527,8 @@

data-computed
<span data-rollname="complex" data-computed="true">25</span>
-

The VTT will add the Quantum Roll signature tooltip, but the content of the element will not be modified. Generally, this should only be used when the roll server does not support a particular dice mechanic.

-

Roll Buttons

+

The host will add the Quantum Roll signature tooltip, but the content of the element will not be modified. Generally, this should only be used when the roll server does not support a particular dice mechanic.

+

Roll Buttons

Roll buttons are interactive elements that trigger sheet actions, such as damage rolls, when clicked. These buttons use the data-sheet-action attribute to specify the action to be executed.

@@ -482,6 +542,33 @@

Roll Buttons

Additional arguments can be provided using the data-args attribute, and the character, messageId, and original rolls will be included automatically.

+

Rolls Results Format

+ + + +
+
+
+ +
+ 
type RollResults = {
+  [name: string]: {
+    expression: string        //The original expression (i.e. 1d20+3d6)
+    rollName: string          //The name of the roll
+    results: {                //The results of the roll(s)
+      expression: string
+      dice?: number[]         //
+      result: number          //The final result of the roll
+      rolls?: {               //Detailed results of each part of the roll (i.e. 3d6)
+        sides: number         //The type of die for this part of the roll (i.e. 6)
+        dice: number          //The number of dice (i.e. 3)
+        results: number[]     //The result of each die (i.e. [4, 2, 5])
+      }[]
+    }
+  }
+}
+
+
diff --git a/public/search-index.json b/public/search-index.json index f7b8332..d3730f5 100644 --- a/public/search-index.json +++ b/public/search-index.json @@ -1 +1 @@ -[{"content":"Well-thought-through product announcements will help increase feature awareness and engage users with new functionality. Just like sharing your public roadmap, it\u0026rsquo;s also a great way to let potential customers see that you\u0026rsquo;re constantly improving.\nFurther reading Read How to announce product updates and features ","date":"2023-09-07","id":0,"permalink":"/blog/example-post/","summary":"You can use blog posts for announcing product updates and features.","tags":[],"title":"Example Post"},{"content":"","date":"2023-09-07","id":1,"permalink":"/blog/","summary":"","tags":[],"title":"Blog"},{"content":"","date":"2024-06-07","id":2,"permalink":"/docs/gettingstarted/","summary":"","tags":[],"title":"Getting Started"},{"content":"The Beacon SDK is a toolset designed to enhance and streamline the development of virtual tabletop (VTT) character sheets and other interactive elements.\nWhether you\u0026rsquo;re a game master (GM), a developer, or a player, the Beacon SDK provides a framework to create dynamic, responsive, and fully integrated VTT experiences.\nWhat is the Beacon SDK? The Beacon SDK (software development kit) is a toolset used to create digital character sheets on Roll20 for Roll20 Tabletop and Roll20 Characters.\nWhether you\u0026rsquo;re an experience developer, or just starting out, the Beacon SDK provides a framework to create dynamic, responsive, and fully integrated character sheet experiences.\nThe Beacon SDK also introduces a new way to develop characters sheets for Roll20. Beacon SDK allows you to connect your local development environment to sandboxes in Roll20 Characters and Roll20 Tabletop, giving you real-time updates as you develop.\nKey Features Character Sheets: Design and implement a web app character sheet with dynamic attributes and real-time updates. Local Development: Work where you are most comfortable and get real-time updates in sandboxes in Roll20. Testing Sheets: Release a testing sheet and give others special access to it before you push it live for everyone. Roll Mechanics: Integrate complex roll formulas and display roll results directly within the Roll20 Tabletop and Roll20 Characters. Legacy Support: Convert and integrate legacy macros and roll templates with the new Beacon architecture. Customization: Define custom actions, computed attributes and handle specific roll templates tailored to your game\u0026rsquo;s needs. Components Overview The Beacon SDK is composed of several key components:\nActions: Define and manage custom actions that can be triggered within the VTT. Handlers: Event handlers that process and respond to various VTT events and messages. Computed Attributes: Define dynamically computed attributes based on other attributes. Macro Attributes: Convert and manage legacy macro attributes for compatibility with the Beacon SDK. Rolls: Implement advanced roll mechanics and display results dynamically within the VTT. For a comprehensive overview of these components, view the components section.\nGetting Started To get started with the Beacon SDK, you must initialize the relay, set up your character sheets, and define the necessary actions, handlers, and computed attributes.\nThis documentation provides detailed guides and example sheets to help you through each step of the process.\nBy leveraging the Beacon SDK, you can create rich, interactive, fully integrated VTT experiences that enhance gameplay and streamline game management.\nWhether adapting existing character sheets or building new ones from scratch, the Beacon SDK offers the tools and flexibility to bring your digital character sheet to life.\n","date":"2024-05-07","id":3,"permalink":"/docs/gettingstarted/introduction/","summary":"The Beacon SDK is a toolset designed to enhance and streamline the development of virtual tabletop (VTT) character sheets and other interactive elements.","tags":[],"title":"Introduction"},{"content":"This installation guide is designed for sheet developers with experience in web development, that want to start creating a character sheet from scratch or already have an existing project they wish to add Beacon to.\nTo get started quickly with a boilerplate, you can download and start editing the Quick Start Example Sheet which already has the Beacon SDK installed, along with several recommanded patterns implemented in a Vue.js project.\nPrerequisites Before you can install the Beacon SDK, you\u0026rsquo;ll need to have the following:\nA local web development environment with a code editor. Node.js installed on your machine. If you don\u0026rsquo;t have Node.js installed, use the following steps in the official Node.js documentation. A javascript project, we recommand Vue.js but you can choose whichever you are more comfortable with. These steps use npm but you are free to use any package manager and framework you prefer.\nThe following steps will guide you in installing the Beacon SDK in your application:\nStep 1: Add the package to your project You can find the latest version of the package on the NPM registry.\nIn your project\u0026rsquo;s directory, run the following:\nnpm i @roll20-official/beacon-sdk\rThis will install the Beacon SDK package to your project\u0026rsquo;s package.json file.\nStep 2: Use the Beacon package in your project The Beacon package exports various utilities you can use in your application. The main one that needs to be setup to enable the connection between Beacon SDK and Roll20 is initRelay.\nIdeally you would want to call this when your sheet is initalizing, and it is the function where you will define sheet actions, computed values, and how the sheet will response to or send character data changes. visit the initRelay page for a more detailed breakdown.\nAdd the following to your project:\nimport { initRelay } from \u0026#39;@roll20/beacon-sdk\u0026#39;; const dispatch = initRelay({ handlers: { onInit: ({ character } ) =\u0026gt; { console.log(\u0026#39;sheet character\u0026#39;, character) }, onChange: () =\u0026gt; {}, onSettingsChange: () =\u0026gt; {}, onSharedSettingsChange: () =\u0026gt; {}, onTranslationsRequest: () =\u0026gt; {}, onDragOver: () =\u0026gt; {} }, // Refer to our advanced example sheet on how to setup actions and computed properties. actions: {}, computed: {} })\rinitRelay returns a dispatch function that allows you to call methods or send changes from the sheet to Roll20. Check out the page on dispatch to learn more about the different methods.\nStep 3: Settings up the Roll20 tabletop sandbox On the Roll20 website visit the custom sheet sandbox and create a new sandbox, we\u0026rsquo;ll use this sandbox to develop our sheet but we must set it up to listen to our local project\u0026rsquo;s web server.\nAfter creating a new sandbox, we\u0026rsquo;ll be taken to the sandbox details page, here you will find a collapseable section called Sheet.json Editor, opening this we can add the settings we need to connect to our project:\n{ \u0026#34;advanced\u0026#34;: true, \u0026#34;advancedPort\u0026#34;: 7620 // or the port of your webserver }\rAfter adding these changes make sure to click Save Changes at the bottom of the page. After which you can click Launch Game on the page to go into the game and start testing your sheet.\n","date":"2024-04-07","id":4,"permalink":"/docs/gettingstarted/installing-beacon/","summary":"This installation guide is designed for sheet developers with experience in web development, that want to start creating a character sheet from scratch or already have an existing project they wish to add Beacon to.","tags":[],"title":"Installing Beacon"},{"content":"Background: The background color of the alert box.\nCharacter: An entity in the game with attributes, bio, GM notes, and a token representation.\nCharacter sheet: A digital or printed page used to track a character\u0026rsquo;s attributes, abilities, and other relevant information in a role-playing game.\nComputed Property: Properties that have both get and set methods, which can be dynamically calculated.\nConvertLegacyMacroAttributes: A function to handle mapping legacy macro attributes to the new Beacon Sheet format.\nDispatch: A set of functions enabling the sheet to send commands back to the VTT.\nGM (Game Master): The person who runs the game, controls the NPCs \u0026amp; the story, and provides challenges for the players.\nHandler: Methods that act as event handlers to process messages from the host.\nInitRelay: Function to initialize the SDK relay, setting up communication between the host and the character sheet.\nMacro: A script that automates repetitive tasks in the VTT.\nRoll Template: A predefined format for displaying the results of a dice roll.\nToken: A visual representation of a character or object on the virtual tabletop, with various properties like position, size, and attributes.\nVTT (Virtual Tabletop): An online platform that allows players to play tabletop role-playing games over the internet.\nValidationMessage: A message displayed when an input value does not meet specific criteria.\nQuantum Roll: A system that ensures the fairness and authenticity of dice rolls in the VTT by using cryptographic methods.\n","date":"2024-03-07","id":5,"permalink":"/docs/about/glossary/","summary":"Background: The background color of the alert box.\nCharacter: An entity in the game with attributes, bio, GM notes, and a token representation.","tags":[],"title":"Glossary"},{"content":"\rQ: How is Beacon better than the old way of building sheets (known as Custom Sheets)?\rIt depends on your web development skill level. There are a number of benefits to the Beacon SDK if you know how to build web applications. If you don\u0026rsquo;t know how to set up your own local environment, than the Beacon SDK might now be the first place you should start. Learn more about sheet development using the custom sheet.\nIf you have the skill to take advantage of the Beacon SDK, there are a number of improvements that will make it much easier to build characters sheets.\nFirst, the Beacon SDK allows you to develop locally and preview your changes automatically in the Roll20 Tabletop and Roll20 Character sandboxes. This means that you don\u0026rsquo;t have to keep uploading your HTML and CSS into the custom sheet to see your changes.\nNext, it allows you to develop your character sheet with all the power of JavaScript frameworks and modern web development libraries. In our example sheets, we use Vue.js, but you are free to use whatever you are most comfortable with. Also, you could use something like Cypress to create automated testing. That\u0026rsquo;s what we use in our Beacon sheets.\nLastly, the Beacon SDK makes it much easier for a web developer who knows JSON and Javascript to access character data and manage attributes on the character. If you\u0026rsquo;re familiar with the custom sheet, you no longer have to deal with sheet workers to get the data you need for a character. Also, the Beacon SDK introduces nested and computed attributes that make complex data models for your character sheet easier to create and maintain.\nQ: I\u0026rsquo;m not really a web developer, should I use Beacon or the custom sheet to make a my own character sheet?\rThat is up to you and your comfort level. If you\u0026rsquo;re looking to learn more about web development, building a character sheet with the Beacon SDK is a great way to level up your skills. What you learn during this process can be taken with you into any other web development project you work on in the future.\nIf setting up your own development environment is too intimidating for you, than it might be easier for you to start with the custom sheet and to go from there.\nQ: I\u0026rsquo;m interested in using Beacon, but I don\u0026rsquo;t know the basics of setting up a local environment. Where can I go to learn more about web development?\rYou can start learning how to build a local development environment by reading or watching the following tutorials. Note: these are not tutorials that we\u0026rsquo;ve produced, but we have found them helpful in getting started with web development.\nhttps://learn.microsoft.com/en-us/windows/dev-environment/javascript/vue-on-wsl https://www.youtube.com/watch?v=WPqXP_kLzpo Q: Now that Roll20 has acquired Demiplane, will you continue to support character sheets built on Beacon?\rThe recent acquisition of Demiplane brings exciting new opportunities for character sheets and compendiums on Roll20. At the same time, we are fully committed to supporting the Beacon SDK and character sheets that are built in our new advanced sheets ecosystem on Roll20. In fact, we believe that the Beacon SDK will be a key component of our future plans for Demiplane integration. In addition, our new D\u0026amp;D 2024 sheet is built on top of the Beacon SDK, and we will continue to utilize it to build first-class experiences on Roll20.\nIn short, you can rest assured that the Beacon SDK is an important tool in our toolbox moving forward.\nQ: What are actions in the context of Beacon?\rActions are methods executed in the chat log of Roll20 Tabletop or Roll20 Characters, often used for rolls triggered from macros or chat buttons. They are defined in the sheet\u0026rsquo;s configuration and can interact with character data. Q: How are computed properties used in Roll20?\rComputed properties are attributes which are accessible by users of your character sheet. They are usable in macros to create custom rolls or common actions for each character. Computed properties can represent derived values or complex calculations based on character data. Q: What is the dispatch function used for?\rThe dispatch function provides methods for sending commands from the character sheet back to Roll20, including updating character data, performing actions, and interacting with the interface. Q: What are roll buttons, and how do they work?\rRoll buttons are HTML elements with specific attributes that execute designated sheet actions when clicked. They can pass arguments to the action method and are commonly used for triggering rolls from the character sheet. Q: How are legacy attributes handled in Beacon?\rBeacon gives you the ability to transition your legacy attributes to new attributes you create in Beacon. This means that when a user updates their sheet to the new Beacon sheet, their legacy attribute can be mapped to Beacon attributes using the convertLegacyMacroAttributes function. Sheet developers can define how to handle legacy attribute values to ensure compatibility with existing macros. Q: What is the purpose of the query function?\rThe query function displays a SweetAlert2 prompt to users and returns the results along with any errors. It is commonly used for interactive prompts or confirmations within the VTT interface. Q: How are tokens managed in the VTT?\rTokens represent characters or objects on Roll20 Tabletop (VTT). Functions like getTokens, updateTokensByCharacter, and addToTracker are used to retrieve token information, update token data, and manage tokens in the turn tracker. Q: What is the role of the convertLegacyMacroAttributesArgs type?\rThe convertLegacyMacroAttributesArgs type defines the arguments used for handling legacy macro attributes. It includes the attribute name, character ID, and character data needed for mapping legacy attributes to the new sheet structure. ","date":"2024-01-07","id":6,"permalink":"/docs/about/faq/","summary":"Q: How is Beacon better than the old way of building sheets (known as Custom Sheets)?\rIt depends on your web development skill level.","tags":[],"title":"FAQ"},{"content":"The Beacon SDK is composed of various methods and components that allow developers to create dynamic and interactive character sheets for virtual tabletop (VTT) games. initRelay is the main method that initializes the Beacon SDK communication channel with the host (Either the Roll20 tabletop or in Roll20 Characters). It should be initialized as soon as the sheet loads, as its onInit handler will be the earliest we can get access to that character\u0026rsquo;s data.\ninitRelay({ handlers: { onInit, onChange, onSettingsChange, onSharedSettingsChange, onTranslationsRequest, onDragOver, onDropOver, }, actions: {}, computed: {}, convertLegacyMacroAttributes, handleLegacyRollTemplates }): Promise\u0026lt;Dispatch\u0026gt;\rThese components are crucial for handling actions, computations, macros, and rolls. This overview provides a high-level summary of each section, helping you understand their roles and how they integrate within the SDK.\nActions\rActions define specific operations that can be performed by characters within the VTT. These operations can range from simple tasks like rolling a dice to more complex interactions such as casting spells or activating abilities.\nHandlers\rHandlers are event listeners that manage communication between the VTT and the character sheet. They respond to various events, such as changes in character attributes or settings, and trigger appropriate actions or updates.\nComputed\rComputed properties are dynamic values derived from other character attributes. They allow for the creation of complex, calculated attributes that automatically update when their dependencies change.\nMacro Attributes\rMacro attributes handle the conversion of legacy macro attributes to the new format used in the Beacon SDK. This ensures compatibility with older character sheets and macros, allowing for a smooth transition to the new system.\nRolls\rThe Rolls component allows for advanced dice-rolling mechanics within the VTT. It supports both simple and complex rolls, providing flexibility in how roll results are displayed and computed.\nDispatch\rThe dispatch object provides methods for sending commands from the character sheet back to the host. Except when specified every method returns a promise.\n","date":"2024-06-07","id":7,"permalink":"/docs/components/initrelay/","summary":"The Beacon SDK is composed of various methods and components that allow developers to create dynamic and interactive character sheets for virtual tabletop (VTT) games.","tags":[],"title":"InitRelay"},{"content":"Actions are a collection of methods that can be executed from the VTT. These actions are used for any rolls that may need to be triggered outside of the sheet itself, such as from a macro or a chat button. Generally, most or all of a sheet’s rolls should be defined as actions.\nactions: { [name: string]: { method: (props: { dispatch: Dispatch, character: Character, messageId?: string, rolls?: RollResults }, ...args: string[]): void | Promise\u0026lt;void\u0026gt; } }\rActions are passed into the initRelay function in an object, where the keys are the unique names of the actions, and the values are objects containing a method property (additional metadata fields may be added to this object in the future).\nThe method receives a props object containing the following properties:\ndispatch: A Dispatch object. character: The data of the character performing the action. Currently, the action will not receive the character’s bio or GM notes, regardless of whether the player has access to those fields. messageId (optional): A unique ID for an existing chat message. It\u0026rsquo;s included in actions triggered from chat buttons to provide context for the original roll. rolls (optional): Included when action is triggered from a chat button. Contains the roll results of the original roll. These functions can also receive an unlimited number of additional arguments. This is because these actions can be triggered by plain text via a macro. However, all additional arguments must be strings. Additionally, these functions can be synchronous or asynchronous and do not return a value.\n","date":"2024-05-07","id":8,"permalink":"/docs/components/actions/","summary":"Actions are a collection of methods that can be executed from the VTT. These actions are used for any rolls that may need to be triggered outside of the sheet itself, such as from a macro or a chat button.","tags":[],"title":"Actions"},{"content":"","date":"2024-04-07","id":9,"permalink":"/docs/components/","summary":"","tags":[],"title":"Components"},{"content":"Sheet authors define computed properties that are accessed by the host. These computed properties can be used as attributes in macros and are available to assign as values to token bars - if the tokenBarValue property is set to true.\ncomputed: { [name: string]: { tokenBarValue?: boolean, description?: string, get: ( props: { character: Character }, ...args: string[] ) =\u0026gt; ComputedResult, set?: ( props: { character: Character, dispatch: Dispatch }, ...args: string[] ) =\u0026gt; void | Promise\u0026lt;void\u0026gt; } }\rComputed properties are passed into the initRelay function in an object where the keys are the names of the properties, and the value should be an object containing the following:\nget (required): It receives character data along with any number of string parameters and should return the computed value. tokenBarValue (optional): A boolean indicating whether this property should be available for use in token bars. description (optional): A text value indicating what this computed summary property represents. set (optional): This method receives character data and a dispatch, along with string arguments. This method does not need to return a value. Setting tokenBarValue to true will make the property available to use as a value for token bars. To work correctly, the get function must not rely on any additional arguments and must return either a simple value (a string or number) or an object: { current: number | string, max: number | string }\rIf the set function is omitted, the value will not be editable from the token itself. If defined, set methods will receive one string argument, which is whatever the user types into the input for modifying the bar. ","date":"2024-04-07","id":10,"permalink":"/docs/components/computed/","summary":"Sheet authors define computed properties that are accessed by the host. These computed properties can be used as attributes in macros and are available to assign as values to token bars - if the tokenBarValue property is set to true.","tags":[],"title":"Computed"},{"content":"Handler functions allow the sheet to respond to messages from the host. The handlers argument requires the following methods:\nonInit The onInit function provides the initial set of data to the sheet.\nonInit(e: { character: Character, settings: { colorTheme: string, language: string, gm: boolean, owned: boolean, settingsSheet: boolean, headless: boolean, sandbox: boolean, campaignId: number, environment: string, currentUserId: string, singleSheet: boolean }, sharedSettings: {}, compendiumDropData: { pageName: string, categoryName: string, expansion: number } }, dispatch: Dispatch): void;\rThe event object contains the following:\ncharacter: The primary character for this sheet. settings: Campaign and character-specific settings. sharedSettings: Data shared between all characters in this campaign. compendiumDropData: Populated when the character sheet is created from a compendium entry such as a creature or NPC. This function may be called multiple times during development in the sheet sandbox as part of hot reloads.\nonChange onChange is called whenever a character’s data is changed on the host’s end. The event object contains a partial character with only the character’s ID and the changed data. This could be the character’s bio, GM notes, or attributes (only the changed attributes).\nonChange(e: { character: Partial\u0026lt;Character\u0026gt; }, dispatch: Dispatch): void;\ronSettingsChange onSettingsChange is called when either the VTT’s color theme is changed, or when the current player’s ownership of the primary character changes.\nonSettingsChange(e: { colorTheme: string, owned: boolean }, dispatch: Dispatch): void;\ronSharedSettingsChange onSharedSettingsChange is called when someone changes a shared setting in the VTT.\nonSharedSettingsChange({ settings: { [key: string]: any } }): void;\ronTranslationsRequest onTranslationsRequest is called before the relay is fully initialized and returns the translation JSON data corresponding to the two-letter language argument.\nonTranslationsRequest(language: string): { [key: string]: string };\ronDragOver (optional) onDragOver is called when a compendium item from the compendium tab is dragged over the iframe window containing the character sheet.\nCoordinates of the drag are provided via top and left values, and basic compendium data is passed so that a subsequent compendium request can be made via the provided dispatch. If the item is moved outside of the iframe, dragData and coordinates are null.\nonDragOver(e: { coordinates: { top: number, left: number }, dragData: { pageName: string, categoryName: string, expansionId: number } | null }, dispatch: Dispatch): void\ronDropOver (optional) onDropOver is called when a compendium item from the compendium tab is dropped over the iframe window containing the character sheet.\nCoordinates of the drop are provided via top and left values, and basic compendium data is passed so that a subsequent compendium request can be made via the provided dispatch.\nonDropOver(e: { coordinates: { top: number, left: number }, dropData: { pageName: string, categoryName: string, expansionId: number } }, dispatch: Dispatch): void\r","date":"2024-03-07","id":11,"permalink":"/docs/components/handlers/","summary":"Handler functions allow the sheet to respond to messages from the host. The handlers argument requires the following methods:\nonInit The onInit function provides the initial set of data to the sheet.","tags":[],"title":"Handlers"},{"content":"","date":"2024-02-07","id":12,"permalink":"/docs/about/","summary":"","tags":[],"title":"About"},{"content":"When utilizing Macros within the VTT, there are instances where a legacy macro might need to be employed for a Beacon sheet.\nThis scenario commonly arises when transitioning from an existing legacy sheet to a Beacon sheet. During such transitions, it\u0026rsquo;s possible that the attributes called from the legacy macro may not align with the structure of attributes in the Beacon Sheet.\nThe convertLegacyMacroAttributes function serves as a pivotal tool, empowering Sheet Developers to determine the mapping strategy for legacy attributes to the new Beacon Sheet.\nconvertLegacyMacroAttributes This function is defined during the initial SDK initialization process and is invoked by the host when it encounters a failure in locating an attribute\u0026rsquo;s value.\nconvertLegacyMacroAttributes: (messages: convertLegacyMacroAttributesArgs) =\u0026gt; {}: any\rAdvanced sheet macros typically first search through the defined computed properties before resorting to the convertLegacyMacroAttributes function.\nThe function\u0026rsquo;s purpose is to return a value that will be substituted in the macro. However, it grants Sheet Developers the autonomy to devise their preferred approach for handling legacy attribute values.\n","date":"2024-02-07","id":13,"permalink":"/docs/components/handling-legacy-macro-attributes/","summary":"When utilizing Macros within the VTT, there are instances where a legacy macro might need to be employed for a Beacon sheet.","tags":[],"title":"Handling Legacy Macro Attributes"},{"content":"Release Date: 2022-03-17\nNew Features Initial release of the Beacon SDK. Support for Vue.js framework. Setup with Vite for rapid development. Basic and advanced sheet examples. Improvements Detailed comments added to example files for better understanding. Support for complex roll templates and rich sheet actions. Bug Fixes N/A (initial release). Version 2.0.0 Release Date: 2023-03-17\nNew Features SCSS support for styling. Integration with Roll20 and VTT. Mock Relay for offline development. Improvements TypeScript integration for type checking and improved development experience. Unit testing with Vitest. End-to-End testing with Cypress. Bug Fixes N/A (initial release). ","date":"2024-01-07","id":14,"permalink":"/docs/about/changelog/","summary":"Release Date: 2022-03-17\nNew Features Initial release of the Beacon SDK. Support for Vue.js framework. Setup with Vite for rapid development.","tags":[],"title":"Changelog"},{"content":"The VTT (Virtual Tabletop) has several new features that enhance the way rolls are handled and displayed. These features include attributes and elements that allow for dynamic roll results and interactivity within the VTT environment.\ndata-rollname The data-rollname attribute tells the VTT that this HTML element is displaying the result of a roll.\n\u0026lt;span data-rollname=\u0026#34;attack\u0026#34;\u0026gt;\u0026lt;/span\u0026gt;\rThe VTT will both add the Quantum Roll signature tooltip to the element and replace the contents of the element with the result from the roll.\nThis is the preferred method for displaying roll results wherever possible, that is, sending the whole roll formula to the roll server and allowing the VTT to display the result.\ndata-computed Tagging an element with both a data-rollname and a data-computed=\u0026quot;true\u0026quot; tells the VTT that this element is associated with a roll, but the results of that roll were computed by the author, as opposed to the roll server computing the result.\n\u0026lt;span data-rollname=\u0026#34;complex\u0026#34; data-computed=\u0026#34;true\u0026#34;\u0026gt;25\u0026lt;/span\u0026gt;\rThe VTT will add the Quantum Roll signature tooltip, but the content of the element will not be modified. Generally, this should only be used when the roll server does not support a particular dice mechanic.\nRoll Buttons Roll buttons are interactive elements that trigger sheet actions, such as damage rolls, when clicked. These buttons use the data-sheet-action attribute to specify the action to be executed.\n\u0026lt;button data-sheet-action=\u0026#34;damage\u0026#34; data-args=\u0026#34;arg1:arg2\u0026#34;\u0026gt;Click Me\u0026lt;/button\u0026gt;\rAdditional arguments can be provided using the data-args attribute, and the character, messageId, and original rolls will be included automatically.\n","date":"2024-01-07","id":15,"permalink":"/docs/components/rolls/","summary":"The VTT (Virtual Tabletop) has several new features that enhance the way rolls are handled and displayed. These features include attributes and elements that allow for dynamic roll results and interactivity within the VTT environment.","tags":[],"title":"Rolls"},{"content":"The dispatch is returned by the initRelay and provides methods for sending commands from the character sheet back to the host. Except when specified every method below will return a promise.\nupdate dispatch.update({ options: { overwrite?: boolean } character: Partial\u0026lt;Character\u0026gt; }): Promise\u0026lt;void\u0026gt;\rThe update method sends character changes to the host (Roll20 Tabletop or Roll20 Characters) to be persisted. The partial character passed in here must contain the character\u0026rsquo;s id, and can contain any combination of the attributes, bio, and gmNotes properties. When updating a character’s attributes, only include those attributes that have changed.\nupdateCharacter dispatch.updateCharacter({ character: Partial\u0026lt;Character\u0026gt; }): Promise\u0026lt;void\u0026gt;\rLike the update method, updateCharacter sends character changes to the host page (Roll20 Tabletop or Roll20 Characters) to be persisted. However, this method takes a full set of character attributes as the character argument, and automatically computes the diff with existing character attributes, so that only changed attributes are sent to the data store.\nroll dispatch.roll({ rolls: { [rollName: string]: string } // Ex. {attack: \u0026#39;1d20+4\u0026#39;, damage: `3d6+2`} messageId?: string }): Promise\u0026lt;{messageId: string, results: RollResults }\u0026gt;\rThe roll method takes one or more rolls in the form of an object, where the keys are unique roll names and the values are roll strings. messageId can be provided to attach the roll to an existing chat message, either overriding it or appending to it in the chat log. If messageId is omitted, the roll will be associated with a new chat message and a new messageId for that message will be returned with the roll results. The method returns a promise that resolves with an object containing the messageId and the RollResult (see Types). The roll result is returned in the same format as in the non-beacon dice rolls computed roll system.\npost dispatch.post({ characterId: string, messageId?: string, content: string, options?: { whisper?: \u0026#39;gm\u0026#39;, secret?: boolean, } }): Promise\u0026lt;string\u0026gt;\rpost posts a message to chat, either creating a new message or overwriting an existing one. It requires a character id and message content, a string containing either plain text or HTML to be posted. The method also accepts an options object. Currently, only whisper and secret are supported, the only valid value for whisper is gm, which will send the message as a whisper to the gm. The secret option is ignored unless whisper is also set, toggling to true will cause the message to not be visible to the controlling player. Like roll, messageId can be provided to update an existing chat message, but if omitted the method will generate a new messageId and post a new chat message. The method returns the messageId.\nquery dispatch.query(options: Swal2Options): { isConfirmed: boolean, isDenied: boolean, isDismissed: boolean, value?: string | number, dismiss?: \u0026#34;cancel\u0026#34; | \u0026#34;backdrop\u0026#34; | \u0026#34;close\u0026#34; | \u0026#34;esc\u0026#34; | \u0026#34;timer\u0026#34;, errors?: string[], }: Promise\u0026lt;{ results: { isConfirmed: boolean isDenied: boolean isDismissed: boolean value: string | number dismiss: string }, errors: [string] }\u0026gt;\rThe query method takes an options object and uses them to display a SweetAlert2 prompt to the user. It returns the results of the query as a SweetAlertResult, along with any errors encountered. The options work exactly as described in the documentation for SweetAlert2, however not all options are allowed. Here is a list of the allowed options:\ntitleText, text, iconColor, input, width, padding, background, position, grow, timer, timerProgressBar, showConfirmButton, showDenyButton, showCancelButton, ariaLabel, confirmButtonText, denyButtonText, cancelButtonText, confirmButtonAriaLabel, confirmButtonColor, cancelButtonAriaLabel, cancelButtonColor, denyButtonAriaLabel, denyButtonColor, reverseButtons, showCloseButton, closeButtonAriaLabel, returnInputValueOnDeny, imageUrl, imageWidth, imageHeight, imageAlt, inputLabel, inputPlaceholder, inputValue, inputOptions, inputPlaceholder, inputAutoTrim, inputAttributes, validationMessage, progressSteps, currentProgressStep, progressStepsDistance.\nPerform dispatch.perform({ characterId: string, action: string, args: string[], }): Promise\u0026lt;void\u0026gt;;\rperform executes the specified action on behalf of the character (designated by the character id), passing in args to the action method. This method can perform actions on behalf of any character, even a character that the sheet does not have data for.\ngetComputed dispatch.getComputed({ characterId: string, property: string, args: string[] }): Promise\u0026lt;string | number | object\u0026gt;\rsee setComputed below\nsetComputed dispatch.setComputed({ characterId: string, property: string, args: string[] }): Promise\u0026lt;string | number | object\u0026gt;\rgetComputed and setComputed are both nearly identical in how they are called, taking a character id and a property with the name of the computed property you wish to get or set, and an array of string args. Both methods return a promise that resolves with the computed value.\ncompendiumRequest dispatch.compendiumRequest({ query: string }): Promise\u0026lt;{ data: Object errors: Array\u0026lt;Error\u0026gt; extensions: Record\u0026lt;string, any\u0026gt; }\u0026gt;\rcompendiumRequest executes an AJAX request to the compendium service’s graphQL endpoint. It takes in a graphQL query string written according to the Compendium service’s schema. The query string does not need to include the ruleSystem shortName as this is set automatically according to the campaign override or sheet.json value in the Roll20 Tabletop.\ndebouncedCompendiumRequest dispatch.debouncedCompendiumRequest({ query: string }): Promise\u0026lt;{ data: Object }\u0026gt;\rLike compendiumRequest, except that calls to this method are automatically debounced (at 100ms) and grouped together into a single request to the compendium service. Note that this method will only return the requested data, it does not return errors or extensions.\ngetTokens dispatch.getTokens({ characterId: string }): Promise\u0026lt;{ selected: Token[], tokens: Token[] }\u0026gt;: Promise\u0026lt;{ selected: Token[] tokens: Token[] }\u0026gt;\rgetTokens requires a character id string and returns information about tokens on the user’s current page. The return value contains two arrays of tokens. The tokens array contains all tokens on the current page that represent the character whose id was provided to the method. The selected array contains any tokens that are currently selected, regardless of which character they represent. The returned token objects contain all of the token attributes available to the API, you can find documentation here and here.\naddToTracker dispatch.addToTracker({ tokenId?: string, custom?: { name: string img?: string } formula?: string value: string | number }): Promise\u0026lt;void\u0026gt;\raddToTracker adds or updates a single item in the turn tracker. Passing in a tokenId will add the specified token to the tracker, while passing in custom with a name and an optional image url (img) will add a custom item, not connected to any character or token. A round calculation string can be added via the optional formula parameter. value is the initiative number for the item.\naddActionsToHost dispatch.addActionsToHost({ sheetAction?: { characterId: string action: string args?: string[] } action?: string locations?: [\u0026#39;macroBar\u0026#39;] | [\u0026#39;tokenActionBar\u0026#39;] | [\u0026#39;macroBar\u0026#39;, \u0026#39;tokenActionBar\u0026#39;] actionId?: string name: string requestId?: string }): void\raddActionsToHost adds a specific action(macro) to an area of the Roll20 Tabletop UI; either the macrobar or the token action bar. Either sheetAction or action can be passed in but not both at the same time. The sheetAction arg should be passed in when an the action is to designated to a character. While the action arg should be passed in when the action is more generic.\ngetActions dispatch.getActions({ args: { characterId?: string } }): Promise\u0026lt;{ actions?: {} | { [id: string]: ActionFromHost } }\u0026gt;\rgetActions gets a specific character’s actions(macro).\nsetContainerSize dispatch.setContainerSize({ args: { width?: number height?: number } }): Promise\u0026lt;void\u0026gt;\rsetContainerSize updates the size of the container which holds the sheet shared settings. Returns a promise that can be awaited. This can be used in conjunction with something like the ResizeSensor event listener from npm: css-element-queries to automatically resize the container on the host.\nupdateTokensByCharacter dispatch.updateTokensByCharacter({ args: { characterId: string token: Partial\u0026lt;Token\u0026gt; } }): Promise\u0026lt;void\u0026gt;\rupdateTokensByCharacter updates a particular character’s default token as well as all existing tokens representing that character. Returns a promise that can be awaited.\nupdateTokensByIds dispatch.updateTokensByIds({ args: { tokenIds: array of ids as strings token: Partial\u0026lt;Token\u0026gt; } }): Promise\u0026lt;void\u0026gt;\rupdateTokensByIds updates a single or several tokens. Returns a promise that can be awaited.\nautoLinkText dispatch.autoLinkText({ args: { text: string } }): Promise\u0026lt;string\u0026gt;\rautoLinkText goes through the text to find handout names between square brackets and converts them into links with the handoutID. For example in a game with a handout named Dragon, passing in the text string of this is a [Dragon] to autoLinkText returns something similar to this is a \u0026lt;a href=\u0026quot;https://journal.roll20.net/8je02j0kd02k\u0026quot;\u0026gt;Dragon\u0026lt;/a\u0026gt;.\nopenDialogFromLink dispatch.openDialogFromLink({ args: { urlString: string } }): void\ropenDialogFromLink opens the supplied urlString through the Roll20 Tabletop.\nIf the url is for a handout, it will open the corresponding handout in the campaign. This will also check if the user opening the link has access to the handout. If the url is for a compendium, it will open a pop up to the compendium page, it will also check to ensure the user has access to view the page. If the url is for an external page, a confirmation pop up will display to warn the user that the link is for an external site and open a new tab in their main window if confirmed. ","date":"2023-09-07","id":16,"permalink":"/docs/components/dispatch/","summary":"The dispatch is returned by the initRelay and provides methods for sending commands from the character sheet back to the host.","tags":[],"title":"Dispatch"},{"content":"Prerequisites To set this sheet up properly, make sure that you have the following tools installed:\nVue.js Vite SCSS Figure 1: Quickstart sheet\nUse the following steps to get started:\nInstall the Beacon SDK: Run the following command. npm i @roll20-official/beacon-sdk\rInstall dependencies: Install the dependencies for the project. npm install\rStart the Vite server: After installing the project\u0026rsquo;s dependencies, you\u0026rsquo;ll need to start the Vite server. There are two ways to do this: a. Offline Development: This method will run the Vite server with the default port and environment set to development.\nnpm run dev\rOnce this code executes successfully, you can access the Vite server at http://localhost:5173.\nThis method is useful when you do not have access to the Roll20 website or would like to work on parts of your project that do not depend on a connection to the VTT or Roll20 Characters, such as working on styling, mocking up the environment, building Vue components, testing functionality, etc.\nIn development mode, you cannot save or access existing character data or use the Beacon SDK functions that depend on VTT or Roll20 Characters functionality, such as dice rolling and token manipulation.\nb. Sandbox Development: This method will run the Vite server with the port set to 7620 and the environment set to staging mode.\nnpm run sandbox\rThis command will build the SCSS files and then run the Vite server. This will set the server up for connecting to a VTT custom sheet sandbox as well as through the sandbox in Roll20 Characters.\nTo test your changes in the VTT custom sheet sandbox, you will need to add the following to the sheet.json editor in the game settings:\n{ \u0026#34;advanced\u0026#34;: true, \u0026#34;advancedPort\u0026#34;: 7620 }\rUseful Commands The following set of commands can come in handy when working with this sheet:\nFor Hot reloading and building CSS files, use the following command: npm run watch-scss\rFor linting, use the following command: npm run lint\rFor formatting with Prettier, use the following command: npm run format\r","date":"2024-04-07","id":17,"permalink":"/docs/gettingstarted/quick-start-sheet-template/","summary":"Prerequisites To set this sheet up properly, make sure that you have the following tools installed:\nVue.js Vite SCSS Figure 1: Quickstart sheet","tags":[],"title":"Quick Start Sheet Template"},{"content":"Prerequisites To set this sheet up properly, make sure that you have the following:\nVue framework \u0026amp; Routing Multiple Data Stores Complex Roll Templates Rich Sheet Actions TypeScript Vite SCSS Ability to run Unit \u0026amp; End-to-End Tests Figure 1: Advanced sheet\nThis sheet uses the same steps listed in the . Immediately after implementing those three steps, you\u0026rsquo;ll add the following step:\nRun a CI check: This will run several checks to ensure your code is as optimal as possible, including formatting, linting, type checking, unit tests, and end-to-end tests. npm run ci-check\rYou can think of this command as a sanity check you can leverage when pushing a big release for your sheet!\nUseful Commands The following set of commands can come in handy when working with this sheet:\nFor Hot reloading and building CSS files, use the following command: npm run watch-scss\rFor linting, use the following command: npm run lint\rFor formatting with Prettier, use the following command: npm run format\rFor type checking with TypeScript, use the following command: npm run type-check\rFor running unit tests with Vitest, use the following command: npm run test:unit\rTo open up and develop local end-to-end tests with Cypress, use the following command: npm run test:e2e:open:local\rFor running local end-to-end tests with Cypress, use the following command: npm run test:e2e:local\rTo run CDN-hosted end-to-end tests with Cypress, use the following command: npm run test:e2e\r","date":"2024-03-07","id":18,"permalink":"/docs/gettingstarted/example-patterns-sheet/","summary":"Prerequisites To set this sheet up properly, make sure that you have the following:\nVue framework \u0026amp; Routing Multiple Data Stores Complex Roll Templates Rich Sheet Actions TypeScript Vite SCSS Ability to run Unit \u0026amp; End-to-End Tests Figure 1: Advanced sheet","tags":[],"title":"Example Patterns Sheet"},{"content":"We appreciate your interest in contributing to the Beacon SDK project. Here are some guidelines to help you get started:\nHow to Contribute Reporting Bugs If you find a bug, please report it by opening an issue in the GitHub repository. Provide as much detail as possible to help us understand and reproduce the issue.\nSuggesting Features We welcome suggestions for new features. Please open an issue in the GitHub repository with a detailed description of the feature you would like to see and why you think it would be useful.\nCode Contributions Fork the Repository: Create a personal fork of the project on GitHub.\nClone the Fork: Clone your fork to your local machine.\ngit clone Create a Branch: Create a new branch for your work.\ngit checkout -b feature-or-bugfix-description\rMake Changes: Make your changes to the codebase. Follow the existing code style and conventions.\nRun Tests: Ensure that all tests pass before submitting your changes.\nnpm run ci-check\rCommit Changes: Commit your changes with a descriptive commit message.\ngit commit -m \u0026#34;Description of your changes\u0026#34;\rPush Changes: Push your changes to your fork.\ngit push origin feature-or-bugfix-description\rCreate a Pull Request: Open a pull request from your fork to the main repository. Provide a detailed description of your changes and why they should be merged.\nRunning Tests Unit Tests: Run unit tests with Vitest.\nnpm run test:unit\rEnd-to-End Tests: Run End-to-End tests with Cypress.\nnpm run test:e2e\rCode Style Follow the existing code style and conventions.\nUse ESLint for linting.\nnpm run lint\rFormat code with Prettier.\nnpm run format\rCommunication GitHub Issues: Use GitHub issues for bug reports, feature requests, and questions. Pull Requests: Use GitHub pull requests to submit your code contributions. Thank you for contributing to the Beacon SDK project!\n","date":"2024-02-07","id":19,"permalink":"/docs/about/how-to-contribute/","summary":"We appreciate your interest in contributing to the Beacon SDK project. Here are some guidelines to help you get started:","tags":[],"title":"How to Contribute"},{"content":"A release sheet is a finalized version of a character sheet or other content designed for use on the Roll20 platform. This sheet includes all the necessary code, assets, and metadata packaged together to be easily shared, tested, and eventually deployed on Roll20.\nWhen you\u0026rsquo;re ready to test and share a sheet on Roll20, you\u0026rsquo;d want to do it in such a way that others who might need it won\u0026rsquo;t have to set it up with a local dev environment.\nThat\u0026rsquo;s what the steps below help you achieve. In this guide, you can make your sheet available in the Roll20 Tabletop and Characters.\nSteps to Release a Test Sheet The following steps will aid you while releasing your sheet:\nCreate a Build Command:\nYou must have a build command that will produce the minified production-ready code. You can find an example in our Quickstart Package JSON. The build command must be able to create these exact files:\nsheet.js sheet.css host.css (optional) Add a local folder that contains fonts and images used in the sheet (optional). Add a sheet.json file:\nAdd a sheet.json file to your sheet folder to ensure the metadata for your sheet is up-to-date. For this, you can also find an example in our Quickstart Package JSON.\nCreate a Pull Request in the Community Sheet Repo:\nIn the Community Sheet Repo, create a pull request that must include the submission checklist from our previous process.\nSubmission Checklist When submitting a new or updated sheet to Roll20, it\u0026rsquo;s essential to follow the guidelines to ensure a smooth review and approval process.\nBelow is a checklist to help you prepare your submission.\nRequired The following are the required submission checklist items:\nThe pull request title clearly contains the name of the sheet I am editing. The pull request title clearly states the type of change I am submitting (New Sheet/New Feature/Bugfix/etc.). The pull request makes changes to files in only one sub-folder. The pull request does not contain changes to any JSON files in the translations folder (translation.json is permitted). New Sheet Details You must include the following information in your sheet:\nThe name of this game is: \u0026lt; THE AETHYRBLOOD CHRONICLES \u0026gt;. The publisher of this game is: \u0026lt; HAPHAZARD PROJECTS \u0026gt; The name of this game system/family is: \u0026lt; DPS System ('dice pool scales') \u0026gt; You must also check out the following:\nI have followed the Character Sheets Standards when building this sheet. I have authorization from the game\u0026rsquo;s publisher to make this an official sheet on Roll20 with their name attached. This game is not traditionally published, but a copy of the game rules can be purchased/downloaded/found at The Aethyrblood Chronicles Core Rule Book In the pull request comments, make sure to list the email addresses of the Roll20 users you\u0026rsquo;d like to have access to the sheet.\nWe can always grant more people access to the sheet after it is released. However, you can inform us in our Official Community Sheet Development Channels on Discord.\nApproval and Access:\nAfter you create a pull request, our team will approve it and add your sheet to the sheet selection in Roll20 Tabletop and Characters. We will then give only your Roll20 user and any others you\u0026rsquo;ve listed in the pull request comments access to the sheet in Roll20. This sheet will then be available for you and others with access to test it.\nReleasing a Final Version After you have released a test version of your sheet, you can follow the same steps as releasing a test version to make your sheet available to everyone. This time, the pull request comments state that it is a final release version.\nOnce you have created the pull request, our team will review the sheet functionality, code, and metadata for consistency, best practices, and overall system security. We reserve the right to reject any sheet that does not meet our terms of use or conflicts with our partnerships.\n","date":"2024-02-07","id":20,"permalink":"/docs/gettingstarted/releasing-a-sheet/","summary":"A release sheet is a finalized version of a character sheet or other content designed for use on the Roll20 platform.","tags":[],"title":"Releasing a Sheet"},{"content":"Link to valuable, relevant resources.\n","date":"2024-02-27","id":21,"permalink":"/docs/resources/","summary":"Link to valuable, relevant resources.","tags":[],"title":"Resources"},{"content":"","date":"2023-09-07","id":22,"permalink":"/docs/","summary":"","tags":[],"title":"Docs"},{"content":"","date":"2023-09-07","id":23,"permalink":"/privacy/","summary":"","tags":[],"title":"Privacy Policy"},{"content":"","date":"2023-09-07","id":24,"permalink":"/","summary":"","tags":[],"title":"Welcome to Beacon SDK"},{"content":"","date":"0001-01-01","id":25,"permalink":"/categories/","summary":"","tags":[],"title":"Categories"},{"content":"","date":"0001-01-01","id":26,"permalink":"/contributors/","summary":"","tags":[],"title":"Contributors"},{"content":"","date":"0001-01-01","id":27,"permalink":"/tags/","summary":"","tags":[],"title":"Tags"}] \ No newline at end of file +[{"content":"Well-thought-through product announcements will help increase feature awareness and engage users with new functionality. Just like sharing your public roadmap, it\u0026rsquo;s also a great way to let potential customers see that you\u0026rsquo;re constantly improving.\nFurther reading Read How to announce product updates and features ","date":"2023-09-07","id":0,"permalink":"/blog/example-post/","summary":"You can use blog posts for announcing product updates and features.","tags":[],"title":"Example Post"},{"content":"","date":"2023-09-07","id":1,"permalink":"/blog/","summary":"","tags":[],"title":"Blog"},{"content":"","date":"2024-06-07","id":2,"permalink":"/docs/gettingstarted/","summary":"","tags":[],"title":"Getting Started"},{"content":"The Beacon SDK is a toolset designed to enhance and streamline the development of virtual tabletop (VTT) character sheets and other interactive elements.\nWhether you\u0026rsquo;re a game master (GM), a developer, or a player, the Beacon SDK provides a framework to create dynamic, responsive, and fully integrated VTT experiences.\nWhat is the Beacon SDK? The Beacon SDK (software development kit) is a toolset used to create digital character sheets on Roll20 for Roll20 Tabletop and Roll20 Characters.\nWhether you\u0026rsquo;re an experience developer, or just starting out, the Beacon SDK provides a framework to create dynamic, responsive, and fully integrated character sheet experiences.\nThe Beacon SDK also introduces a new way to develop characters sheets for Roll20. Beacon SDK allows you to connect your local development environment to sandboxes in Roll20 Characters and Roll20 Tabletop, giving you real-time updates as you develop.\nKey Features Character Sheets: Design and implement a web app character sheet with dynamic attributes and real-time updates. Local Development: Work where you are most comfortable and get real-time updates in sandboxes in Roll20. Testing Sheets: Release a testing sheet and give others special access to it before you push it live for everyone. Roll Mechanics: Integrate complex roll formulas and display roll results directly within the Roll20 Tabletop and Roll20 Characters. Legacy Support: Convert and integrate legacy macros and roll templates with the new Beacon architecture. Customization: Define custom actions, computed attributes and handle specific roll templates tailored to your game\u0026rsquo;s needs. Components Overview The Beacon SDK is composed of several key components:\nActions: Define and manage custom actions that can be triggered within the VTT. Handlers: Event handlers that process and respond to various VTT events and messages. Computed Attributes: Define dynamically computed attributes based on other attributes. Macro Attributes: Convert and manage legacy macro attributes for compatibility with the Beacon SDK. Rolls: Implement advanced roll mechanics and display results dynamically within the VTT. For a comprehensive overview of these components, view the components section.\nGetting Started To get started with the Beacon SDK, you must initialize the relay, set up your character sheets, and define the necessary actions, handlers, and computed attributes.\nThis documentation provides detailed guides and example sheets to help you through each step of the process.\nBy leveraging the Beacon SDK, you can create rich, interactive, fully integrated VTT experiences that enhance gameplay and streamline game management.\nWhether adapting existing character sheets or building new ones from scratch, the Beacon SDK offers the tools and flexibility to bring your digital character sheet to life.\n","date":"2024-05-07","id":3,"permalink":"/docs/gettingstarted/introduction/","summary":"The Beacon SDK is a toolset designed to enhance and streamline the development of virtual tabletop (VTT) character sheets and other interactive elements.","tags":[],"title":"Introduction"},{"content":"This installation guide is designed for sheet developers with experience in web development, that want to start creating a character sheet from scratch or already have an existing project they wish to add Beacon to.\nTo get started quickly with a boilerplate, you can download and start editing the Quick Start Example Sheet which already has the Beacon SDK installed, along with several recommanded patterns implemented in a Vue.js project.\nPrerequisites Before you can install the Beacon SDK, you\u0026rsquo;ll need to have the following:\nA local web development environment with a code editor. Node.js installed on your machine. If you don\u0026rsquo;t have Node.js installed, use the following steps in the official Node.js documentation. A javascript project, we recommand Vue.js but you can choose whichever you are more comfortable with. These steps use npm but you are free to use any package manager and framework you prefer.\nThe following steps will guide you in installing the Beacon SDK in your application:\nStep 1: Add the package to your project You can find the latest version of the package on the NPM registry.\nIn your project\u0026rsquo;s directory, run the following:\nnpm i @roll20-official/beacon-sdk\rThis will install the Beacon SDK package to your project\u0026rsquo;s package.json file.\nStep 2: Use the Beacon package in your project The Beacon package exports various utilities you can use in your application. The main one that needs to be setup to enable the connection between Beacon SDK and Roll20 is initRelay.\nIdeally you would want to call this when your sheet is initalizing, and it is the function where you will define sheet actions, computed values, and how the sheet will response to or send character data changes. visit the initRelay page for a more detailed breakdown.\nAdd the following to your project:\nimport { initRelay } from \u0026#39;@roll20/beacon-sdk\u0026#39;; const dispatch = initRelay({ handlers: { onInit: ({ character } ) =\u0026gt; { console.log(\u0026#39;sheet character\u0026#39;, character) }, onChange: () =\u0026gt; {}, onSettingsChange: () =\u0026gt; {}, onSharedSettingsChange: () =\u0026gt; {}, onTranslationsRequest: () =\u0026gt; {}, onDragOver: () =\u0026gt; {} }, // Refer to our advanced example sheet on how to setup actions and computed properties. actions: {}, computed: {} })\rinitRelay returns a dispatch function that allows you to call methods or send changes from the sheet to Roll20. Check out the page on dispatch to learn more about the different methods.\nStep 3: Settings up the Roll20 tabletop sandbox On the Roll20 website visit the custom sheet sandbox and create a new sandbox, we\u0026rsquo;ll use this sandbox to develop our sheet but we must set it up to listen to our local project\u0026rsquo;s web server.\nAfter creating a new sandbox, we\u0026rsquo;ll be taken to the sandbox details page, here you will find a collapseable section called Sheet.json Editor, opening this we can add the settings we need to connect to our project:\n{ \u0026#34;advanced\u0026#34;: true, \u0026#34;advancedPort\u0026#34;: 7620 // or the port of your webserver }\rAfter adding these changes make sure to click Save Changes at the bottom of the page. After which you can click Launch Game on the page to go into the game and start testing your sheet.\n","date":"2024-04-07","id":4,"permalink":"/docs/gettingstarted/installing-beacon/","summary":"This installation guide is designed for sheet developers with experience in web development, that want to start creating a character sheet from scratch or already have an existing project they wish to add Beacon to.","tags":[],"title":"Installing Beacon"},{"content":"Background: The background color of the alert box.\nCharacter: An entity in the game with attributes, bio, GM notes, and a token representation.\nCharacter sheet: A digital or printed page used to track a character\u0026rsquo;s attributes, abilities, and other relevant information in a role-playing game.\nComputed Property: Properties that have both get and set methods, which can be dynamically calculated.\nConvertLegacyMacroAttributes: A function to handle mapping legacy macro attributes to the new Beacon Sheet format.\nDispatch: A set of functions enabling the sheet to send commands back to the VTT.\nGM (Game Master): The person who runs the game, controls the NPCs \u0026amp; the story, and provides challenges for the players.\nHandler: Methods that act as event handlers to process messages from the host.\nInitRelay: Function to initialize the SDK relay, setting up communication between the host and the character sheet.\nMacro: A script that automates repetitive tasks in the VTT.\nRoll Template: A predefined format for displaying the results of a dice roll.\nToken: A visual representation of a character or object on the virtual tabletop, with various properties like position, size, and attributes.\nVTT (Virtual Tabletop): An online platform that allows players to play tabletop role-playing games over the internet.\nValidationMessage: A message displayed when an input value does not meet specific criteria.\nQuantum Roll: A system that ensures the fairness and authenticity of dice rolls in the VTT by using cryptographic methods.\n","date":"2024-03-07","id":5,"permalink":"/docs/about/glossary/","summary":"Background: The background color of the alert box.\nCharacter: An entity in the game with attributes, bio, GM notes, and a token representation.","tags":[],"title":"Glossary"},{"content":"\rQ: How is Beacon better than the old way of building sheets (known as Custom Sheets)?\rIt depends on your web development skill level. There are a number of benefits to the Beacon SDK if you know how to build web applications. If you don\u0026rsquo;t know how to set up your own local environment, than the Beacon SDK might now be the first place you should start. Learn more about sheet development using the custom sheet.\nIf you have the skill to take advantage of the Beacon SDK, there are a number of improvements that will make it much easier to build characters sheets.\nFirst, the Beacon SDK allows you to develop locally and preview your changes automatically in the Roll20 Tabletop and Roll20 Character sandboxes. This means that you don\u0026rsquo;t have to keep uploading your HTML and CSS into the custom sheet to see your changes.\nNext, it allows you to develop your character sheet with all the power of JavaScript frameworks and modern web development libraries. In our example sheets, we use Vue.js, but you are free to use whatever you are most comfortable with. Also, you could use something like Cypress to create automated testing. That\u0026rsquo;s what we use in our Beacon sheets.\nLastly, the Beacon SDK makes it much easier for a web developer who knows JSON and Javascript to access character data and manage attributes on the character. If you\u0026rsquo;re familiar with the custom sheet, you no longer have to deal with sheet workers to get the data you need for a character. Also, the Beacon SDK introduces nested and computed attributes that make complex data models for your character sheet easier to create and maintain.\nQ: I\u0026rsquo;m not really a web developer, should I use Beacon or the custom sheet to make a my own character sheet?\rThat is up to you and your comfort level. If you\u0026rsquo;re looking to learn more about web development, building a character sheet with the Beacon SDK is a great way to level up your skills. What you learn during this process can be taken with you into any other web development project you work on in the future.\nIf setting up your own development environment is too intimidating for you, than it might be easier for you to start with the custom sheet and to go from there.\nQ: I\u0026rsquo;m interested in using Beacon, but I don\u0026rsquo;t know the basics of setting up a local environment. Where can I go to learn more about web development?\rYou can start learning how to build a local development environment by reading or watching the following tutorials. Note: these are not tutorials that we\u0026rsquo;ve produced, but we have found them helpful in getting started with web development.\nhttps://learn.microsoft.com/en-us/windows/dev-environment/javascript/vue-on-wsl https://www.youtube.com/watch?v=WPqXP_kLzpo Q: Now that Roll20 has acquired Demiplane, will you continue to support character sheets built on Beacon?\rThe recent acquisition of Demiplane brings exciting new opportunities for character sheets and compendiums on Roll20. At the same time, we are fully committed to supporting the Beacon SDK and character sheets that are built in our new advanced sheets ecosystem on Roll20. In fact, we believe that the Beacon SDK will be a key component of our future plans for Demiplane integration. In addition, our new D\u0026amp;D 2024 sheet is built on top of the Beacon SDK, and we will continue to utilize it to build first-class experiences on Roll20.\nIn short, you can rest assured that the Beacon SDK is an important tool in our toolbox moving forward.\nQ: What are actions in the context of Beacon?\rActions are methods executed in the chat log of Roll20 Tabletop or Roll20 Characters, often used for rolls triggered from macros or chat buttons. They are defined in the sheet\u0026rsquo;s configuration and can interact with character data. Q: How are computed properties used in Roll20?\rComputed properties are attributes which are accessible by users of your character sheet. They are usable in macros to create custom rolls or common actions for each character. Computed properties can represent derived values or complex calculations based on character data. Q: What is the dispatch function used for?\rThe dispatch function provides methods for sending commands from the character sheet back to Roll20, including updating character data, performing actions, and interacting with the interface. Q: What are roll buttons, and how do they work?\rRoll buttons are HTML elements with specific attributes that execute designated sheet actions when clicked. They can pass arguments to the action method and are commonly used for triggering rolls from the character sheet. Q: How are legacy attributes handled in Beacon?\rBeacon gives you the ability to transition your legacy attributes to new attributes you create in Beacon. This means that when a user updates their sheet to the new Beacon sheet, their legacy attribute can be mapped to Beacon attributes using the convertLegacyMacroAttributes function. Sheet developers can define how to handle legacy attribute values to ensure compatibility with existing macros. Q: What is the purpose of the query function?\rThe query function displays a SweetAlert2 prompt to users and returns the results along with any errors. It is commonly used for interactive prompts or confirmations within the VTT interface. Q: How are tokens managed in the VTT?\rTokens represent characters or objects on Roll20 Tabletop (VTT). Functions like getTokens, updateTokensByCharacter, and addToTracker are used to retrieve token information, update token data, and manage tokens in the turn tracker. Q: What is the role of the convertLegacyMacroAttributesArgs type?\rThe convertLegacyMacroAttributesArgs type defines the arguments used for handling legacy macro attributes. It includes the attribute name, character ID, and character data needed for mapping legacy attributes to the new sheet structure. ","date":"2024-01-07","id":6,"permalink":"/docs/about/faq/","summary":"Q: How is Beacon better than the old way of building sheets (known as Custom Sheets)?\rIt depends on your web development skill level.","tags":[],"title":"FAQ"},{"content":"The Beacon SDK is composed of various methods and components that allow developers to create dynamic and interactive character sheets for virtual tabletop (VTT) games. initRelay is the main method that initializes the Beacon SDK communication channel with the host (Either the Roll20 tabletop or in Roll20 Characters). It should be initialized as soon as the sheet loads, as its onInit handler will be the earliest we can get access to that character\u0026rsquo;s data.\ninitRelay({ handlers: { onInit, onChange, onSettingsChange, onSharedSettingsChange, onTranslationsRequest, onDragOver, onDropOver, }, actions: {}, computed: {}, convertLegacyMacroAttributes, handleLegacyRollTemplates }): Promise\u0026lt;Dispatch\u0026gt;\rThese components are crucial for handling actions, computations, macros, and rolls. This overview provides a high-level summary of each section, helping you understand their roles and how they integrate within the SDK.\nActions\rActions define specific operations that can be performed by characters within the VTT. These operations can range from simple tasks like rolling a dice to more complex interactions such as casting spells or activating abilities.\nHandlers\rHandlers are event listeners that manage communication between the VTT and the character sheet. They respond to various events, such as changes in character attributes or settings, and trigger appropriate actions or updates.\nComputed\rComputed properties are dynamic values derived from other character attributes. They allow for the creation of complex, calculated attributes that automatically update when their dependencies change.\nMacro Attributes\rMacro attributes handle the conversion of legacy macro attributes to the new format used in the Beacon SDK. This ensures compatibility with older character sheets and macros, allowing for a smooth transition to the new system.\nRolls\rThe Rolls component allows for advanced dice-rolling mechanics within the VTT. It supports both simple and complex rolls, providing flexibility in how roll results are displayed and computed.\nDispatch\rThe dispatch object provides methods for sending commands from the character sheet back to the host. Except when specified every method returns a promise.\n","date":"2024-06-07","id":7,"permalink":"/docs/components/initrelay/","summary":"The Beacon SDK is composed of various methods and components that allow developers to create dynamic and interactive character sheets for virtual tabletop (VTT) games.","tags":[],"title":"InitRelay"},{"content":"Actions are a collection of methods that can be executed from the VTT. These actions are used for any rolls that may need to be triggered outside of the sheet itself, such as from a macro or a chat button. Generally, most or all of a sheet’s rolls should be defined as actions.\nactions: { [name: string]: { method: (props: { dispatch: Dispatch, character: Character, messageId?: string, rolls?: RollResults }, ...args: string[]): void | Promise\u0026lt;void\u0026gt; } }\rActions are passed into the initRelay function in an object, where the keys are the unique names of the actions, and the values are objects containing a method property (additional metadata fields may be added to this object in the future).\nThe method receives a props object containing the following properties:\ndispatch: A Dispatch object. character: The data of the character performing the action. Currently, the action will not receive the character’s bio or GM notes, regardless of whether the player has access to those fields. messageId (optional): A unique ID for an existing chat message. It\u0026rsquo;s included in actions triggered from chat buttons to provide context for the original roll. rolls (optional): Included when action is triggered from a chat button. Contains the roll results of the original roll. These functions can also receive an unlimited number of additional arguments. This is because these actions can be triggered by plain text via a macro. However, all additional arguments must be strings. Additionally, these functions can be synchronous or asynchronous and do not return a value.\n","date":"2024-05-07","id":8,"permalink":"/docs/components/actions/","summary":"Actions are a collection of methods that can be executed from the VTT. These actions are used for any rolls that may need to be triggered outside of the sheet itself, such as from a macro or a chat button.","tags":[],"title":"Actions"},{"content":"","date":"2024-04-07","id":9,"permalink":"/docs/components/","summary":"","tags":[],"title":"Components"},{"content":"Sheet authors define computed properties that are accessed by the host. These computed properties can be used as attributes in macros and are available to assign as values to token bars - if the tokenBarValue property is set to true.\ncomputed: { [name: string]: { tokenBarValue?: boolean, description?: string, get: ( props: { character: Character }, ...args: string[] ) =\u0026gt; ComputedResult, set?: ( props: { character: Character, dispatch: Dispatch }, ...args: string[] ) =\u0026gt; void | Promise\u0026lt;void\u0026gt; } }\rComputed properties are passed into the initRelay function in an object where the keys are the names of the properties, and the value should be an object containing the following:\nget (required): It receives character data along with any number of string parameters and should return the computed value. tokenBarValue (optional): A boolean indicating whether this property should be available for use in token bars. description (optional): A text value indicating what this computed summary property represents. set (optional): This method receives character data and a dispatch, along with string arguments. This method does not need to return a value. Setting tokenBarValue to true will make the property available to use as a value for token bars. To work correctly, the get function must not rely on any additional arguments and must return either a simple value (a string or number) or an object: { current: number | string, max: number | string }\rIf the set function is omitted, the value will not be editable from the token itself. If defined, set methods will receive one string argument, which is whatever the user types into the input for modifying the bar. ","date":"2024-04-07","id":10,"permalink":"/docs/components/computed/","summary":"Sheet authors define computed properties that are accessed by the host. These computed properties can be used as attributes in macros and are available to assign as values to token bars - if the tokenBarValue property is set to true.","tags":[],"title":"Computed"},{"content":"Handler functions allow the sheet to respond to messages from the host. The handlers argument requires the following methods:\nonInit The onInit function provides the initial set of data to the sheet.\nonInit(e: { character: Character, settings: { colorTheme: string, language: string, gm: boolean, owned: boolean, settingsSheet: boolean, headless: boolean, sandbox: boolean, campaignId: number, environment: string, currentUserId: string, singleSheet: boolean }, sharedSettings: {}, compendiumDropData: { pageName: string, categoryName: string, expansion: number } }, dispatch: Dispatch): void;\rThe event object contains the following:\ncharacter: The primary character for this sheet. settings: Campaign and character-specific settings. sharedSettings: Data shared between all characters in this campaign. compendiumDropData: Populated when the character sheet is created from a compendium entry such as a creature or NPC. This function may be called multiple times during development in the sheet sandbox as part of hot reloads.\nonChange onChange is called whenever a character’s data is changed on the host’s end. The event object contains a partial character with only the character’s ID and the changed data. This could be the character’s bio, GM notes, or attributes (only the changed attributes).\nonChange(e: { character: Partial\u0026lt;Character\u0026gt; }, dispatch: Dispatch): void;\ronSettingsChange onSettingsChange is called when either the VTT’s color theme is changed, or when the current player’s ownership of the primary character changes.\nonSettingsChange(e: { colorTheme: string, owned: boolean }, dispatch: Dispatch): void;\ronSharedSettingsChange onSharedSettingsChange is called when someone changes a shared setting in the VTT.\nonSharedSettingsChange({ settings: { [key: string]: any } }): void;\ronTranslationsRequest onTranslationsRequest is called before the relay is fully initialized and returns the translation JSON data corresponding to the two-letter language argument.\nonTranslationsRequest(language: string): { [key: string]: string };\ronDragOver (optional) onDragOver is called when a compendium item from the compendium tab is dragged over the iframe window containing the character sheet.\nCoordinates of the drag are provided via top and left values, and basic compendium data is passed so that a subsequent compendium request can be made via the provided dispatch. If the item is moved outside of the iframe, dragData and coordinates are null.\nonDragOver(e: { coordinates: { top: number, left: number }, dragData: { pageName: string, categoryName: string, expansionId: number } | null }, dispatch: Dispatch): void\ronDropOver (optional) onDropOver is called when a compendium item from the compendium tab is dropped over the iframe window containing the character sheet.\nCoordinates of the drop are provided via top and left values, and basic compendium data is passed so that a subsequent compendium request can be made via the provided dispatch.\nonDropOver(e: { coordinates: { top: number, left: number }, dropData: { pageName: string, categoryName: string, expansionId: number } }, dispatch: Dispatch): void\r","date":"2024-03-07","id":11,"permalink":"/docs/components/handlers/","summary":"Handler functions allow the sheet to respond to messages from the host. The handlers argument requires the following methods:\nonInit The onInit function provides the initial set of data to the sheet.","tags":[],"title":"Handlers"},{"content":"","date":"2024-02-07","id":12,"permalink":"/docs/about/","summary":"","tags":[],"title":"About"},{"content":"When utilizing Macros within the VTT, there are instances where a legacy macro might need to be employed for a Beacon sheet.\nThis scenario commonly arises when transitioning from an existing legacy sheet to a Beacon sheet. During such transitions, it\u0026rsquo;s possible that the attributes called from the legacy macro may not align with the structure of attributes in the Beacon Sheet.\nThe convertLegacyMacroAttributes function serves as a pivotal tool, empowering Sheet Developers to determine the mapping strategy for legacy attributes to the new Beacon Sheet.\nconvertLegacyMacroAttributes This function is defined during the initial SDK initialization process and is invoked by the host when it encounters a failure in locating an attribute\u0026rsquo;s value.\nconvertLegacyMacroAttributes: (messages: convertLegacyMacroAttributesArgs) =\u0026gt; {}: any\rAdvanced sheet macros typically first search through the defined computed properties before resorting to the convertLegacyMacroAttributes function.\nThe function\u0026rsquo;s purpose is to return a value that will be substituted in the macro. However, it grants Sheet Developers the autonomy to devise their preferred approach for handling legacy attribute values.\n","date":"2024-02-07","id":13,"permalink":"/docs/components/handling-legacy-macro-attributes/","summary":"When utilizing Macros within the VTT, there are instances where a legacy macro might need to be employed for a Beacon sheet.","tags":[],"title":"Handling Legacy Macro Attributes"},{"content":"Release Date: 2022-03-17\nNew Features Initial release of the Beacon SDK. Support for Vue.js framework. Setup with Vite for rapid development. Basic and advanced sheet examples. Improvements Detailed comments added to example files for better understanding. Support for complex roll templates and rich sheet actions. Bug Fixes N/A (initial release). Version 2.0.0 Release Date: 2023-03-17\nNew Features SCSS support for styling. Integration with Roll20 and VTT. Mock Relay for offline development. Improvements TypeScript integration for type checking and improved development experience. Unit testing with Vitest. End-to-End testing with Cypress. Bug Fixes N/A (initial release). ","date":"2024-01-07","id":14,"permalink":"/docs/about/changelog/","summary":"Release Date: 2022-03-17\nNew Features Initial release of the Beacon SDK. Support for Vue.js framework. Setup with Vite for rapid development.","tags":[],"title":"Changelog"},{"content":"The Roll20 Tabletop and Roll20 Characters (both refered to as host throughout the rest of this page) have several new features that enhance the way rolls are handled and displayed. These features include attributes and elements that allow for dynamic roll results and interactivity within the host. Vist the Roll20 help center to learn more about Roll20\u0026rsquo;s Dice Rolling system\nThe most command way to trigger a dice roll is through the dispatch object returned from the initRelay, but it could also be called from actions:\ndispatch.roll({ rolls: { [rollName: string]: string } // Ex. {attack: \u0026#39;1d20+4\u0026#39;, damage: `3d6+2`} messageId?: string }): Promise\u0026lt;{messageId: string, results: RollResults }\u0026gt;\rThe roll method takes one or more rolls in the form of an object, where the keys are unique roll names and the values are roll strings.\nmessageId can be provided to attach the roll to an existing chat message, either overriding it or appending to it in the chat log. If messageId is omitted, the roll will be associated with a new chat message and a new messageId for that message will be returned with the roll results. The method returns a promise that resolves with an object containing the messageId and the RollResults. The roll result is returned in the same format as in the non-beacon dice rolls computed roll system.\nThe dispatch roll method and the actions roll section do not post to the chat, instead they will return a promise which will resolve to the roll results and the message id.\nPosting A Roll to the Chat The roll method does not send or post any data to the chat on it\u0026rsquo;s own. We instead have to use dispatch\u0026rsquo;s post method to send our roll results along with any other content to the chat.\ndispatch.post({ characterId: \u0026#39;-O0KZhMTxLkn2HArFj8f\u0026#39;, content: `I rolled a ${diceRoll.results.attack.results.result} to hit and did ${diceRoll.results.damage.results.result} damage!`, })\rAdditional Roll Posting Options data-rollname The data-rollname attribute tells the host that this HTML element is displaying the result of a roll.\n\u0026lt;span data-rollname=\u0026#34;attack\u0026#34;\u0026gt;\u0026lt;/span\u0026gt;\rThe host will both add the Quantum Roll signature element and replace the contents of the element with the result from the roll.\nThis is the preferred method for displaying roll results wherever possible, that is, sending the whole roll formula to the roll server and allowing the host to display the result.\ndata-computed Tagging an element with both a data-rollname and a data-computed=\u0026quot;true\u0026quot; tells the host that this element is associated with a roll, but the results of that roll were computed by the author, as opposed to the roll server computing the result.\n\u0026lt;span data-rollname=\u0026#34;complex\u0026#34; data-computed=\u0026#34;true\u0026#34;\u0026gt;25\u0026lt;/span\u0026gt;\rThe host will add the Quantum Roll signature tooltip, but the content of the element will not be modified. Generally, this should only be used when the roll server does not support a particular dice mechanic.\nRoll Buttons Roll buttons are interactive elements that trigger sheet actions, such as damage rolls, when clicked. These buttons use the data-sheet-action attribute to specify the action to be executed.\n\u0026lt;button data-sheet-action=\u0026#34;damage\u0026#34; data-args=\u0026#34;arg1:arg2\u0026#34;\u0026gt;Click Me\u0026lt;/button\u0026gt;\rAdditional arguments can be provided using the data-args attribute, and the character, messageId, and original rolls will be included automatically.\nRolls Results Format type RollResults = { [name: string]: { expression: string //The original expression (i.e. 1d20+3d6) rollName: string //The name of the roll results: { //The results of the roll(s) expression: string dice?: number[] // result: number //The final result of the roll rolls?: { //Detailed results of each part of the roll (i.e. 3d6) sides: number //The type of die for this part of the roll (i.e. 6) dice: number //The number of dice (i.e. 3) results: number[] //The result of each die (i.e. [4, 2, 5]) }[] } } }\r","date":"2024-01-07","id":15,"permalink":"/docs/components/rolls/","summary":"The Roll20 Tabletop and Roll20 Characters (both refered to as host throughout the rest of this page) have several new features that enhance the way rolls are handled and displayed.","tags":[],"title":"Rolls"},{"content":"The dispatch is returned by the initRelay and provides methods for sending commands from the character sheet back to the host. Except when specified every method below will return a promise.\nupdate dispatch.update({ options: { overwrite?: boolean } character: Partial\u0026lt;Character\u0026gt; }): Promise\u0026lt;void\u0026gt;\rThe update method sends character changes to the host (Roll20 Tabletop or Roll20 Characters) to be persisted. The partial character passed in here must contain the character\u0026rsquo;s id, and can contain any combination of the attributes, bio, and gmNotes properties. When updating a character’s attributes, only include those attributes that have changed.\nupdateCharacter dispatch.updateCharacter({ character: Partial\u0026lt;Character\u0026gt; }): Promise\u0026lt;void\u0026gt;\rLike the update method, updateCharacter sends character changes to the host page (Roll20 Tabletop or Roll20 Characters) to be persisted. However, this method takes a full set of character attributes as the character argument, and automatically computes the diff with existing character attributes, so that only changed attributes are sent to the data store.\nroll dispatch.roll({ rolls: { [rollName: string]: string } // Ex. {attack: \u0026#39;1d20+4\u0026#39;, damage: `3d6+2`} messageId?: string }): Promise\u0026lt;{messageId: string, results: RollResults }\u0026gt;\rThe roll method takes one or more rolls in the form of an object, where the keys are unique roll names and the values are roll strings. messageId can be provided to attach the roll to an existing chat message, either overriding it or appending to it in the chat log. If messageId is omitted, the roll will be associated with a new chat message and a new messageId for that message will be returned with the roll results. The method returns a promise that resolves with an object containing the messageId and the RollResult (see Types). The roll result is returned in the same format as in the non-beacon dice rolls computed roll system.\npost dispatch.post({ characterId: string, messageId?: string, content: string, options?: { whisper?: \u0026#39;gm\u0026#39;, secret?: boolean, } }): Promise\u0026lt;string\u0026gt;\rpost posts a message to chat, either creating a new message or overwriting an existing one. It requires a character id and message content, a string containing either plain text or HTML to be posted. The method also accepts an options object. Currently, only whisper and secret are supported, the only valid value for whisper is gm, which will send the message as a whisper to the gm. The secret option is ignored unless whisper is also set, toggling to true will cause the message to not be visible to the controlling player. Like roll, messageId can be provided to update an existing chat message, but if omitted the method will generate a new messageId and post a new chat message. The method returns the messageId.\nquery dispatch.query(options: Swal2Options): { isConfirmed: boolean, isDenied: boolean, isDismissed: boolean, value?: string | number, dismiss?: \u0026#34;cancel\u0026#34; | \u0026#34;backdrop\u0026#34; | \u0026#34;close\u0026#34; | \u0026#34;esc\u0026#34; | \u0026#34;timer\u0026#34;, errors?: string[], }: Promise\u0026lt;{ results: { isConfirmed: boolean isDenied: boolean isDismissed: boolean value: string | number dismiss: string }, errors: [string] }\u0026gt;\rThe query method takes an options object and uses them to display a SweetAlert2 prompt to the user. It returns the results of the query as a SweetAlertResult, along with any errors encountered. The options work exactly as described in the documentation for SweetAlert2, however not all options are allowed. Here is a list of the allowed options:\ntitleText, text, iconColor, input, width, padding, background, position, grow, timer, timerProgressBar, showConfirmButton, showDenyButton, showCancelButton, ariaLabel, confirmButtonText, denyButtonText, cancelButtonText, confirmButtonAriaLabel, confirmButtonColor, cancelButtonAriaLabel, cancelButtonColor, denyButtonAriaLabel, denyButtonColor, reverseButtons, showCloseButton, closeButtonAriaLabel, returnInputValueOnDeny, imageUrl, imageWidth, imageHeight, imageAlt, inputLabel, inputPlaceholder, inputValue, inputOptions, inputPlaceholder, inputAutoTrim, inputAttributes, validationMessage, progressSteps, currentProgressStep, progressStepsDistance.\nPerform dispatch.perform({ characterId: string, action: string, args: string[], }): Promise\u0026lt;void\u0026gt;;\rperform executes the specified action on behalf of the character (designated by the character id), passing in args to the action method. This method can perform actions on behalf of any character, even a character that the sheet does not have data for.\ngetComputed dispatch.getComputed({ characterId: string, property: string, args: string[] }): Promise\u0026lt;string | number | object\u0026gt;\rsee setComputed below\nsetComputed dispatch.setComputed({ characterId: string, property: string, args: string[] }): Promise\u0026lt;string | number | object\u0026gt;\rgetComputed and setComputed are both nearly identical in how they are called, taking a character id and a property with the name of the computed property you wish to get or set, and an array of string args. Both methods return a promise that resolves with the computed value.\ncompendiumRequest dispatch.compendiumRequest({ query: string }): Promise\u0026lt;{ data: Object errors: Array\u0026lt;Error\u0026gt; extensions: Record\u0026lt;string, any\u0026gt; }\u0026gt;\rcompendiumRequest executes an AJAX request to the compendium service’s graphQL endpoint. It takes in a graphQL query string written according to the Compendium service’s schema. The query string does not need to include the ruleSystem shortName as this is set automatically according to the campaign override or sheet.json value in the Roll20 Tabletop.\ndebouncedCompendiumRequest dispatch.debouncedCompendiumRequest({ query: string }): Promise\u0026lt;{ data: Object }\u0026gt;\rLike compendiumRequest, except that calls to this method are automatically debounced (at 100ms) and grouped together into a single request to the compendium service. Note that this method will only return the requested data, it does not return errors or extensions.\ngetTokens dispatch.getTokens({ characterId: string }): Promise\u0026lt;{ selected: Token[], tokens: Token[] }\u0026gt;: Promise\u0026lt;{ selected: Token[] tokens: Token[] }\u0026gt;\rgetTokens requires a character id string and returns information about tokens on the user’s current page. The return value contains two arrays of tokens. The tokens array contains all tokens on the current page that represent the character whose id was provided to the method. The selected array contains any tokens that are currently selected, regardless of which character they represent. The returned token objects contain all of the token attributes available to the API, you can find documentation here and here.\naddToTracker dispatch.addToTracker({ tokenId?: string, custom?: { name: string img?: string } formula?: string value: string | number }): Promise\u0026lt;void\u0026gt;\raddToTracker adds or updates a single item in the turn tracker. Passing in a tokenId will add the specified token to the tracker, while passing in custom with a name and an optional image url (img) will add a custom item, not connected to any character or token. A round calculation string can be added via the optional formula parameter. value is the initiative number for the item.\naddActionsToHost dispatch.addActionsToHost({ sheetAction?: { characterId: string action: string args?: string[] } action?: string locations?: [\u0026#39;macroBar\u0026#39;] | [\u0026#39;tokenActionBar\u0026#39;] | [\u0026#39;macroBar\u0026#39;, \u0026#39;tokenActionBar\u0026#39;] actionId?: string name: string requestId?: string }): void\raddActionsToHost adds a specific action(macro) to an area of the Roll20 Tabletop UI; either the macrobar or the token action bar. Either sheetAction or action can be passed in but not both at the same time. The sheetAction arg should be passed in when an the action is to designated to a character. While the action arg should be passed in when the action is more generic.\ngetActions dispatch.getActions({ args: { characterId?: string } }): Promise\u0026lt;{ actions?: {} | { [id: string]: ActionFromHost } }\u0026gt;\rgetActions gets a specific character’s actions(macro).\nsetContainerSize dispatch.setContainerSize({ args: { width?: number height?: number } }): Promise\u0026lt;void\u0026gt;\rsetContainerSize updates the size of the container which holds the sheet shared settings. Returns a promise that can be awaited. This can be used in conjunction with something like the ResizeSensor event listener from npm: css-element-queries to automatically resize the container on the host.\nupdateTokensByCharacter dispatch.updateTokensByCharacter({ args: { characterId: string token: Partial\u0026lt;Token\u0026gt; } }): Promise\u0026lt;void\u0026gt;\rupdateTokensByCharacter updates a particular character’s default token as well as all existing tokens representing that character. Returns a promise that can be awaited.\nupdateTokensByIds dispatch.updateTokensByIds({ args: { tokenIds: array of ids as strings token: Partial\u0026lt;Token\u0026gt; } }): Promise\u0026lt;void\u0026gt;\rupdateTokensByIds updates a single or several tokens. Returns a promise that can be awaited.\nautoLinkText dispatch.autoLinkText({ args: { text: string } }): Promise\u0026lt;string\u0026gt;\rautoLinkText goes through the text to find handout names between square brackets and converts them into links with the handoutID. For example in a game with a handout named Dragon, passing in the text string of this is a [Dragon] to autoLinkText returns something similar to this is a \u0026lt;a href=\u0026quot;https://journal.roll20.net/8je02j0kd02k\u0026quot;\u0026gt;Dragon\u0026lt;/a\u0026gt;.\nopenDialogFromLink dispatch.openDialogFromLink({ args: { urlString: string } }): void\ropenDialogFromLink opens the supplied urlString through the Roll20 Tabletop.\nIf the url is for a handout, it will open the corresponding handout in the campaign. This will also check if the user opening the link has access to the handout. If the url is for a compendium, it will open a pop up to the compendium page, it will also check to ensure the user has access to view the page. If the url is for an external page, a confirmation pop up will display to warn the user that the link is for an external site and open a new tab in their main window if confirmed. ","date":"2023-09-07","id":16,"permalink":"/docs/components/dispatch/","summary":"The dispatch is returned by the initRelay and provides methods for sending commands from the character sheet back to the host.","tags":[],"title":"Dispatch"},{"content":"Prerequisites To set this sheet up properly, make sure that you have the following tools installed:\nVue.js Vite SCSS Figure 1: Quickstart sheet\nUse the following steps to get started:\nInstall the Beacon SDK: Run the following command. npm i @roll20-official/beacon-sdk\rInstall dependencies: Install the dependencies for the project. npm install\rStart the Vite server: After installing the project\u0026rsquo;s dependencies, you\u0026rsquo;ll need to start the Vite server. There are two ways to do this: a. Offline Development: This method will run the Vite server with the default port and environment set to development.\nnpm run dev\rOnce this code executes successfully, you can access the Vite server at http://localhost:5173.\nThis method is useful when you do not have access to the Roll20 website or would like to work on parts of your project that do not depend on a connection to the VTT or Roll20 Characters, such as working on styling, mocking up the environment, building Vue components, testing functionality, etc.\nIn development mode, you cannot save or access existing character data or use the Beacon SDK functions that depend on VTT or Roll20 Characters functionality, such as dice rolling and token manipulation.\nb. Sandbox Development: This method will run the Vite server with the port set to 7620 and the environment set to staging mode.\nnpm run sandbox\rThis command will build the SCSS files and then run the Vite server. This will set the server up for connecting to a VTT custom sheet sandbox as well as through the sandbox in Roll20 Characters.\nTo test your changes in the VTT custom sheet sandbox, you will need to add the following to the sheet.json editor in the game settings:\n{ \u0026#34;advanced\u0026#34;: true, \u0026#34;advancedPort\u0026#34;: 7620 }\rUseful Commands The following set of commands can come in handy when working with this sheet:\nFor Hot reloading and building CSS files, use the following command: npm run watch-scss\rFor linting, use the following command: npm run lint\rFor formatting with Prettier, use the following command: npm run format\r","date":"2024-04-07","id":17,"permalink":"/docs/gettingstarted/quick-start-sheet-template/","summary":"Prerequisites To set this sheet up properly, make sure that you have the following tools installed:\nVue.js Vite SCSS Figure 1: Quickstart sheet","tags":[],"title":"Quick Start Sheet Template"},{"content":"Prerequisites To set this sheet up properly, make sure that you have the following:\nVue framework \u0026amp; Routing Multiple Data Stores Complex Roll Templates Rich Sheet Actions TypeScript Vite SCSS Ability to run Unit \u0026amp; End-to-End Tests Figure 1: Advanced sheet\nThis sheet uses the same steps listed in the . Immediately after implementing those three steps, you\u0026rsquo;ll add the following step:\nRun a CI check: This will run several checks to ensure your code is as optimal as possible, including formatting, linting, type checking, unit tests, and end-to-end tests. npm run ci-check\rYou can think of this command as a sanity check you can leverage when pushing a big release for your sheet!\nUseful Commands The following set of commands can come in handy when working with this sheet:\nFor Hot reloading and building CSS files, use the following command: npm run watch-scss\rFor linting, use the following command: npm run lint\rFor formatting with Prettier, use the following command: npm run format\rFor type checking with TypeScript, use the following command: npm run type-check\rFor running unit tests with Vitest, use the following command: npm run test:unit\rTo open up and develop local end-to-end tests with Cypress, use the following command: npm run test:e2e:open:local\rFor running local end-to-end tests with Cypress, use the following command: npm run test:e2e:local\rTo run CDN-hosted end-to-end tests with Cypress, use the following command: npm run test:e2e\r","date":"2024-03-07","id":18,"permalink":"/docs/gettingstarted/example-patterns-sheet/","summary":"Prerequisites To set this sheet up properly, make sure that you have the following:\nVue framework \u0026amp; Routing Multiple Data Stores Complex Roll Templates Rich Sheet Actions TypeScript Vite SCSS Ability to run Unit \u0026amp; End-to-End Tests Figure 1: Advanced sheet","tags":[],"title":"Example Patterns Sheet"},{"content":"We appreciate your interest in contributing to the Beacon SDK project. Here are some guidelines to help you get started:\nHow to Contribute Reporting Bugs If you find a bug, please report it by opening an issue in the GitHub repository. Provide as much detail as possible to help us understand and reproduce the issue.\nSuggesting Features We welcome suggestions for new features. Please open an issue in the GitHub repository with a detailed description of the feature you would like to see and why you think it would be useful.\nCode Contributions Fork the Repository: Create a personal fork of the project on GitHub.\nClone the Fork: Clone your fork to your local machine.\ngit clone Create a Branch: Create a new branch for your work.\ngit checkout -b feature-or-bugfix-description\rMake Changes: Make your changes to the codebase. Follow the existing code style and conventions.\nRun Tests: Ensure that all tests pass before submitting your changes.\nnpm run ci-check\rCommit Changes: Commit your changes with a descriptive commit message.\ngit commit -m \u0026#34;Description of your changes\u0026#34;\rPush Changes: Push your changes to your fork.\ngit push origin feature-or-bugfix-description\rCreate a Pull Request: Open a pull request from your fork to the main repository. Provide a detailed description of your changes and why they should be merged.\nRunning Tests Unit Tests: Run unit tests with Vitest.\nnpm run test:unit\rEnd-to-End Tests: Run End-to-End tests with Cypress.\nnpm run test:e2e\rCode Style Follow the existing code style and conventions.\nUse ESLint for linting.\nnpm run lint\rFormat code with Prettier.\nnpm run format\rCommunication GitHub Issues: Use GitHub issues for bug reports, feature requests, and questions. Pull Requests: Use GitHub pull requests to submit your code contributions. Thank you for contributing to the Beacon SDK project!\n","date":"2024-02-07","id":19,"permalink":"/docs/about/how-to-contribute/","summary":"We appreciate your interest in contributing to the Beacon SDK project. Here are some guidelines to help you get started:","tags":[],"title":"How to Contribute"},{"content":"A release sheet is a finalized version of a character sheet or other content designed for use on the Roll20 platform. This sheet includes all the necessary code, assets, and metadata packaged together to be easily shared, tested, and eventually deployed on Roll20.\nWhen you\u0026rsquo;re ready to test and share a sheet on Roll20, you\u0026rsquo;d want to do it in such a way that others who might need it won\u0026rsquo;t have to set it up with a local dev environment.\nThat\u0026rsquo;s what the steps below help you achieve. In this guide, you can make your sheet available in the Roll20 Tabletop and Characters.\nSteps to Release a Test Sheet The following steps will aid you while releasing your sheet:\nCreate a Build Command:\nYou must have a build command that will produce the minified production-ready code. You can find an example in our Quickstart Package JSON. The build command must be able to create these exact files:\nsheet.js sheet.css host.css (optional) Add a local folder that contains fonts and images used in the sheet (optional). Add a sheet.json file:\nAdd a sheet.json file to your sheet folder to ensure the metadata for your sheet is up-to-date. For this, you can also find an example in our Quickstart Package JSON.\nCreate a Pull Request in the Community Sheet Repo:\nIn the Community Sheet Repo, create a pull request that must include the submission checklist from our previous process.\nSubmission Checklist When submitting a new or updated sheet to Roll20, it\u0026rsquo;s essential to follow the guidelines to ensure a smooth review and approval process.\nBelow is a checklist to help you prepare your submission.\nRequired The following are the required submission checklist items:\nThe pull request title clearly contains the name of the sheet I am editing. The pull request title clearly states the type of change I am submitting (New Sheet/New Feature/Bugfix/etc.). The pull request makes changes to files in only one sub-folder. The pull request does not contain changes to any JSON files in the translations folder (translation.json is permitted). New Sheet Details You must include the following information in your sheet:\nThe name of this game is: \u0026lt; THE AETHYRBLOOD CHRONICLES \u0026gt;. The publisher of this game is: \u0026lt; HAPHAZARD PROJECTS \u0026gt; The name of this game system/family is: \u0026lt; DPS System ('dice pool scales') \u0026gt; You must also check out the following:\nI have followed the Character Sheets Standards when building this sheet. I have authorization from the game\u0026rsquo;s publisher to make this an official sheet on Roll20 with their name attached. This game is not traditionally published, but a copy of the game rules can be purchased/downloaded/found at The Aethyrblood Chronicles Core Rule Book In the pull request comments, make sure to list the email addresses of the Roll20 users you\u0026rsquo;d like to have access to the sheet.\nWe can always grant more people access to the sheet after it is released. However, you can inform us in our Official Community Sheet Development Channels on Discord.\nApproval and Access:\nAfter you create a pull request, our team will approve it and add your sheet to the sheet selection in Roll20 Tabletop and Characters. We will then give only your Roll20 user and any others you\u0026rsquo;ve listed in the pull request comments access to the sheet in Roll20. This sheet will then be available for you and others with access to test it.\nReleasing a Final Version After you have released a test version of your sheet, you can follow the same steps as releasing a test version to make your sheet available to everyone. This time, the pull request comments state that it is a final release version.\nOnce you have created the pull request, our team will review the sheet functionality, code, and metadata for consistency, best practices, and overall system security. We reserve the right to reject any sheet that does not meet our terms of use or conflicts with our partnerships.\n","date":"2024-02-07","id":20,"permalink":"/docs/gettingstarted/releasing-a-sheet/","summary":"A release sheet is a finalized version of a character sheet or other content designed for use on the Roll20 platform.","tags":[],"title":"Releasing a Sheet"},{"content":"Link to valuable, relevant resources.\n","date":"2024-02-27","id":21,"permalink":"/docs/resources/","summary":"Link to valuable, relevant resources.","tags":[],"title":"Resources"},{"content":"","date":"2023-09-07","id":22,"permalink":"/docs/","summary":"","tags":[],"title":"Docs"},{"content":"","date":"2023-09-07","id":23,"permalink":"/privacy/","summary":"","tags":[],"title":"Privacy Policy"},{"content":"","date":"2023-09-07","id":24,"permalink":"/","summary":"","tags":[],"title":"Welcome to Beacon SDK"},{"content":"","date":"0001-01-01","id":25,"permalink":"/categories/","summary":"","tags":[],"title":"Categories"},{"content":"","date":"0001-01-01","id":26,"permalink":"/contributors/","summary":"","tags":[],"title":"Contributors"},{"content":"","date":"0001-01-01","id":27,"permalink":"/tags/","summary":"","tags":[],"title":"Tags"}] \ No newline at end of file