Installing Beacon

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.

Prerequisites#

Before you can install the Beacon SDK, you’ll need to have the following:

• A local web development environment with a code editor.
• Node.js installed on your machine. If you don’t have Node.js installed, use the following steps in the official Node.js documentation.
• A javascript project, we recommand Vue.js but you can choose whichever you are more comfortable with.

The following steps will guide you in installing the Beacon SDK in your application:

Step 1: Add the package to your project#

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-sdk

This will install the Beacon SDK package to your project’s package.json file.

Step 2: Use the Beacon package in your project#

The Beacon package exports various utilities you can use in your application. The main one that needs to be setup to enable the connection between Beacon SDK and Roll20 is initRelay.

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.

Step 3: Settings up the Roll20 tabletop sandbox#

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.