The page you are looking for doesn't exist or has been moved.
-The page you are looking for doesn't exist or has been moved.
- September 7, 20231 minute -
- -You can use blog posts for announcing product updates and features.
Well-thought-through product announcements will help increase feature awareness and engage users with new functionality. Just like sharing your public roadmap, it’s also a great way to let potential customers see that you’re constantly improving.
-September 7, 20231 minute
You can use blog posts for announcing product updates and features.
Well-thought-through product announcements will help increase feature awareness and engage users with new functionality. Just like sharing your public roadmap, it’s also a great way to let potential customers see that you’re constantly improving.
You can use blog posts for announcing product updates and features.
-- September 7, 20231 minute -
-You can use blog posts for announcing product updates and features.
September 7, 20231 minute
Release Date: 2024-07-1
-Release Date: 2024-07-1
Join the Closed Beta
- -The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
-Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
- -It 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’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.
-If 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.
-First, 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’t have to keep uploading your HTML and CSS into the custom sheet to see your changes.
-Next, 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’s what we use in our Beacon sheets.
-Lastly, 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’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.
-That is up to you and your comfort level. If you’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.
-If 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.
-You can start learning how to build a local development environment by reading or watching the following tutorials. Note: these are not tutorials that we’ve produced, but we have found them helpful in getting started with web development.
-The 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&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.
-In short, you can rest assured that the Beacon SDK is an important tool in our toolbox moving forward.
-convertLegacyMacroAttributes function. Sheet developers can define how to handle legacy attribute values to ensure compatibility with existing macros.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.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.Join the Closed Beta
The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
It 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’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.
If 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.
First, 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’t have to keep uploading your HTML and CSS into the custom sheet to see your changes.
Next, 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’s what we use in our Beacon sheets.
Lastly, 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’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.
That is up to you and your comfort level. If you’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.
If 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.
You can start learning how to build a local development environment by reading or watching the following tutorials. Note: these are not tutorials that we’ve produced, but we have found them helpful in getting started with web development.
The 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&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.
In short, you can rest assured that the Beacon SDK is an important tool in our toolbox moving forward.
convertLegacyMacroAttributes function. Sheet developers can define how to handle legacy attribute values to ensure compatibility with existing macros.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.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.Join the Closed Beta
- -The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
-Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
- -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.
- - -Join the Closed Beta
The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
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.
Join the Closed Beta
- -The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
-Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
- -We strive to make the Beacon SDK and its documentation a better tool for Community Sheet Developers like you! So before we get started, thank you for helping us make them the best they can be. It is no small task supporting all games with the best digital character sheets, but with your help, players around the world will can use awesome characeter sheets for their favorite games.
-If you find a bug with the Beacon SDK, and you want to report it, thank you. There are several ways you can go about reporting it. Feel free to choose the easiest for you. Most importantly, we want you to let us know so we can fix them.
-When you submit a bug report, it’s most helpful for you to include steps that will reliably reproduce the bug. If you don’t have those, that’s fine too. The most important thing is to report it. We’ll work with you to figure out how we can reproduce and fix the bug.
-Ultimately, our team manages our sprint work with an internal tool. No matter which method you use to report the issue, we’ll create a companion ticket in our internal tool and link it to your original report. This is why if we have questions, we can find your report, and when we’re done, we can let you know that it has been fixed.
-If you have an idea of a feature that we should add to make things easier for you or others, please let us know! Here are a few ways that you can choose from to let us know.
-Ultimately, we want to hear what is particularly painful and time consuming for you so we can work to make it easier for you to create awesome digtial character sheets for the games you love.
-Our goal it to build this site into the single source of information for Community Sheet Developers. The task of documenting everything will take time and iteration. If you find something in the documention that is wrong or needs to be updated, please let us know! You are also welcome to make a pull request of the Beacon SDK Documentation Repo, update the files, and commit your changes. We’ll review and publish them on a regular basis.
-When you do submit a pull request, thank you for helping us make the Beacon SDK project better!
- - - - - -Join the Closed Beta
The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
We strive to make the Beacon SDK and its documentation a better tool for Community Sheet Developers like you! So before we get started, thank you for helping us make them the best they can be. It is no small task supporting all games with the best digital character sheets, but with your help, players around the world will can use awesome characeter sheets for their favorite games.
If you find a bug with the Beacon SDK, and you want to report it, thank you. There are several ways you can go about reporting it. Feel free to choose the easiest for you. Most importantly, we want you to let us know so we can fix them.
When you submit a bug report, it’s most helpful for you to include steps that will reliably reproduce the bug. If you don’t have those, that’s fine too. The most important thing is to report it. We’ll work with you to figure out how we can reproduce and fix the bug.
Ultimately, our team manages our sprint work with an internal tool. No matter which method you use to report the issue, we’ll create a companion ticket in our internal tool and link it to your original report. This is why if we have questions, we can find your report, and when we’re done, we can let you know that it has been fixed.
If you have an idea of a feature that we should add to make things easier for you or others, please let us know! Here are a few ways that you can choose from to let us know.
Ultimately, we want to hear what is particularly painful and time consuming for you so we can work to make it easier for you to create awesome digtial character sheets for the games you love.
Our goal it to build this site into the single source of information for Community Sheet Developers. The task of documenting everything will take time and iteration. If you find something in the documention that is wrong or needs to be updated, please let us know! You are also welcome to make a pull request of the Beacon SDK Documentation Repo, update the files, and commit your changes. We’ll review and publish them on a regular basis.
When you do submit a pull request, thank you for helping us make the Beacon SDK project better!
Join the Closed Beta
- -The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
-Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
- -initRelay({
- //...other methods
- actions: {},
-}): Promise<Dispatch>Actions are a collection of methods that can be executed from the Roll20 Tabletop or Roll20 Characters. 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: {
- [name: string]: {
- method: (props: {
- dispatch: Dispatch,
- character: Character,
- messageId?: string,
- rolls?: RollResults
- }, ...args: string[]): void | Promise<void>
- }
-}Actions 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).
The action’s method receives a props object from the host 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.These methods 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 methods can be synchronous or asynchronous and do not return a value.
- - - - - -Join the Closed Beta
The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
initRelay({
+ //...other methods
+ actions: {},
+}): Promise<Dispatch>Actions are a collection of methods that can be executed from the Roll20 Tabletop or Roll20 Characters. 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: {
+ [name: string]: {
+ method: (props: {
+ dispatch: Dispatch,
+ character: Character,
+ messageId?: string,
+ rolls?: RollResults
+ }, ...args: string[]): void | Promise<void>
+ }
+}Actions 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).
The action’s method receives a props object from the host 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.These methods 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 methods can be synchronous or asynchronous and do not return a value.
Join the Closed Beta
- -The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
-Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
- -Sheet authors define computed properties that are accessed by the Roll20 Tabletop or Roll20 Characters. 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.
initRelay({
- //...other methods
- computed: {
- [name: string]: {
- tokenBarValue?: boolean
- description?: string
- get: (
- props: {
- character: Character
- },
- ...args: string[]
- ) => string | number | JSONValue
- set?: (
- props: {
- character: Character
- dispatch: Dispatch
- },
- ...args: string[]
- ) => void | Promise<void>
- }
- },
-}): Promise<Dispatch>Computed 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:
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.Join the Closed Beta
The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
Sheet authors define computed properties that are accessed by the Roll20 Tabletop or Roll20 Characters. 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.
initRelay({
+ //...other methods
+ computed: {
+ [name: string]: {
+ tokenBarValue?: boolean
+ description?: string
+ get: (
+ props: {
+ character: Character
+ },
+ ...args: string[]
+ ) => string | number | JSONValue
+ set?: (
+ props: {
+ character: Character
+ dispatch: Dispatch
+ },
+ ...args: string[]
+ ) => void | Promise<void>
+ }
+ },
+}): Promise<Dispatch>Computed 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:
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.Join the Closed Beta
- -The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
-Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
- -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.
dispatch.update({
- options: { overwrite?: boolean }
- character: Partial<Character>
-}): Promise<void>The 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’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.
-dispatch.updateCharacter({
- character: Partial<Character>
-}): Promise<void>Like 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.
-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 RollResult (see Types). The roll result is returned in the same format as in the non-beacon dice rolls computed roll system.
-dispatch.post({
- characterId: string,
- messageId?: string,
- content: string,
- options?: {
- whisper?: 'gm',
- secret?: boolean,
- }
-}): Promise<string>post 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.
-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]
-}>The 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:
titleText, 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.
dispatch.perform({
- characterId: string,
- action: string,
- args: string[],
-}): Promise<void>;perform 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.
dispatch.getComputed({
- characterId: string,
- property: string,
- args: string[]
-}): Promise<string | number | object>see setComputed below
dispatch.setComputed({
- characterId: string,
- property: string,
- args: string[]
-}): Promise<string | number | object>getComputed 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.
dispatch.compendiumRequest({
- query: string
-}): Promise<{
- data: Object
- errors: Array<Error>
- extensions: Record<string, any>
-}>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 Roll20 Tabletop.
dispatch.debouncedCompendiumRequest({
- query: string
-}): Promise<{
- data: Object
-}>Like 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.
dispatch.getTokens({
- characterId: string
-}): Promise<{
- selected: Token[],
- tokens: Token[]
-}>: Promise<{
- selected: Token[]
- tokens: Token[]
-}>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. 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.
dispatch.addToTracker({
- tokenId?: string,
- custom?: {
- name: string
- img?: string
- }
- formula?: string
- value: string | number
-}): Promise<void>addToTracker 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.
dispatch.addActionsToHost({
- sheetAction?: {
- characterId: string
- action: string
- args?: string[]
- }
- action?: string
- locations?: ['macroBar'] | ['tokenActionBar'] | ['macroBar', 'tokenActionBar']
- actionId?: string
- name: string
- requestId?: string
-}): voidaddActionsToHost 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.
dispatch.getActions({
- args: {
- characterId?: string
- }
-}): Promise<{
- actions?: {} | { [id: string]: ActionFromHost }
-}>getActions gets a specific character’s actions(macro).
dispatch.setContainerSize({
- args: {
- width?: number
- height?: number
- }
-}): Promise<void>setContainerSize 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.
dispatch.updateTokensByCharacter({
- args: {
- characterId: string
- token: Partial<Token>
- }
-}): Promise<void>updateTokensByCharacter updates a particular character’s default token as well as all existing tokens representing that character. Returns a promise that can be awaited.
dispatch.updateTokensByIds({
- args: {
- tokenIds: array of ids as strings
- token: Partial<Token>
- }
-}): Promise<void>updateTokensByIds updates a single or several tokens. Returns a promise that can be awaited.
dispatch.autoLinkText({
- args: {
- text: string
- }
-}): Promise<string>autoLinkText 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 <a href="https://journal.roll20.net/8je02j0kd02k">Dragon</a>.
dispatch.openDialogFromLink({
- args: {
- urlString: string
- }
-}): voidopenDialogFromLink opens the supplied urlString through the Roll20 Tabletop.
Join the Closed Beta
The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
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.
dispatch.update({
+ options: { overwrite?: boolean }
+ character: Partial<Character>
+}): Promise<void>The 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’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.
dispatch.updateCharacter({
+ character: Partial<Character>
+}): Promise<void>Like 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.
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 RollResult (see Types). The roll result is returned in the same format as in the non-beacon dice rolls computed roll system.
dispatch.post({
+ characterId: string,
+ messageId?: string,
+ content: string,
+ options?: {
+ whisper?: 'gm',
+ secret?: boolean,
+ }
+}): Promise<string>post 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.
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]
+}>The 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:
titleText, 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.
dispatch.perform({
+ characterId: string,
+ action: string,
+ args: string[],
+}): Promise<void>;perform 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.
dispatch.getComputed({
+ characterId: string,
+ property: string,
+ args: string[]
+}): Promise<string | number | object>see setComputed below
dispatch.setComputed({
+ characterId: string,
+ property: string,
+ args: string[]
+}): Promise<string | number | object>getComputed 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.
dispatch.compendiumRequest({
+ query: string
+}): Promise<{
+ data: Object
+ errors: Array<Error>
+ extensions: Record<string, any>
+}>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 Roll20 Tabletop.
dispatch.debouncedCompendiumRequest({
+ query: string
+}): Promise<{
+ data: Object
+}>Like 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.
dispatch.getTokens({
+ characterId: string
+}): Promise<{
+ selected: Token[],
+ tokens: Token[]
+}>: Promise<{
+ selected: Token[]
+ tokens: Token[]
+}>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. 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.
dispatch.addToTracker({
+ tokenId?: string,
+ custom?: {
+ name: string
+ img?: string
+ }
+ formula?: string
+ value: string | number
+}): Promise<void>addToTracker 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.
dispatch.addActionsToHost({
+ sheetAction?: {
+ characterId: string
+ action: string
+ args?: string[]
+ }
+ action?: string
+ locations?: ['macroBar'] | ['tokenActionBar'] | ['macroBar', 'tokenActionBar']
+ actionId?: string
+ name: string
+ requestId?: string
+}): voidaddActionsToHost 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.
dispatch.getActions({
+ args: {
+ characterId?: string
+ }
+}): Promise<{
+ actions?: {} | { [id: string]: ActionFromHost }
+}>getActions gets a specific character’s actions(macro).
dispatch.setContainerSize({
+ args: {
+ width?: number
+ height?: number
+ }
+}): Promise<void>setContainerSize 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.
dispatch.updateTokensByCharacter({
+ args: {
+ characterId: string
+ token: Partial<Token>
+ }
+}): Promise<void>updateTokensByCharacter updates a particular character’s default token as well as all existing tokens representing that character. Returns a promise that can be awaited.
dispatch.updateTokensByIds({
+ args: {
+ tokenIds: array of ids as strings
+ token: Partial<Token>
+ }
+}): Promise<void>updateTokensByIds updates a single or several tokens. Returns a promise that can be awaited.
dispatch.autoLinkText({
+ args: {
+ text: string
+ }
+}): Promise<string>autoLinkText 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 <a href="https://journal.roll20.net/8je02j0kd02k">Dragon</a>.
dispatch.openDialogFromLink({
+ args: {
+ urlString: string
+ }
+}): voidopenDialogFromLink opens the supplied urlString through the Roll20 Tabletop.
Join the Closed Beta
- -The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
-Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
- -Handler methods allow the sheet to respond to data passed from the Roll20 Tabletop or Roll20 Characters (both refered to as host throughout this page) to the sheet. It is the main agrument that must be passed into initRelay or the sheet will never fully load.
initRelay({
- handlers: {
- onInit,
- onChange,
- onSettingsChange,
- onSharedSettingsChange,
- onTranslationsRequest,
- onDragOver, // optional
- onDropOver, // optional
- }
- //...other methods
-}): Promise<Dispatch>The onInit method receives the initial data from the host.
This will be the first time we have access to character data, sheet settings, as well as compendium data if this character is made as a result of a compendium drag and drop on the host.
- - - -onInit(event: {
- character: Character, // Initial Data of the primary character for this sheet.
- settings: { // Campaign and character specific settings
- colorTheme: string, // 'dark' or 'light'
- language: string, // two-letter language code, i.e. 'en'
- gm: boolean, // whether or not the current player has gm permissions
- owned: boolean, // whether or not the current player controls the primary character
- settingsSheet: boolean, // whether or not this sheet is the settings sheet
- headless: boolean, // whether or not it should be displayed, set by the host
- sandbox: boolean,
- campaignId: number, // The id of the current campaign
- environment: string, // VTT, CHARACTERS, DISCORD
- currentUserId: string, // user id of user opening the sheet
- singleSheet: boolean
- },
- 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.
- pageName: string,
- categoryName: string,
- expansion: number,
- },
-}, dispatch: Dispatch): void;This function may be called multiple times during development in the sheet sandbox as part of hot reloads.
- -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 is called when either the host’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 is called when someone changes a shared setting in the host.
onSharedSettingsChange({ settings: { [key: string]: any } }): void;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 is called when a compendium item from the compendium tab is dragged over the iframe window containing the character sheet.
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, dragData and coordinates are null.
onDragOver(e: {
- coordinates: { top: number, left: number },
- dragData: {
- pageName: string
- categoryName: string
- expansionId: number
- } | null,
-}, dispatch: Dispatch) => voidonDropOver is called when a compendium item from the compendium tab is dropped over the iframe window containing the character sheet.
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.
- - - -onDropOver(e: {
- coordinates: { top: number, left: number },
- dropData: {
- pageName: string
- categoryName: string
- expansionId: number
- }
-}, dispatch: Dispatch) => voidJoin the Closed Beta
The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
Handler methods allow the sheet to respond to data passed from the Roll20 Tabletop or Roll20 Characters (both refered to as host throughout this page) to the sheet. It is the main agrument that must be passed into initRelay or the sheet will never fully load.
initRelay({
+ handlers: {
+ onInit,
+ onChange,
+ onSettingsChange,
+ onSharedSettingsChange,
+ onTranslationsRequest,
+ onDragOver, // optional
+ onDropOver, // optional
+ }
+ //...other methods
+}): Promise<Dispatch>The onInit method receives the initial data from the host.
This will be the first time we have access to character data, sheet settings, as well as compendium data if this character is made as a result of a compendium drag and drop on the host.
onInit(event: {
+ character: Character, // Initial Data of the primary character for this sheet.
+ settings: { // Campaign and character specific settings
+ colorTheme: string, // 'dark' or 'light'
+ language: string, // two-letter language code, i.e. 'en'
+ gm: boolean, // whether or not the current player has gm permissions
+ owned: boolean, // whether or not the current player controls the primary character
+ settingsSheet: boolean, // whether or not this sheet is the settings sheet
+ headless: boolean, // whether or not it should be displayed, set by the host
+ sandbox: boolean,
+ campaignId: number, // The id of the current campaign
+ environment: string, // VTT, CHARACTERS, DISCORD
+ currentUserId: string, // user id of user opening the sheet
+ singleSheet: boolean
+ },
+ 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.
+ pageName: string,
+ categoryName: string,
+ expansion: number,
+ },
+}, dispatch: Dispatch): void;This function may be called multiple times during development in the sheet sandbox as part of hot reloads.
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 is called when either the host’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 is called when someone changes a shared setting in the host.
onSharedSettingsChange({ settings: { [key: string]: any } }): void;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 is called when a compendium item from the compendium tab is dragged over the iframe window containing the character sheet.
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, dragData and coordinates are null.
onDragOver(e: {
+ coordinates: { top: number, left: number },
+ dragData: {
+ pageName: string
+ categoryName: string
+ expansionId: number
+ } | null,
+}, dispatch: Dispatch) => voidonDropOver is called when a compendium item from the compendium tab is dropped over the iframe window containing the character sheet.
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.
onDropOver(e: {
+ coordinates: { top: number, left: number },
+ dropData: {
+ pageName: string
+ categoryName: string
+ expansionId: number
+ }
+}, dispatch: Dispatch) => voidJoin the Closed Beta
- -The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
-Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
- -When utilizing Macroswithin the Roll20 Tabletop or Roll20 Characters (both refered to as host throughout this page), 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 or roll templates called from the legacy macro may not align with the structure of attributes or the lack of roll templates in the Beacon Sheet.
-The convertLegacyMacroAttributes method allows us to determine the mapping strategy for legacy attributes to the new Beacon Sheet.
initRelay({
- convertLegacyMacroAttributes: (messages: {
- attribute: string,
- characterId: string,
- character: Character
- }) => {}: any,
-}): Promise<Dispatch>This method is defined during the initial SDK initialization process and is invoked by the host when it attempts to parse a macro and encounters a failure in locating an attribute’s value during an macro’s execution.
-Advanced sheet actions typically will first search through the defined computed properties before resorting to the convertLegacyMacroAttributes method as a fallback.
The method’s purpose is to return a value that will be substituted in the macro. However, it grants us the autonomy to devise the preferred approach for handling legacy attribute values.
-Since Beacon sheets no longer require or use roll templates as previously needed in older custom sheets, there will be times where a legacy macro might make include a reference to a legacy roll template. We can use the handleLegacyRollTemplates to determine how to handle these cases.
initRelay({
- handleLegacyRollTemplates: (message: {
- templateName: string, // name of the template that triggered this method
- properties: Record<string, any>, // a list of the values and formulas for rolls and macro in the template
- // along with values for other properties in the template
- dispatch: Dispatch,
- playerid: string ,
- originalInput: string // the original text input for the entire roll template string
- }) => {}: any,
-}): Promise<Dispatch>The properites object will also include a plainText key for roll template arguments not inside the curly brace syntax.
- - - -{
- //... other arguments
- properties: {
- attack: { value: 12, formula: '1d20' },
- damage: { value: 5, formula: '2d6' },
- foo: { value: 'bar' },
- name: {
- formula: "@{Helga|name}"
- value: "Helga"
- },
- plainText: ['apicallback', 'apple=red'],
- something: {
- value: "I went to get tacos"
- },
- ............
- }
-}Join the Closed Beta
The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
When utilizing Macroswithin the Roll20 Tabletop or Roll20 Characters (both refered to as host throughout this page), 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 or roll templates called from the legacy macro may not align with the structure of attributes or the lack of roll templates in the Beacon Sheet.
The convertLegacyMacroAttributes method allows us to determine the mapping strategy for legacy attributes to the new Beacon Sheet.
initRelay({
+ convertLegacyMacroAttributes: (messages: {
+ attribute: string,
+ characterId: string,
+ character: Character
+ }) => {}: any,
+}): Promise<Dispatch>This method is defined during the initial SDK initialization process and is invoked by the host when it attempts to parse a macro and encounters a failure in locating an attribute’s value during an macro’s execution.
Advanced sheet actions typically will first search through the defined computed properties before resorting to the convertLegacyMacroAttributes method as a fallback.
The method’s purpose is to return a value that will be substituted in the macro. However, it grants us the autonomy to devise the preferred approach for handling legacy attribute values.
Since Beacon sheets no longer require or use roll templates as previously needed in older custom sheets, there will be times where a legacy macro might make include a reference to a legacy roll template. We can use the handleLegacyRollTemplates to determine how to handle these cases.
initRelay({
+ handleLegacyRollTemplates: (message: {
+ templateName: string, // name of the template that triggered this method
+ properties: Record<string, any>, // a list of the values and formulas for rolls and macro in the template
+ // along with values for other properties in the template
+ dispatch: Dispatch,
+ playerid: string ,
+ originalInput: string // the original text input for the entire roll template string
+ }) => {}: any,
+}): Promise<Dispatch>The properites object will also include a plainText key for roll template arguments not inside the curly brace syntax.
{
+ //... other arguments
+ properties: {
+ attack: { value: 12, formula: '1d20' },
+ damage: { value: 5, formula: '2d6' },
+ foo: { value: 'bar' },
+ name: {
+ formula: "@{Helga|name}"
+ value: "Helga"
+ },
+ plainText: ['apicallback', 'apple=red'],
+ something: {
+ value: "I went to get tacos"
+ },
+ ............
+ }
+}Join the Closed Beta
- -The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
-Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
- -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’s data.
initRelay({
- handlers: {
- onInit,
- onChange,
- onSettingsChange,
- onSharedSettingsChange,
- onTranslationsRequest,
- onDragOver,
- onDropOver,
- },
- actions: {},
- computed: {},
- convertLegacyMacroAttributes,
- handleLegacyRollTemplates
-}): Promise<Dispatch>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 define specific operations that can be performed by characters within the Roll20 Tabletop. These operations can range from simple tasks like rolling a dice to more complex interactions such as casting spells or activating abilities.
-Handlers are event listeners that manage communication between the Roll20 Tabletop and the character sheet. They respond to various events, such as changes in character attributes or settings, and trigger appropriate actions or updates.
-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 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.
-The Rolls component allows for advanced dice-rolling mechanics within the Roll20 Tabletop. It supports both simple and complex rolls, providing flexibility in how roll results are displayed and computed.
-The dispatch object provides methods for sending commands from the character sheet back to the host. Except when specified every method returns a promise.
-Join the Closed Beta
The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
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’s data.
initRelay({
+ handlers: {
+ onInit,
+ onChange,
+ onSettingsChange,
+ onSharedSettingsChange,
+ onTranslationsRequest,
+ onDragOver,
+ onDropOver,
+ },
+ actions: {},
+ computed: {},
+ convertLegacyMacroAttributes,
+ handleLegacyRollTemplates
+}): Promise<Dispatch>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 define specific operations that can be performed by characters within the Roll20 Tabletop. These operations can range from simple tasks like rolling a dice to more complex interactions such as casting spells or activating abilities.
Handlers are event listeners that manage communication between the Roll20 Tabletop and the character sheet. They respond to various events, such as changes in character attributes or settings, and trigger appropriate actions or updates.
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 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.
The Rolls component allows for advanced dice-rolling mechanics within the Roll20 Tabletop. It supports both simple and complex rolls, providing flexibility in how roll results are displayed and computed.
The dispatch object provides methods for sending commands from the character sheet back to the host. Except when specified every method returns a promise.
Join the Closed Beta
- -The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
-Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
- -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.
+
Join the Closed Beta
The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
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.
- -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!`,
-})The data-rollname attribute tells the host that this HTML element is displaying the result of a roll.
<span data-rollname="attack"></span>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.
-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.
<span data-rollname="complex" data-computed="true">25</span>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 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.
<button data-sheet-action="damage" data-args="arg1:arg2">Click Me</button>Additional arguments can be provided using the data-args attribute, and the character, messageId, and original rolls will be included automatically.
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])
- }[]
- }
- }
-}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.
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!`,
+})The data-rollname attribute tells the host that this HTML element is displaying the result of a roll.
<span data-rollname="attack"></span>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.
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.
<span data-rollname="complex" data-computed="true">25</span>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 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.
<button data-sheet-action="damage" data-args="arg1:arg2">Click Me</button>Additional arguments can be provided using the data-args attribute, and the character, messageId, and original rolls will be included automatically.
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])
+ }[]
+ }
+ }
+}Join the Closed Beta
- -The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
-Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
- -To set this sheet up properly, make sure that you have the following:
-To download the community quick start sheet, refer to these repositories:
-Figure 1: Advanced sheet
-This sheet uses the same steps listed in the . Immediately after implementing those three steps, you’ll add the following step:
-npm run ci-checkYou 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:
-npm run watch-scssnpm run lintnpm run formatnpm run type-checknpm run test:unitnpm run test:e2e:open:localnpm run test:e2e:localnpm run test:e2eJoin the Closed Beta
The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
To set this sheet up properly, make sure that you have the following:
To download the community quick start sheet, refer to these repositories:
Figure 1: Advanced sheet
This sheet uses the same steps listed in the . Immediately after implementing those three steps, you’ll add the following step:
npm run ci-checkYou 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:
npm run watch-scssnpm run lintnpm run formatnpm run type-checknpm run test:unitnpm run test:e2e:open:localnpm run test:e2e:localnpm run test:e2eJoin the Closed Beta
- -The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
-Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
- -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.
-To 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.
- -Before you can install the Beacon SDK, you’ll need to have the following:
-These steps use npm but you are free to use any package manager and framework you prefer.
- -The following steps will guide you in installing the Beacon SDK in your application:
-You can find the latest version of the package on the NPM registry.
-In your project’s directory, run the following:
- - - - npm i @roll20-official/beacon-sdkThis will install the Beacon SDK package to your project’s package.json file.
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.
Ideally 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.
-Add the following to your project:
- - - -import { initRelay } from '@roll20/beacon-sdk';
-
-const dispatch = initRelay({
- handlers: {
- onInit: ({ character } ) => { console.log('sheet character', character) },
- onChange: () => {},
- onSettingsChange: () => {},
- onSharedSettingsChange: () => {},
- onTranslationsRequest: () => {},
- onDragOver: () => {}
- },
- // Refer to our advanced example sheet on how to setup actions and computed properties.
- actions: {},
- computed: {}
-})initRelay 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.
On the Roll20 website visit the custom sheet sandbox and create a new sandbox, we’ll use this sandbox to develop our sheet but we must set it up to listen to our local project’s web server.
-After creating a new sandbox, we’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:
{
- "advanced": true,
- "advancedPort": 7620 // or the port of your webserver
-}After 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.
-
-
Join the Closed Beta
The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
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.
To 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.
Before you can install the Beacon SDK, you’ll need to have the following:
These steps use npm but you are free to use any package manager and framework you prefer.
The following steps will guide you in installing the Beacon SDK in your application:
You can find the latest version of the package on the NPM registry.
In your project’s directory, run the following:
npm i @roll20-official/beacon-sdkThis will install the Beacon SDK package to your project’s package.json file.
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.
Ideally 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.
Add the following to your project:
import { initRelay } from '@roll20/beacon-sdk';
+
+const dispatch = initRelay({
+ handlers: {
+ onInit: ({ character } ) => { console.log('sheet character', character) },
+ onChange: () => {},
+ onSettingsChange: () => {},
+ onSharedSettingsChange: () => {},
+ onTranslationsRequest: () => {},
+ onDragOver: () => {}
+ },
+ // Refer to our advanced example sheet on how to setup actions and computed properties.
+ actions: {},
+ computed: {}
+})initRelay 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.
On the Roll20 website visit the custom sheet sandbox and create a new sandbox, we’ll use this sandbox to develop our sheet but we must set it up to listen to our local project’s web server.
After creating a new sandbox, we’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:
{
+ "advanced": true,
+ "advancedPort": 7620 // or the port of your webserver
+}After 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.
Join the Closed Beta
- -The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
-Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
- -The Beacon SDK is a Software Development Toolset (SDK) designed to allow web developers create digital TTRPG character sheets for Roll20 using modern web development tools.
-The Beacon SDK provides a framework to create dynamic, responsive, and fully integrated character sheet for both Roll20 Tabletop and Roll20 Characters.
-The Beacon SDK gives you tools to easily access character data on Roll20 in your local web environment. This allows you hook up your local host to development sandboxes in Roll20 Tabletop and Roll20 Characters so you develop and test your characters in Roll20 using actual compendium and character data.
-Beacon SDK also gives you more tools to create and manage attributes that define your sheet’s data structure. It helps to bypass problematic callback functions, and completely removes the need for sheetworkers from the custom sheet development method.
-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.
-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 characters sheet in Roll20 Tabletop and Roll20 Characters that enhance gameplay and streamline game management for players and GMs.
-Whether adapting existing character sheets or building new ones from scratch, the Beacon SDK offers the tools and flexibility to bring your game to life.
- - -Join the Closed Beta
The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
The Beacon SDK is a Software Development Toolset (SDK) designed to allow web developers create digital TTRPG character sheets for Roll20 using modern web development tools.
The Beacon SDK provides a framework to create dynamic, responsive, and fully integrated character sheet for both Roll20 Tabletop and Roll20 Characters.
The Beacon SDK gives you tools to easily access character data on Roll20 in your local web environment. This allows you hook up your local host to development sandboxes in Roll20 Tabletop and Roll20 Characters so you develop and test your characters in Roll20 using actual compendium and character data.
Beacon SDK also gives you more tools to create and manage attributes that define your sheet’s data structure. It helps to bypass problematic callback functions, and completely removes the need for sheetworkers from the custom sheet development method.
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.
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 characters sheet in Roll20 Tabletop and Roll20 Characters that enhance gameplay and streamline game management for players and GMs.
Whether adapting existing character sheets or building new ones from scratch, the Beacon SDK offers the tools and flexibility to bring your game to life.
Join the Closed Beta
- -The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
-Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
- -To set this sheet up properly, make sure that you have the following tools installed:
-To download the community quick start sheet, refer to these repositories:
-Figure 1: Quickstart sheet
-Use the following steps to get started:
-npm i @roll20-official/beacon-sdknpm installa. Offline Development: This method will run the Vite server with the default port and environment set to development.
- - - -npm run devOnce this code executes successfully, you can access the Vite server at http://localhost:5173.
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 Roll20 Tabletop or Roll20 Characters, such as working on styling, mocking up the environment, building Vue components, testing functionality, etc.
-In development mode, you cannot save or access existing character data or use the Beacon SDK functions that depend on Roll20 Tabletop 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 7620 and the environment set to staging mode.
npm run sandboxThis command will build the SCSS files and then run the Vite server. This will set the server up for connecting to a Roll20 Tabletop custom sheet sandbox as well as through the sandbox in Roll20 Characters.
-To test your changes in the Roll20 Tabletop custom sheet sandbox, you will need to add the following to the sheet.json editor in the game settings:
{
- "advanced": true,
- "advancedPort": 7620
-}The following set of commands can come in handy when working with this sheet:
-npm run watch-scssnpm run lintnpm run formatJoin the Closed Beta
The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
To set this sheet up properly, make sure that you have the following tools installed:
To download the community quick start sheet, refer to these repositories:
Figure 1: Quickstart sheet
Use the following steps to get started:
npm i @roll20-official/beacon-sdknpm installa. Offline Development: This method will run the Vite server with the default port and environment set to development.
npm run devOnce this code executes successfully, you can access the Vite server at http://localhost:5173.
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 Roll20 Tabletop or Roll20 Characters, such as working on styling, mocking up the environment, building Vue components, testing functionality, etc.
In development mode, you cannot save or access existing character data or use the Beacon SDK functions that depend on Roll20 Tabletop 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 7620 and the environment set to staging mode.
npm run sandboxThis command will build the SCSS files and then run the Vite server. This will set the server up for connecting to a Roll20 Tabletop custom sheet sandbox as well as through the sandbox in Roll20 Characters.
To test your changes in the Roll20 Tabletop custom sheet sandbox, you will need to add the following to the sheet.json editor in the game settings:
{
+ "advanced": true,
+ "advancedPort": 7620
+}The following set of commands can come in handy when working with this sheet:
npm run watch-scssnpm run lintnpm run formatJoin the Closed Beta
- -The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
-Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
- -There are two ways you can publish a Beacon sheet.
-When publishing a sheet, you will need to includes all the necessary code, assets, and metadata packaged together to be easily deployed and tested on the Roll20 platform. When a sheet is published, either publicly or privately for testing purposes, the sheet will run on Roll20 and will no longer require a local development environment to use it.
-We allow anyone to create and release a sheet on Roll20 provided the sheet meets our code of conduct, does not infringe on our intellectual property or the intellectual property of our partners, and does not violate copyright laws. Before submitting a sheet to be released either as a test sheet in private or a publicly released sheet, please ensure that atleast one of these conditions are met.
-The following steps will aid you while releasing your sheet. These steps assume this is your first time releasing your sheet for testing, but you will likely multiple times. Each time, follow these steps, making sure that everything is up-to-date with each release.
-You must have a build command that will produce the minified production-ready code for the sheet. The build command must be able to create these exact files:
+Releasing a Sheet | Releasing a Sheet
Join the Closed Beta
The Beacon SDK is currently in closed Beta. Please complete the form to sign up for the closed beta.
Join to get access to the Beacon SDK, the community sheet repo for Beacon sheet, the community sheet developers in discord, and the new sheet developer Roll20 permissions.
There are two ways you can publish a Beacon sheet.
- You can publish a testing verison of the sheet privately and give specific Roll20 users access to it on Roll20 Characters and Roll20 Tabletop, or
- You can submit a request to publish your sheet publicly for all users on Roll20 Characters and Roll20 Tabletop to have access.
When publishing a sheet, you will need to includes all the necessary code, assets, and metadata packaged together to be easily deployed and tested on the Roll20 platform. When a sheet is published, either publicly or privately for testing purposes, the sheet will run on Roll20 and will no longer require a local development environment to use it.
Who can release a sheet?
We allow anyone to create and release a sheet on Roll20 provided the sheet meets our code of conduct, does not infringe on our intellectual property or the intellectual property of our partners, and does not violate copyright laws. Before submitting a sheet to be released either as a test sheet in private or a publicly released sheet, please ensure that atleast one of these conditions are met.
- I have authorization from the game’s publisher to make this an official sheet on Roll20 with their name attached.
- This sheet is for an unofficial fan game and it does not contain any copyright material.
- This sheet is a modification to an existing game with an open license that allows me to make a sheet for the game.
- This sheet is a homebrew game system that I created myself.
Releasing a Test Sheet
The following steps will aid you while releasing your sheet. These steps assume this is your first time releasing your sheet for testing, but you will likely multiple times. Each time, follow these steps, making sure that everything is up-to-date with each release.
Step 1: Create a build command.
You must have a build command that will produce the minified production-ready code for the sheet. The build command must be able to create these exact files:
- `sheet.js`
- `sheet.css`
@@ -494,9 +8,7 @@ Step 1: Create a build command.Step 2: Add a sheet.json file to your project.
-The `sheet.json` file holds the metadata about your sheet. We use this information to display the sheet modal in Roll20 Characters and we should it to the user when they are creating a game on Roll20 Tabletop.
+
Step 2: Add a sheet.json file to your project.
The `sheet.json` file holds the metadata about your sheet. We use this information to display the sheet modal in Roll20 Characters and we should it to the user when they are creating a game on Roll20 Tabletop.
Add a `sheet.json` file to your sheet folder. Each time you release your sheet, make sure this information is up-to-date.
@@ -517,101 +29,8 @@ Step 2: Add a sheet.j
This example comes from the `sheet.json` for the [Quickstart sheet](https://github.com/Roll20/roll20-beacon-sheets/blob/main/sheets/quickstart-example-sheet/sheet.json).
Use this table to better understand your options as you setup your own `sheet.json` file.
-
-
-
-
-Key
-Format and Options
-Description
-Required?
-
-
-
-
-advancedtrueThis indicated the type of sheet this is. true is required for Beacon Sheets. Leave this one as true.
-Yes
-
-
-legacyfalseThis indicated the type of CSS sanitization you would like to use. false is required for Beacon Sheets. Leave this one as false.
-Yes
-
-
-authors"Author name,author name"Add the name of each Author in a comma separated list.
-Yes
-
-
-roll20userid"[userID],[userID]"Add the user ID (found in the address bar when you view your profile) of each Roll20 account for the contributors on this sheet. This will give each user a “Sheet Author” badge on their Roll20 Profile. This does not have to be the same account used to develop the sheet
-No
-
-
-previewURL or filenameAccepts the URL or relative path of an image used to show off the sheet. This should be a screenshot of your sheet.
-Yes
-
-
-instructions"text"Text used in Roll20 Characters to describe the sheet. You can put information for your users here. If you have nothing to say, make sure the field is in the sheet.json but it is blank.
-Yes
-
-
-compendium"compendium_shortname"Add the compendium shortname for the compendium that you want to use for your sheet.
-No
-
-
-requestedSizewidthxheightPut a default value used to open the character sheet in Roll20 Tabletop. If you leave it out, Roll20 Tabletop will use the default size.
-No
-
-
-useroptionsan array of options
-This is an array of options from the Default Sheet Settings.
-No
-
-
-tags"Free Basic Rules,Auto-Calculations,Automated Dice,Mobile-Friendly,Alpha,Ready To Play Characters"These tags are used in Roll20 Character to indicate to the user the features that are available on this sheet. Adding a tag here does not activate the feature itself.
-No
-
-
-printabletrue or falseAdd if the sheet have been updated to be print-friendly. This will activate the print button on the character sheet.
-No
-
-
-patreonURLPlace the URL for a Patreon campaign here, and it will appear under your sheet’s description.
-No
-
-
-tipeeURLPlace the URL for a Tipeee here, and it will appear under your sheet’s description
-No
-
-
-
-You can find more information about the sheet.json used for custom sheets on the [Roll20 Wiki](https://github.com/Roll20/roll20-beacon-sheets/blob/main/sheets/quickstart-example-sheet/package.json).
-
-Step 3: Create a pull request in the Beacon Community Sheet repo.
-In the [Beacon Community Sheet Repo](https://github.com/Roll20/roll20-beacon-sheets/tree/main), create a pull request that must include the [submission checklist](https://github.com/Roll20/roll20-beacon-sheets/blob/main/.github/PULL_REQUEST_TEMPLATE.md) listed for reference below.
+
Key Format and Options Description Required? advancedtrueThis indicated the type of sheet this is. true is required for Beacon Sheets. Leave this one as true. Yes legacyfalseThis indicated the type of CSS sanitization you would like to use. false is required for Beacon Sheets. Leave this one as false. Yes authors"Author name,author name"Add the name of each Author in a comma separated list. Yes roll20userid"[userID],[userID]"Add the user ID (found in the address bar when you view your profile) of each Roll20 account for the contributors on this sheet. This will give each user a “Sheet Author” badge on their Roll20 Profile. This does not have to be the same account used to develop the sheet No previewURL or filenameAccepts the URL or relative path of an image used to show off the sheet. This should be a screenshot of your sheet. Yes instructions"text"Text used in Roll20 Characters to describe the sheet. You can put information for your users here. If you have nothing to say, make sure the field is in the sheet.json but it is blank. Yes compendium"compendium_shortname"Add the compendium shortname for the compendium that you want to use for your sheet. No requestedSizewidthxheightPut a default value used to open the character sheet in Roll20 Tabletop. If you leave it out, Roll20 Tabletop will use the default size. No useroptionsan array of options This is an array of options from the Default Sheet Settings. No tags"Free Basic Rules,Auto-Calculations,Automated Dice,Mobile-Friendly,Alpha,Ready To Play Characters"These tags are used in Roll20 Character to indicate to the user the features that are available on this sheet. Adding a tag here does not activate the feature itself. No printabletrue or falseAdd if the sheet have been updated to be print-friendly. This will activate the print button on the character sheet. No patreonURLPlace the URL for a Patreon campaign here, and it will appear under your sheet’s description. No tipeeURLPlace the URL for a Tipeee here, and it will appear under your sheet’s description No
You can find more information about the sheet.json used for custom sheets on the [Roll20 Wiki](https://github.com/Roll20/roll20-beacon-sheets/blob/main/sheets/quickstart-example-sheet/package.json).
+
Step 3: Create a pull request in the Beacon Community Sheet repo.
In the [Beacon Community Sheet Repo](https://github.com/Roll20/roll20-beacon-sheets/tree/main), create a pull request that must include the [submission checklist](https://github.com/Roll20/roll20-beacon-sheets/blob/main/.github/PULL_REQUEST_TEMPLATE.md) listed for reference below.
The name of the pull request should...
- [ ] Contain the **short name** of the sheet being submitted, and
@@ -626,144 +45,8 @@ Step 3:
- The a URL address of where the game rules can be purchased/downloaded/found.
The information that is provided here will be used to help users find the sheet in Roll20 Tabletop and Roll20 Characters. Please make sure that all names that you provide read exactly how you'd like them to be displayed. To see an example of how this information will show up, create a new game on Roll20. The name and the publisher will show up in the dropdown menu and as the title of the sheet that is selected.
-
-
-
-
-
-
- Pull requests that contain changes to files outside the sheet sub-folder on which you’re working will be rejected.
-
-
-
-
-
-Step 4: Give specific Roll20 users access.
-Before your testing sheet is finally approved, you want choose to give specific Roll20 Users access to the testing sheet. This will allow only those users to see the sheet in Roll20 Tabletop and Roll20 Characters. These users will be able to use it just like the final users will when the sheet is public. You can give access to friends, group members, or even clients and publishers you're working with.
+
Pull requests that contain changes to files outside the sheet sub-folder on which you’re working will be rejected.
Step 4: Give specific Roll20 users access.
Before your testing sheet is finally approved, you want choose to give specific Roll20 Users access to the testing sheet. This will allow only those users to see the sheet in Roll20 Tabletop and Roll20 Characters. These users will be able to use it just like the final users will when the sheet is public. You can give access to friends, group members, or even clients and publishers you're working with.
To give access to one ore more specific user's, fill out the [Beacon Sheet Access Form](https://docs.google.com/forms/d/e/1FAIpQLSdaVl_RSMdZ5Rv_Q1gIK2wtNIHd6CibhOZGdQWo833k-z9Jdg/viewform?usp=sf_link). You will need the email associated with the Roll20 Account that will have access to the sheet for each person you'd like to give access.
-
-
-
-
-
-
- We can always grant more people access to the sheet after it is released. Resubmit the Beacon Sheet Access Form to the new people for which you’d like to give access.
-
-
-
-
-
-Step 5: Wait for approval and access.
-After you create a pull request, our team will approve it and add your sheet to the sheet selection in Roll20 Tabletop and Roll20 Characters. We will then give only your Roll20 user and any others you'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.
-
-
-
-
-
-
- Submission Checklist
-
-- The pull request title contains the short name of the sheet being submitted.
-- The pull request title states the type of change being submitted (New/Update/Bugfix/etc.).
-- There is a build command for the sheet.
-- I have updated the
sheet.json file.
-- This sheet meets Roll20’s Code of Conduct.
-- This sheet does not violate the intellectual property of Roll20 or their partners.
-- This sheet does not violate copyright laws.
-
-
-
-
-
-
-Releasing a Final Version
-After you have released a test version of your sheet, you can follow the same steps as [releasing a test version](#Releasing a Test Sheet) to make your sheet available to everyone. This time, make sure to check the box for “For Public Release” in the pull request instead of updating the user access list.
-Once 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 will also follow up with any publishing partners to confirm the release of a sheet using their game system. We reserve the right to reject any sheet that does not meet our code of conduct or conflicts with our partnerships.
-
-
-
-
-
-
-
-
-
-
- Prev
- Example Patterns Sheet
-
-
-
-
-
-
-
- Next
- InitRelay
-
-
-
-
-
-
-
-
-
-
We can always grant more people access to the sheet after it is released. Resubmit the Beacon Sheet Access Form to the new people for which you’d like to give access.
After you create a pull request, our team will approve it and add your sheet to the sheet selection in Roll20 Tabletop and Roll20 Characters. We will then give only your Roll20 user and any others you'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.
+sheet.json file.After you have released a test version of your sheet, you can follow the same steps as [releasing a test version](#Releasing a Test Sheet) to make your sheet available to everyone. This time, make sure to check the box for “For Public Release” in the pull request instead of updating the user access list.
Once 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 will also follow up with any publishing partners to confirm the release of a sheet using their game system. We reserve the right to reject any sheet that does not meet our code of conduct or conflicts with our partnerships.
Roll20 Character Sheets with Modern Web Development Tools
- -The Beacon SDK connects you to Roll20 character sheet data, allowing you to create a modern web application using whatever tools you'd like. You are free to create a character sheet your way.
-With the Beacon SDK, you can make edits and run them locally. Connect to the Roll20 sandboxes to instantly see your changes in Roll20 Tabletop or Roll20 Characters. Assign a compendium and access character data while building your sheet locally, making the development process swift and efficient.
-When you’re ready, release your sheet for a select group of people, giving them access to it in Roll20 Tabletop or Roll20 Characters. Gather feedback, make changes, and playtest it again with the same group. Build a sheet millions of players can enjoy.
-Roll20 Character Sheets with Modern Web Development Tools
The Beacon SDK connects you to Roll20 character sheet data, allowing you to create a modern web application using whatever tools you'd like. You are free to create a character sheet your way.
With the Beacon SDK, you can make edits and run them locally. Connect to the Roll20 sandboxes to instantly see your changes in Roll20 Tabletop or Roll20 Characters. Assign a compendium and access character data while building your sheet locally, making the development process swift and efficient.
When you’re ready, release your sheet for a select group of people, giving them access to it in Roll20 Tabletop or Roll20 Characters. Gather feedback, make changes, and playtest it again with the same group. Build a sheet millions of players can enjoy.
Last updated on September 7, 2023
-Last updated on September 7, 2023