Feature A
Lorem ipsum dolor sit amet, consectetur adipiscing elit
diff --git a/.vitepress/dist/404.html b/.vitepress/dist/404.html new file mode 100644 index 0000000..388c5fb --- /dev/null +++ b/.vitepress/dist/404.html @@ -0,0 +1,21 @@ + + +
+ + +Repository for public documentation of Beacon SDK.
npm install
The docs:dev script will start a local dev server with instant hot updates. Run it with the following command:
npm run docs:dev
Release Date: 2022-03-17
Release Date: 2023-03-17
Release Date: 2022-03-17
Release Date: 2023-03-17
=0)c=r.activeElement;else{var f=i.tabbableGroups[0],p=f&&f.firstTabbableNode;c=p||h("fallbackFocus")}if(!c)throw new Error("Your focus-trap needs to have at least one focusable element");return c},v=function(){if(i.containerGroups=i.containers.map(function(c){var f=br(c,a.tabbableOptions),p=wr(c,a.tabbableOptions),C=f.length>0?f[0]:void 0,I=f.length>0?f[f.length-1]:void 0,M=p.find(function(m){return le(m)}),P=p.slice().reverse().find(function(m){return le(m)}),z=!!f.find(function(m){return se(m)>0});return{container:c,tabbableNodes:f,focusableNodes:p,posTabIndexesFound:z,firstTabbableNode:C,lastTabbableNode:I,firstDomTabbableNode:M,lastDomTabbableNode:P,nextTabbableNode:function(x){var $=arguments.length>1&&arguments[1]!==void 0?arguments[1]:!0,K=f.indexOf(x);return K<0?$?p.slice(p.indexOf(x)+1).find(function(Q){return le(Q)}):p.slice(0,p.indexOf(x)).reverse().find(function(Q){return le(Q)}):f[K+($?1:-1)]}}}),i.tabbableGroups=i.containerGroups.filter(function(c){return c.tabbableNodes.length>0}),i.tabbableGroups.length<=0&&!h("fallbackFocus"))throw new Error("Your focus-trap must have at least one container with at least one tabbable node in it at all times");if(i.containerGroups.find(function(c){return c.posTabIndexesFound})&&i.containerGroups.length>1)throw new Error("At least one node with a positive tabindex was found in one of your focus-trap's multiple containers. Positive tabindexes are only supported in single-container focus-traps.")},y=function w(c){var f=c.activeElement;if(f)return f.shadowRoot&&f.shadowRoot.activeElement!==null?w(f.shadowRoot):f},b=function w(c){if(c!==!1&&c!==y(document)){if(!c||!c.focus){w(d());return}c.focus({preventScroll:!!a.preventScroll}),i.mostRecentlyFocusedNode=c,Ar(c)&&c.select()}},E=function(c){var f=h("setReturnFocus",c);return f||(f===!1?!1:c)},g=function(c){var f=c.target,p=c.event,C=c.isBackward,I=C===void 0?!1:C;f=f||Ae(p),v();var M=null;if(i.tabbableGroups.length>0){var P=l(f,p),z=P>=0?i.containerGroups[P]:void 0;if(P<0)I?M=i.tabbableGroups[i.tabbableGroups.length-1].lastTabbableNode:M=i.tabbableGroups[0].firstTabbableNode;else if(I){var m=ft(i.tabbableGroups,function(B){var U=B.firstTabbableNode;return f===U});if(m<0&&(z.container===f||_e(f,a.tabbableOptions)&&!le(f,a.tabbableOptions)&&!z.nextTabbableNode(f,!1))&&(m=P),m>=0){var x=m===0?i.tabbableGroups.length-1:m-1,$=i.tabbableGroups[x];M=se(f)>=0?$.lastTabbableNode:$.lastDomTabbableNode}else ge(p)||(M=z.nextTabbableNode(f,!1))}else{var K=ft(i.tabbableGroups,function(B){var U=B.lastTabbableNode;return f===U});if(K<0&&(z.container===f||_e(f,a.tabbableOptions)&&!le(f,a.tabbableOptions)&&!z.nextTabbableNode(f))&&(K=P),K>=0){var Q=K===i.tabbableGroups.length-1?0:K+1,q=i.tabbableGroups[Q];M=se(f)>=0?q.firstTabbableNode:q.firstDomTabbableNode}else ge(p)||(M=z.nextTabbableNode(f))}}else M=h("fallbackFocus");return M},S=function(c){var f=Ae(c);if(!(l(f,c)>=0)){if(ye(a.clickOutsideDeactivates,c)){s.deactivate({returnFocus:a.returnFocusOnDeactivate});return}ye(a.allowOutsideClick,c)||c.preventDefault()}},T=function(c){var f=Ae(c),p=l(f,c)>=0;if(p||f instanceof Document)p&&(i.mostRecentlyFocusedNode=f);else{c.stopImmediatePropagation();var C,I=!0;if(i.mostRecentlyFocusedNode)if(se(i.mostRecentlyFocusedNode)>0){var M=l(i.mostRecentlyFocusedNode),P=i.containerGroups[M].tabbableNodes;if(P.length>0){var z=P.findIndex(function(m){return m===i.mostRecentlyFocusedNode});z>=0&&(a.isKeyForward(i.recentNavEvent)?z+1
H)for(;E<=B;)Le(u[E],b,S,!0),E++;else{const W=E,z=E,Q=new Map;for(E=z;E<=H;E++){const be=d[E]=R?Ge(d[E]):Ae(d[E]);be.key!=null&&Q.set(be.key,E)}let te,ae=0;const Te=H-z+1;let pt=!1,zr=0;const St=new Array(Te);for(E=0;E {const{el:S,type:L,transition:x,children:R,shapeFlag:E}=u;if(E&6){tt(u.component.subTree,d,g,_);return}if(E&128){u.suspense.move(d,g,_);return}if(E&64){L.move(u,d,g,ht);return}if(L===ye){r(S,d,g);for(let B=0;B 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. Actions are passed into the The 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. The Beacon SDK is composed of various components that allow developers to create dynamic and interactive character sheets for virtual tabletop (VTT) games. These 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. Actions Actions 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. Handlers Handlers 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. Computed Computed 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. Macro Attributes Macro 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. Rolls 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. 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 Computed properties are passed into the TIP Handler functions allow the sheet to respond to messages from the host. The The The event object contains the following: Note: This function may be called multiple times during development in the sheet sandbox as part of hot reloads. Coordinates 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, Coordinates 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. When utilizing Macros within the VTT, there are instances where a legacy macro might need to be employed for a Beacon sheet. This scenario commonly arises when transitioning from an existing legacy sheet to a Beacon sheet. During such transitions, it's possible that the attributes called from the legacy macro may not align with the structure of attributes in the Beacon Sheet. The 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's value. Advanced sheet macros typically first search through the defined computed properties before resorting to the The function'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. 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 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. Tagging an element with both a 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 are interactive elements that trigger sheet actions, such as damage rolls, when clicked. These buttons use the Additional arguments can be provided using the The The The partial character passed in here must contain the When updating a character’s attributes, only include those attributes that have changed. Like However, this function takes a full set of character attributes as the Updates sheet settings that are shared across all people in the game. Returns a promise that can be awaited. The The The function returns a promise that resolves with an object containing the For more information on data types, see the Types page. This function posts a message to chat, either creating a new message or overwriting an existing one. It requires a The function also accepts an options object. Currently, only The Like The It returns the results of the query as a However, not all options are allowed. Here is a list of the allowed options: The The It takes the following arguments: This method returns a promise that resolves with the computed value, which can be a string, number, or object. The It takes the following arguments: This method returns a promise that resolves with the new computed value, which can be a string, number, or object. NOTE: This function will only return the requested data; it does not return errors or extensions. The The returned token objects contain all of the token attributes available to the API. You can find the documentation here. The A round calculation string can be added via the optional The The This method updates the size of the container which holds the sheet shared settings. It also returns a promise that can be awaited. This can be used in conjunction with something like the The This method returns a promise that can be awaited. The For example, in a game with a handout named Dragon, passing in the text "this is a [Dragon]" to the NOTE: We appreciate your interest in contributing to the Beacon SDK project. Here are some guidelines to help you get started: 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. 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. Fork the Repository: Create a personal fork of the project on GitHub. Clone the Fork: Clone your fork to your local machine. Create a Branch: Create a new branch for your work. Make Changes: Make your changes to the codebase. Follow the existing code style and conventions. Run Tests: Ensure that all tests pass before submitting your changes. Commit Changes: Commit your changes with a descriptive commit message. Push Changes: Push your changes to your fork. Create 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. Unit Tests: Run unit tests with Vitest. End-to-End Tests: Run End-to-End tests with Cypress. Follow the existing code style and conventions. Use ESLint for linting. Format code with Prettier. Thank you for contributing to the Beacon SDK project! Actions are methods executed from the VTT, often used for rolls triggered from macros or chat buttons. They are defined in the sheet's configuration and can interact with character data. Computed properties are defined attributes accessible by the host, usable in macros, and assignable to token bars. They can represent derived values or complex calculations based on character data. The dispatch function provides methods for sending commands from the character sheet back to the host, including updating character data, performing actions, and interacting with the VTT interface. Roll 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. Legacy macro attributes can be mapped to the new sheet structure using the convertLegacyMacroAttributes function. Sheet developers can define how to handle legacy attribute values to ensure compatibility with existing macros. The query function displays a SweetAlert prompt to users and returns the results along with any errors. It is commonly used for interactive prompts or confirmations within the VTT interface. Tokens represent characters or objects on the virtual tabletop. Functions like getTokens, updateTokensByCharacter, and addToTracker are used to retrieve token information, update token data, and manage tokens in the turn tracker. The 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. The background color of the alert box. An entity in the game with attributes, bio, GM notes, and a token representation. A digital or printed page used to track a character's attributes, abilities, and other relevant information in a role-playing game. Properties that have both get and set methods, which can be dynamically calculated. A function to handle mapping legacy macro attributes to the new Beacon Sheet format. A set of functions enabling the sheet to send commands back to the VTT. The person who runs the game, controls the NPCs & the story, and provides challenges for the players. Methods that act as event handlers to process messages from the host. Function to initialize the SDK relay, setting up communication between the host and the character sheet. A script that automates repetitive tasks in the VTT. A predefined format for displaying the results of a dice roll. A visual representation of a character or object on the virtual tabletop, with various properties like position, size, and attributes. An online platform that allows players to play tabletop role-playing games over the internet. A message displayed when an input value does not meet specific criteria. A system that ensures the fairness and authenticity of dice rolls in the VTT by using cryptographic methods. This guide will help you set up the Beacon SDK on your machine. Before you can install the Beacon SDK, you'll need to have Node.js installed on your machine. If you don't have Node.js installed, use the following steps in the official Node.js documentation. The following steps will guide you in installing the package in your application: Add the package to your Under the For example: For more information about installing packages, refer to the NPM documentation. Run Open a terminal in the root of your application’s folder and run the following command: For more information about NPM commands, refer to the NPM install documentation. Import the necessary package contents in your application: The package exports various utilities you can use in your application. For example, you will need to utilize the Here's an import statement for that function: For more information about imports, refer to the JavaScript import documentation. The Beacon SDK is a toolset designed to enhance and streamline the development of virtual tabletop (VTT) character sheets and other interactive elements. Whether you'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. The Beacon SDK is a specialized software development kit for virtual tabletops. It facilitates creating and managing interactive character sheets, roll templates, macros, and other VTT functionalities. The SDK ensures easy communication between the VTT platform and the character sheets, allowing real-time updates and interactions. The Beacon SDK is composed of several key components: For a comprehensive overview of these components, view the components section. 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 properties. This documentation provides detailed guides and examples to help you through each step of the process. By leveraging the Beacon SDK, you can create rich, interactive, fully integrated VTT experiences that enhance gameplay and streamline game management. Whether adapting existing character sheets or building new ones from scratch, the Beacon SDK offers the tools and flexibility to bring your virtual tabletop to life. This is a quick start sheet example. This sheet will guide you through getting started with the Beacon Sheet. To set this sheet up properly, make sure that you have the following tools installed: Figure 1: Quickstart sheet Use the following steps to get started: a. Offline Development: This method will run the Vite server with the default port and environment set to development. Once this code executes successfully, you can access the Vite server at This 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. INFO In 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. b. Sandbox Development: This method will run the Vite server with the port set to This 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. To test your changes in the VTT custom sheet sandbox, you will need to add the following to the The following set of commands can come in handy when working with this sheet: This is an advanced quick start sheet example. This sheet takes an advanced approach to building the Beacon sheet. To set this sheet up properly, make sure that you have the following: Figure 1: Advanced sheet This sheet uses the same steps listed in the Beginner sheet. Immediately after implementing those three steps, you'll add the following step: You can think of this command as a sanity check you can leverage when pushing a big release for your sheet! The following set of commands can come in handy when working with this sheet: This section provides detailed descriptions and examples of the key types used in the SDK. Each type represents different aspects of characters, tokens, roll results, and macro attributes, facilitating comprehensive and flexible interactions within the VTT environment. The The The The The The The The These types control interaction with character data, tokens, roll results, and handling legacy macro attributes, making the SDK flexible for various use cases.Actions
actions: {
+ [name: string]: {
+ method: (props: {
+ dispatch: Dispatch,
+ character: Character,
+ messageId?: string,
+ rolls?: RollResults
+ }, ...args: string[]): void | Promise<void>
+ }
+}
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).method
receives a props
object containing the following properties:dispatch
: 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'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.
`,7),h=[n];function l(o,p,r,c,d,k){return a(),i("div",null,h)}const y=s(e,[["render",l]]);export{E as __pageData,y as default};
diff --git a/.vitepress/dist/assets/components_actions.md.DD4l12qJ.lean.js b/.vitepress/dist/assets/components_actions.md.DD4l12qJ.lean.js
new file mode 100644
index 0000000..5fbc565
--- /dev/null
+++ b/.vitepress/dist/assets/components_actions.md.DD4l12qJ.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a3 as t}from"./chunks/framework.D5qxx6u8.js";const E=JSON.parse('{"title":"Actions","description":"","frontmatter":{},"headers":[],"relativePath":"components/actions.md","filePath":"components/actions.md","lastUpdated":1717792017000}'),e={name:"components/actions.md"},n=t("",7),h=[n];function l(o,p,r,c,d,k){return a(),i("div",null,h)}const y=s(e,[["render",l]]);export{E as __pageData,y as default};
diff --git a/.vitepress/dist/assets/components_components-overview.md.CT9Z7mbI.js b/.vitepress/dist/assets/components_components-overview.md.CT9Z7mbI.js
new file mode 100644
index 0000000..f9a191f
--- /dev/null
+++ b/.vitepress/dist/assets/components_components-overview.md.CT9Z7mbI.js
@@ -0,0 +1 @@
+import{_ as e,c as t,o,a3 as a}from"./chunks/framework.D5qxx6u8.js";const v=JSON.parse('{"title":"Components","description":"","frontmatter":{},"headers":[],"relativePath":"components/components-overview.md","filePath":"components/components-overview.md","lastUpdated":1717792017000}'),s={name:"components/components-overview.md"},n=a('Components
Computed
tokenBarValue
property is set to true.computed: {
+ [name: string]: {
+ tokenBarValue?: boolean,
+ description?: string,
+ get: (
+ props: {
+ character: Character
+ },
+ ...args: string[]
+ ) => ComputedResult,
+ set?: (
+ props: {
+ character: Character,
+ dispatch: Dispatch
+ },
+ ...args: string[]
+ ) => void | Promise<void>
+ }
+}
initRelay
function in an object where the keys are the names of the properties, and the value should be an object containing the following:get
(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.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 }
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.Handlers
handlers
argument requires the following methods:onInit
onInit
function provides the initial set of data to the sheet.onInit(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;
character
: 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.onChange
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).onChange(e: {
+ character: Partial<Character>
+}, dispatch: Dispatch): void;
onSettingsChange
onSettingsChange
is called when either the VTT’s color theme is changed, or when the current player’s ownership of the primary character changes.onSettingsChange(e: {
+ colorTheme: string,
+ owned: boolean
+}, dispatch: Dispatch): void;
onSharedSettingsChange
onSharedSettingsChange
is called when someone changes a shared setting in the VTT.onSharedSettingsChange({ settings: { [key: string]: any } }): void;
onTranslationsRequest
onTranslationsRequest
is called before the relay is fully initialized and returns the translation JSON data corresponding to the two-letter language argument.onTranslationsRequest(language: string): { [key: string]: string };
onDragOver
(optional) onDragOver
is called when a compendium item from the compendium tab is dragged over the iframe window containing the character sheet.dragData
and coordinates
are null.onDragOver(e: {
+ coordinates: { top: number, left: number },
+ dragData: {
+ pageName: string,
+ categoryName: string,
+ expansionId: number
+ } | null
+}, dispatch: Dispatch): void
onDropOver
(optional) onDropOver
is called when a compendium item from the compendium tab is dropped over the iframe window containing the character sheet.onDropOver(e: {
+ coordinates: { top: number, left: number },
+ dropData: {
+ pageName: string,
+ categoryName: string,
+ expansionId: number
+ }
+}, dispatch: Dispatch): void
Handling Legacy Macro Attributes
convertLegacyMacroAttributes
function serves as a pivotal tool, empowering Sheet Developers to determine the mapping strategy for legacy attributes to the new Beacon Sheet.convertLegacyMacroAttributes
convertLegacyMacroAttributes: (messages: convertLegacyMacroAttributesArgs) => {}: any
convertLegacyMacroAttributes
function.Rolls
data-rollname
data-rollname
attribute tells the VTT that this HTML element is displaying the result of a roll.<span data-rollname="attack"></span>
data-computed
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.<span data-rollname="complex" data-computed="true">25</span>
Roll Buttons
data-sheet-action
attribute to specify the action to be executed.<button data-sheet-action="damage" data-args="arg1:arg2">Click Me</button>
data-args
attribute, and the character, messageId
, and original rolls will be included automatically.Dispatch
initRelay
function returns a promise that resolves with a Dispatch
object. This object can be used to interact with the relay system.Dispatch
provides methods for sending commands from the character sheet back to the host. Except when specified, all of these methods below will return a promise.update
update
method sends character changes to the host page (VTT) to persist in the data store (Firebase).characterId
and can contain any combination of the attributes
, bio
, and gmNotes
properties.dispatch.update({
+ options: { overwrite?: boolean },
+ character: Partial<Character>
+}): Promise<void>
updateCharacter
update
, updateCharacter
sends character changes to the host page (VTT) to persist in the data store (Firebase).character
argument and automatically computes the diff with existing character attributes so that only changed attributes are sent to the data store.dispatch.updateCharacter({
+ character: Partial<Character>
+}): Promise<void>
updateSharedSettings
dispatch.updateSharedSettings({
+ update: { settings: { [key: string]: any } }
+}): Promise<void>
roll
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.dispatch.roll({
+ rolls: { [rollName: string]: string } // Ex. {attack: '1d20+4', damage: \`3d6+2\`}
+ messageId?: string
+}): Promise<{messageId: string, results: RollResults }>
messageId
property can be provided to attach the roll to an existing chat message. If the messageId
property is omitted, the roll will be associated with a new chat message, and a new messageId
will be returned with the roll results.messageId
and the RollResult
. The roll result is returned in the same format as in the legacy computed roll system.post
characterId
and message content, a string containing either plain text or HTML to be posted.dispatch.post({
+ characterId: string,
+ messageId?: string,
+ content: string,
+ options?: {
+ whisper?: 'gm',
+ secret?: boolean,
+ }
+}): Promise<string>
whisper
and secret
are supported. The only valid value for whisper
is gm
, which will send the message as a whisper to the GM.secret
option is ignored unless whisper
is also set; toggling to true will cause the message to not be visible to the controlling player.roll
, messageId
can be provided to update an existing chat message, but if omitted, the function will generate a new messageId
and post a new chat message. The function returns the messageId
.query
query
function takes an options
object and uses it to display a SweetAlert
prompt to the user.dispatch.query(options: Swal2Options): {
+ isConfirmed: boolean,
+ isDenied: boolean,
+ isDismissed: boolean,
+ value?: string | number,
+ dismiss?: "cancel" | "backdrop" | "close" | "esc" | "timer",
+ errors?: string[],
+}: Promise<{
+ results: {
+ isConfirmed: boolean,
+ isDenied: boolean,
+ isDismissed: boolean,
+ value: string | number,
+ dismiss: string,
+ },
+ errors: [string]
+}>
SweetAlertResult
, along with any errors encountered. The options work exactly as described in the SweetAlert2 documentation.Allowed Options Description ariaLabel Custom aria-label for the input field. background Background color for the modal. cancelButtonAriaLabel Custom aria-label for the cancel button. cancelButtonColor Background color for the cancel button. cancelButtonText Text for the cancel button. closeButtonAriaLabel Custom aria-label for the close button. confirmButtonAriaLabel Custom aria-label for the confirm button. confirmButtonColor Background color for the confirm button. confirmButtonText Text for the confirm button. currentProgressStep Current progress step index. denyButtonAriaLabel Custom aria-label for the deny button. denyButtonColor Background color for the deny button. denyButtonText Text for the deny button. grow Grow animation for the modal ('row', 'column', 'fullscreen'). iconColor Color of the modal icon. imageAlt Alternate text for the image. imageHeight Height of the image. imageUrl URL of the image to display. imageWidth Width of the image. input Input field type ('text', 'email', 'password', etc.). inputAttributes Custom attributes for the input field. inputAutoTrim Automatically trim the input value. inputLabel Label for the input field. inputOptions Options for select inputs. inputPlaceholder Placeholder for the input field. inputValue Initial value for the input field. padding Modal window padding. position Position of the modal ('top', 'center', 'bottom'). progressSteps Progress steps, useful for multi-step forms. progressStepsDistance Distance between progress steps. returnInputValueOnDeny Return input value when denied. reverseButtons Reverse the order of buttons. showCancelButton Show the cancel button. showCloseButton Show the close button. showConfirmButton Show the confirm button. showDenyButton Show the deny button. text Text content for the modal. timer Auto close timer for the modal. timerProgressBar Show a progress bar for the timer. titleText Title for the modal. validationMessage Message for input validation. width Width of the modal. perform
perform
method executes the specified action on behalf of the character (designated by characterId
), passing in args
to the action method. This method can perform actions on behalf of any character, even a character for which the sheet does not have data.dispatch.perform({
+ characterId: string,
+ action: string,
+ args: string[],
+}): Promise<void>;
getComputed
getComputed
function is used to retrieve the value of a computed property.dispatch.getComputed({
+ characterId: string,
+ property: string,
+ args: string[],
+}): Promise<string | number | object>;
characterId
: The ID of the character whose computed property you want to get.property
: The name of the computed property to retrieve.args
: An array of string arguments that may be required by the computed property.setComputed
setComputed
function is used to set the value of a computed property.dispatch.setComputed({
+ characterId: string,
+ property: string,
+ args: string[],
+}): Promise<string | number | object>;
characterId
: The ID of the character whose computed property you want to set.property
: The name of the computed property to set.args
: An array of string arguments that may be required by the computed property.compendiumRequest
compendiumRequest
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 VTT.dispatch.compendiumRequest({
+ query: string
+}): Promise<{
+ data: Object
+ errors: Array<Error>
+ extensions: Record<string, any>
+}>;
debouncedCompendiumRequest
debouncedCompendiumRequest
works just like the compendiumRequest
method, with the exception that calls to this function are automatically debounced (at 100ms) and grouped into a single request to the compendium service.dispatch.debouncedCompendiumRequest({
+ query: string
+}): Promise<{
+ data: Object
+}>;
getTokens
getTokens
requires a character ID string and returns information about tokens on the user’s current page. The return value contains two arrays of tokens.dispatch.getTokens({
+ characterId: string
+}): Promise<{
+ selected: Token[],
+ tokens: Token[]
+}>;
tokens
array contains all tokens on the current page representing the character whose ID was provided to the function. The selected
array contains any tokens that are currently selected, regardless of which character they represent.addToTracker
addToTracker
method 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.dispatch.addToTracker({
+ tokenId?: string,
+ custom?: {
+ name: string,
+ img?: string
+ },
+ formula?: string,
+ value: string | number
+}): Promise<void>;
formula
parameter. value
is the initiative number for the item.addActionsToHost
addActionsToHost
method adds a specific action (macro) to an area of the VTT UI, either the macrobar or the token action bar. Either sheetAction
or action
can be passed in, but not both simultaneously.dispatch.addActionsToHost({
+ sheetAction?: {
+ characterId: string,
+ action: string,
+ args?: string[]
+ },
+ action?: string,
+ locations?: ['macroBar'] | ['tokenActionBar'] | ['macroBar', 'tokenActionBar'],
+ actionId?: string,
+ name: string,
+ requestId?: string
+}): void;
sheetAction
arg should be passed in when the action is designated to a character. The action
arg should be passed when the action is more generic.getActions
getActions
retrieves a specific character’s actions (macros).dispatch.getActions({
+ args: {
+ characterId?: string
+ }
+}): Promise<{
+ actions?: {} | { [id: string]: ActionFromHost }
+}>;
setContainerSize
dispatch.setContainerSize({
+ args: {
+ width?: number,
+ height?: number
+ }
+}): Promise<void>;
ResizeSensor
event listener from npm: css-element-queries to resize the container on the host automatically.updateTokensByCharacter
updateTokensByCharacter
method updates a particular character’s default token as well as all existing tokens representing that character.dispatch.updateTokensByCharacter({
+ args: {
+ characterId: string,
+ token: Partial<Token>
+ }
+}): Promise<void>;
updateTokensByIds
updateTokensByIds
method updates a single or several tokens. It also returns a promise that can be awaited.dispatch.updateTokensByIds({
+ args: {
+ tokenIds: array of ids as strings,
+ token: Partial<Token>
+ }
+}): Promise<void>;
autoLinkText
autoLinkText
goes through the text to find handout names between square brackets and converts them into links with the handoutID.dispatch.autoLinkText({
+ args: {
+ text: string
+ }
+}): Promise<string>;
autoLinkText
method returns something similar to:"this is a \`<a href="https://journal.roll20.net/8je02j0kd02k">Dragon</a>\`"
openDialogFromLink
openDialogFromLink
opens the supplied urlString
through the VTT.dispatch.openDialogFromLink({
+ args: {
+ urlString: string
+ }
+}): void;
`,92),h=[n];function l(p,r,d,o,k,c){return a(),i("div",null,h)}const u=s(e,[["render",l]]);export{g as __pageData,u as default};
diff --git a/.vitepress/dist/assets/dispatch.md.BcfYGwEY.lean.js b/.vitepress/dist/assets/dispatch.md.BcfYGwEY.lean.js
new file mode 100644
index 0000000..06e317d
--- /dev/null
+++ b/.vitepress/dist/assets/dispatch.md.BcfYGwEY.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a3 as t}from"./chunks/framework.D5qxx6u8.js";const g=JSON.parse('{"title":"Dispatch","description":"","frontmatter":{},"headers":[],"relativePath":"dispatch.md","filePath":"dispatch.md","lastUpdated":1717792017000}'),e={name:"dispatch.md"},n=t("",92),h=[n];function l(p,r,d,o,k,c){return a(),i("div",null,h)}const u=s(e,[["render",l]]);export{g as __pageData,u as default};
diff --git a/.vitepress/dist/assets/gettingstarted_contributing.md.BjD3FF_z.js b/.vitepress/dist/assets/gettingstarted_contributing.md.BjD3FF_z.js
new file mode 100644
index 0000000..c800854
--- /dev/null
+++ b/.vitepress/dist/assets/gettingstarted_contributing.md.BjD3FF_z.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as t,a3 as e}from"./chunks/framework.D5qxx6u8.js";const k=JSON.parse('{"title":"Contributing Guide","description":"","frontmatter":{},"headers":[],"relativePath":"gettingstarted/contributing.md","filePath":"gettingstarted/contributing.md","lastUpdated":1717792017000}'),a={name:"gettingstarted/contributing.md"},n=e('Contributing Guide
How to Contribute
Reporting Bugs
Suggesting Features
Code Contributions
git clone
git checkout -b feature-or-bugfix-description
npm run ci-check
git commit -m "Description of your changes"
git push origin feature-or-bugfix-description
Running Tests
npm run test:unit
npm run test:e2e
Code Style
npm run lint
npm run format
Communication
FAQ
Q1: What are actions in the context of the VTT?
Q2: How are computed properties used in the VTT?
Q3: What is the dispatch function used for?
Q4: What are roll buttons, and how do they work?
Q5: How are legacy macro attributes handled in the VTT?
Q6: What is the purpose of the query function?
Q7: How are tokens managed in the VTT?
Q8: What is the role of the convertLegacyMacroAttributesArgs type?
Glossary
Background:
Character:
Character sheet:
Computed Property:
ConvertLegacyMacroAttributes:
Dispatch:
GM (Game Master):
Handler:
InitRelay:
Macro:
Roll Template:
Token:
VTT (Virtual Tabletop):
ValidationMessage:
Quantum Roll:
Installation
Prerequisites
Step 1: Accessing Beacon SDK
npm i @roll20-official/beacon-sdk
Step 2: Install & Import
`,9),o=[n];function l(p,r,h,c,d,k){return s(),e("div",null,o)}const m=a(i,[["render",l]]);export{u as __pageData,m as default};
diff --git a/.vitepress/dist/assets/gettingstarted_installation.md.CeGvA-jF.lean.js b/.vitepress/dist/assets/gettingstarted_installation.md.CeGvA-jF.lean.js
new file mode 100644
index 0000000..0c5798b
--- /dev/null
+++ b/.vitepress/dist/assets/gettingstarted_installation.md.CeGvA-jF.lean.js
@@ -0,0 +1 @@
+import{_ as a,c as e,o as s,a3 as t}from"./chunks/framework.D5qxx6u8.js";const u=JSON.parse('{"title":"Installation","description":"","frontmatter":{},"headers":[],"relativePath":"gettingstarted/installation.md","filePath":"gettingstarted/installation.md","lastUpdated":1717792017000}'),i={name:"gettingstarted/installation.md"},n=t("",9),o=[n];function l(p,r,h,c,d,k){return s(),e("div",null,o)}const m=a(i,[["render",l]]);export{u as __pageData,m as default};
diff --git a/.vitepress/dist/assets/gettingstarted_introduction.md.D4KjaCzI.js b/.vitepress/dist/assets/gettingstarted_introduction.md.D4KjaCzI.js
new file mode 100644
index 0000000..520b010
--- /dev/null
+++ b/.vitepress/dist/assets/gettingstarted_introduction.md.D4KjaCzI.js
@@ -0,0 +1 @@
+import{_ as e,c as t,o as a,a3 as n}from"./chunks/framework.D5qxx6u8.js";const g=JSON.parse('{"title":"Introduction","description":"","frontmatter":{},"headers":[],"relativePath":"gettingstarted/introduction.md","filePath":"gettingstarted/introduction.md","lastUpdated":1717792017000}'),o={name:"gettingstarted/introduction.md"},r=n('package.json
:dependencies
object key of your package.json
, add a new string key called @roll20/beacon-sdk
with the version you want to install from our version history.{
+ "@roll20/beacon-sdk": "0.0.0"
+}
npm install
:npm install
initRelay
function from the package.import { initRelay } from '@roll20/beacon-sdk';
Introduction
What is the Beacon SDK?
Key Features
Components Overview
Getting Started
Beginner Beacon Sheet
Prerequisites
npm i @roll20-official/beacon-sdk
npm install
npm run dev
http://localhost:5173
.7620
and the environment set to staging mode.npm run sandbox
sheet.json
editor in the game settings:{
+ "advanced": true,
+ "advancedPort": 7620
+}
Useful Commands
npm run watch-scss
npm run lint
npm run format
Advanced Beacon Sheet
Prerequisites
npm run ci-check
Useful Commands
npm run watch-scss
npm run lint
npm run format
npm run type-check
npm run test:unit
npm run test:e2e:open:local
npm run test:e2e:local
npm run test:e2e
Types
Character
Character
type contains a game character, including its unique ID, name, attributes, and visual representation. It also supports optional fields for character biography and Game Master notes.type Character = {
+ id: string;
+ name: string;
+ attributes: Record<string, any>;
+ bio?: string;
+ gmNotes?: string;
+ token: Token;
+ avatar: string;
+}
character
type contains the following properties:id
: A unique identifier for the character.name
: The character's name.attributes
: A record of various attributes such as strength, agility, etc.bio
: An optional field for the character's biography.gmNotes
: Optional notes intended for the Game Master.token
: A Token
object representing the character's token on the VTT.avatar
: URL to the character's avatar image.Token
Token
type represents a character or object's visual token on the virtual tabletop. This type includes various properties related to the token's appearance, control, and interactions within the game environment.type Token = {
+ id: string;
+ layer: string;
+ imgsrc: string;
+ name: string;
+ gmnotes: string
+ controlledby: string;
+ bar1_value: string;
+ bar1_max: string;
+ bar1_link: string;
+ bar2_value: string;
+ bar2_max: string;
+ bar2_link: string;
+ bar3_value: string;
+ bar3_max: string;
+ bar3_link: string;
+ represents: string;
+ aura1_radius: string;
+ aura1_color: string;
+ aura2_radius: string;
+ aura2_color: string;
+ tint_color: string;
+ statusmarkers: string;
+ light_radius: string;
+ light_dimradius: string;
+ light_angle: string;
+ light_losangle: string;
+ adv_fow_view_distance: string;
+ sides: string;
+ lastmove: string;
+ lightColor: string;
+ currentSide: number;
+ night_vision_distance: number;
+ bright_light_distance: number;
+ low_light_distance: number;
+ limit_field_of_vision_center: number;
+ limit_field_of_vision_total: number;
+ limit_field_of_night_vision_center: number;
+ limit_field_of_night_vision_total: number;
+ directional_bright_light_total: number;
+ directional_bright_light_center: number;
+ directional_low_light_total: number;
+ directional_low_light_center: number;
+ light_sensitivity_multiplier: number;
+ dim_light_opacity: number;
+ isdrawing: boolean;
+ flipv: boolean;
+ fliph: boolean;
+ aura1_square: boolean;
+ aura2_square: boolean;
+ showname: boolean;
+ showplayers_name: boolean;
+ showplayers_bar1: boolean;
+ showplayers_bar2: boolean;
+ showplayers_bar3: boolean;
+ showplayers_aura1: boolean;
+ showplayers_aura2: boolean;
+ playersedit_name: boolean;
+ playersedit_bar1: boolean;
+ playersedit_bar2: boolean;
+ playersedit_bar3: boolean;
+ playersedit_aura1: boolean;
+ playersedit_aura2: boolean;
+ light_otherplayers: boolean;
+ light_hassight: boolean;
+ has_bright_light_vision: boolean;
+ has_night_vision: boolean;
+ emits_bright_light: boolean;
+ emits_low_light: boolean;
+ has_limit_field_of_vision: boolean;
+ has_limit_field_of_night_vision: boolean;
+ has_directional_bright_light: boolean;
+ has_directional_low_light: boolean;
+ show_tooltip: boolean;
+ lockMovement: boolean;
+}
token
type contains the following properties:id
: A unique identifier for the token.layer
: Specifies the layer the token is on, such as "map" or "objects".imgsrc
: URL to the token's image.name
: Name of the token.gmnotes
: Notes for the Game Master about the token.controlledby
: ID of the player controlling the token.bar1_value
: Current value of the first status bar.bar1_max
: Maximum value of the first status bar.bar1_link
: Link to the attribute the first bar represents.bar2_value
: Current value of the second status bar.bar2_max
: Maximum value of the second status bar.bar2_link
: Link to the attribute the second bar represents.bar3_value
: Current value of the third status bar.bar3_max
: Maximum value of the third status bar.bar3_link
: Link to the attribute the third bar represents.represents
: The character ID this token represents.aura1_radius
: Radius of the first aura.aura1_color
: Color of the first aura.aura2_radius
: Radius of the second aura.aura2_color
: Color of the second aura.tint_color
: Tint color applied to the token.statusmarkers
: Status markers applied to the token.light_radius
: Radius of the light the token emits.light_dimradius
: Radius of the dim light the token emits.light_angle
: Angle of the light emission.light_losangle
: Line of sight angle.adv_fow_view_distance
: Distance the token can see in advanced fog of war.sides
: Number of sides for multi-sided tokens.lastmove
: Coordinates of the last move.lightColor
: Color of the light emitted by the token.currentSide
: Current side displayed for multi-sided tokens.night_vision_distance
: Distance for night vision.bright_light_distance
: Distance for bright light vision.low_light_distance
: Distance for low light vision.limit_field_of_vision_center
: Center limit for the field of vision.limit_field_of_vision_total
: Total limit for the field of vision.limit_field_of_night_vision_center
: Center limit for night vision.limit_field_of_night_vision_total
: Total limit for night vision.directional_bright_light_total
: Total distance for directional bright light.directional_bright_light_center
: Center distance for directional bright light.directional_low_light_total
: Total distance for directional low light.directional_low_light_center
: Center distance for directional low light.light_sensitivity_multiplier
: Multiplier for light sensitivity.dim_light_opacity
: Opacity of the dim light.isdrawing
: Indicates if the token is a drawing.flipv
: Indicates if the token is flipped vertically.fliph
: Indicates if the token is flipped horizontally.aura1_square
: Indicates if the first aura is square.aura2_square
: Indicates if the second aura is square.showname
: Show the token's name.showplayers_name
: Show the name to players.showplayers_bar1
: Show the first bar to players.showplayers_bar2
: Show the second bar to players.showplayers_bar3
: Show the third bar to players.showplayers_aura1
: Show the first aura to players.showplayers_aura2
: Show the second aura to players.playersedit_name
: Allow players to edit the name.playersedit_bar1
: Allow players to edit the first bar.playersedit_bar2
: Allow players to edit the second bar.playersedit_bar3
: Allow players to edit the third bar.playersedit_aura1
: Allow players to edit the first aura.playersedit_aura2
: Allow players to edit the second aura.light_otherplayers
: Light is visible to other players.light_hassight
: Token has sight.has_bright_light_vision
: Token has bright light vision.has_night_vision
: Token has night vision.emits_bright_light
: Token emits bright light.emits_low_light
: Token emits low light.has_limit_field_of_vision
: Token has a limited field of vision.has_limit_field_of_night_vision
: Token has a limited night vision.has_directional_bright_light
: Token has directional bright light.has_directional_low_light
: Token has directional low light.show_tooltip
: Show tooltip for the token.lockMovement
: Lock the token's movement.RollResults
RollResults
type details the outcomes of dice rolls, including the expression used, individual dice results, and the final computed result. This type is essential for handling and displaying roll results in the game.type RollResults = {
+ [name: string]: {
+ expression: string;
+ rollName: string;
+ results: {
+ expression: string;
+ dice?: number[];
+ result: number;
+ rolls?: {
+ sides: number;
+ dice: number;
+ results: number[];
+ }[];
+ };
+ };
+}
RollResults
type contains the following properties:expression
: The dice roll formula.rollName
: The name given to this roll.results
: An object containing the roll results. expression
: The formula used for the roll.dice
: An optional array of the dice rolled.result
: The final result of the roll.rolls
: Optional detailed results of each dice rolled. sides
: Number of sides on the dice.dice
: Number of dice rolled.results
: Results of the individual dice rolls.convertLegacyMacroAttributesArgs
convertLegacyMacroAttributesArgs
type defines the arguments required for converting legacy macro attributes. This type includes the attribute name, character ID, and the character object itself.type convertLegacyMacroAttributesArgs = {
+ attribute: string;
+ characterId: string;
+ character: Character;
+}
convertLegacyMacroAttributesArgs
type contains the following properties:attribute
: The name of the attribute to be converted.characterId
: The unique identifier of the character.character
: The Character
object containing the character's data.