Looking for Interactive 1 docs? Find them here.

Introduction

Beam Interactive is a new way to let viewers directly control the environment in and around streamer’s broadcasts by letting viewers interact using a user interface. When a broadcast has interactivity enabled visual controls will appear beneath the broadcast's video that respond directly to the events of the broadcast. These controls can dynamically update as the broadcast progresses in response to different situations that occur.

Interactive developers and producers author interactive experiences which can run as a part of a Game or be their own entirely standalone application or tool. These experiences then get used by broadcasters to make their broadcasts interactive.

When a viewer interacts with controls, their input is sent directly to the experience allowing it to see exactly who is interacting and what they are doing. This level of engagement allows for the creation of truly unique and interactive experiences that let viewers and broadcasters experience Beam broadcasts on a whole new level.

Overview

These are the four major components used to create an interactive experience:

  1. The Game Client
  2. The Interactive Service
  3. An Interactive Project
  4. Participants
Diagram showing the structure of an interactive project

Diagram showing the structure of an interactive project

The Game Client

A Game Client is software code which processes Interactive events.It is written by an Interactive developer. Game Clients make connections to the Interactive Service and listen to events emitted from the service and take action within their environment, thus affecting the broadcast.

Game Clients can run in any environment, including:

  • In a game's existing code
  • In a 3rd party mod for a game
  • In a standalone application
  • In a game's server-side service

The Interactive Service

The Interactive Service is a service operated by Beam. A Game Client connects to it to create an interactive session. Once a session is established, the service acts as a mediator for the Interactive session. The service manages data flow and state within the session by processing and distributing data emitted from both the Game Client and Participants. To interact with the session or update any state in the session a Game Client has to send messages to the service.

An Interactive Project

An Interactive Project is created by a developer or team on Beam within our Interactive Studio. It stores settings and metadata about your interactive experience. Projects are owned by a single Beam user but can be shared with other users.

Within the Studio you can:

  • Edit your project's name and description
  • Create and store controls and scenes
  • Control who can access your project
  • Publish your project for everyone on Beam to see and use

When a Game Client connects to the Interactive Service, the game client provides your project's ID. The service reads this ID and sets up an interactive session with the saved settings and controls created in the studio.

Participants

Participants are Beam users that are watching a broadcast in a broadcaster's channel. When they join the channel they are connected to the interactive session. They are provided with a set of on-screen controls that they can use to affect the broadcast. A Game Client can react to game scenarios and interactive input to change the controls displayed to participants.

Interactive Experience Structure

An Interactive experience contains a hierarchical structure of various elements that interact with and affect the experience.

These elements are:

  • Scenes
  • Controls
  • Groups
  • Participants
Relationship between elements in the interactive hierarchy.

Relationship between elements in the interactive hierarchy.

Scenes

A scene is a named collection of controls. These controls get arranged within the scene on a grid which controls how they are displayed to participants. The Game Client can add or remove controls from a scene and control which participants are seeing which scene throughout the session. Scenes can be used to group controls together in a coherent fashion that has some meaning to the experience.

For example, in an adventure game, you might have a "Battle" scene which is displayed when a broadcaster is in battle and a "Field" scene which is displayed when they are walking around in the game world.

All Interactive Projects contain a default scene. Without any intervention from the Game Client all participants and groups will start on the default scene.

A Game Client can change which scene a participant sees by updating the group they belong to.

Groups

Groups are a way to group individual participants together. Participants within a group all see the same Scene and can contribute input to the controls on that scene. Game Clients can create and update groups at any time, including changing which scene the group is set to.

Groups can be used to create team-based experiences where groups compete to achieve a goal within the experience. For example, say a broadcaster is playing an adventure game. Interactive developers could create a "Helper" group and a "Hinderer" group. The help team would be able to heal the broadcaster and grant them buffs. The Hinderer team could spawn traps or monsters to try and get in the broadcasters way.

All participants start out in the default group. Game Clients can re-assign participants to any group from the Game Client.

Controls

A Control is an interactive component within a scene. Participants can individually interact with the control, usually with their keyboard, mouse or controller. Interactive currently has two types of controls, but additional types may be added in the future. These two controls are Buttons and Joysticks.

Buttons

A button control as displayed to a participant. This button costs one spark to press.

A button control as displayed to a participant. This button costs one spark to press.

Buttons are a rectangle positioned within a scene that a participant can click with their mouse or trigger with their keyboard or controller. Game Clients receive events when a button is interacted with:

  • `mousedown` - Emitted when a button is pressed by a participant.
  • `mouseup` - Emitted when a button is released by a participant.

Interactive developers can use buttons to allow participants to contribute to votes, cause actions to happen or even control in-game entities directly.

Buttons have a number of properties which can be edited in both the Interactive Studio and from a Game Client.

  1. Displayed text
  2. Spark Cost
  3. Progress Bar Width - Displayed at the bottom of a button.
  4. Disabled State - Disabled buttons cannot be interacted with.
  5. Cooldown Duration - Prevents interaction until it expires.
What are Sparks?

Sparks are Beam's virtual currency. Participants earn them while watching or participating in streams everywhere on Beam.

Spark Transactions
Diagram of a transaction's life cycle

Diagram of a spark transaction's life cycle, showing its transition betwen states.

When a button with a spark cost is pressed, it creates a transaction. To deduct sparks from a participant a Game Client must capture the transaction. If a transaction remains uncaptured for 5 minutes, it expires, and the cost associated with the transaction is not deducted from the user's spark balance.

This mechanism allows the Game Client to decide if a button push should deduct sparks from a participant. This feature is a great way to ensure that input from a participant is used for something in the experience before deducting sparks from their balance.

Deducted sparks are not transfered to the broadcaster.

Joysticks

Joysticks are circular controls positioned within a scene that participants can click and drag. Moving a joystick sends an input event down to the Game Client with the coordinates of the joystick relative to its center. Joystick coordinates range between -1 and 1.

A joystick display to a participant.

An idle joystick displayed to a participant. Its coordinates are 0, 0.

An illustration of the coordinate system for joysticks.

An illustration of the coordinate system for joysticks. The top left is -1, -1 and the bottom right is 1, 1.

Getting Started

Interested in making an Interactive Project? Let's get started!

Prerequisites

Before getting started, you should have the following things:

  • A Beam user account.
  • Some knowledge of programming, unless you're using an existing Game Client or Interactive Application.
  • An awesome idea.

Choosing an SDK / Environment

If you're making a Game Client from scratch, you'll need to pick an Interactive SDK.

Environment Repository / Download Documentation Description
Typescript, Nodejs & Browsers GitHub Reference Docs Great for Interactive tools and utilities and beginners.
C++ GitHub Reference Docs Integrate directly into a C++ Game.
Unity Asset Store Reference Docs
Getting Started
Prototype Quickly or integrate into a Unity based Game.

Once you've chosen an SDK from the above list, download it from its repository and get it setup in your favorite IDE and ready to go.

Creating an Interactive Project

Interactive projects are created and configured in the Interactive Studio. To create a new project visit the studio and click on the plus button:

Screenshot showing the location of the create new project button

Screenshot showing the location of the create new project button.

You'll then be prompted to enter a name for your project. Once a name is entered you'll be taken to the Project Editor.

The project editor contains tabs where each tab is a step in the creation of your project.

studio editor tabs

The steps are:

  • Info - Edit the project name and Metadata about it.
  • Build - Configure Scenes and Controls.
  • Code - Hook your Game Client up to the Project and get coding.
  • Publish - Submit your project for review by the Beam team.

The Info Step

The info step is your opportunity to describe your project and provide potential users with all the information they need to get up and running.

It is important to describe what your project does and how to install it in a clear and concise way so that users understand what you have developed and how to use it. Be sure to include some information on how users can get ahold of you if they need help or have found a bug.

During the pre-publish review the Beam team will examine your project closely to gain an understanding of what your project does, so be as thorough as possible.

The Build Step

The build step is where you design your scenes and controls for your project. The interface is divided up in to three areas:

  • Scenes
  • Controls
  • Grid

Scenes Area

This is where you will manage the scenes for your project. Scenes can be created, renamed, or deleted here. You can also select the current scene that you would like to manage controls for.

studio scenes

Controls Area

This is where you will manage the controls for the scenes in your project. Controls can be created, renamed, have their type (button or joystick) changed, spark cost adjusted, or deleted.

studio controls

Grid Area

The grid is how you specify the layout of your controls for the scene. There are three different layouts for which you can set the look of the scene: small (mobile phones), medium (tablets), and large (desktops). These different layouts are indicated by icons in the upper left area of the grid section.

To add a control to the grid, click and drag the control from the Controls section on to the Grid section. Once the control has been added to the grid you have the ability to resize, reposition, or remove the control.

For more detail on the configuration of the controls on the scene, the View JSON option in the top right of the grid section will display the relevant JSON for the scene.

Once you are finished building your scenes/controls, press the Save button in the top right of the grid section.

studio grid

The Code Step

With your projects scenes and controls set up, now it is time to complete the code portion of your project. You will need to write your own Game Client that will connect to the Interactive service.

Grab your Project Version ID from the code step displayed in the center of the screen and then utilize the documentation and samples from your chosen SDK and get creating.

The Publish Step

The final step in the studio is Publish. Publish allows you to share your project with everyone on Beam.

Before considering if an Interactive project is ready for publishing a series of questions should be asked.

  • Is this project something that everyone would use?
  • Is this project ready for every Beam broadcaster to have access to?
  • Is the info tab filled in with detailed installation and setup instructions?

If the answer to any of these is no, then the project should not be published. For cases where the project would suit being shared with a smaller group of users, it can be shared instead.

Publishing Flow

studio pubish process

A Project starts off in the draft state. In this state, you can freely make edits to it and test and share it with other users. Many projects don't leave the draft state. It's perfectly ok not to publish your project.

Once you've decided to publish your project, visit the publish tab in the interactive studio. It will perform some checks on the project to ensure that it meets some basic requirements before allowing you to submit the project.

Once submitted the Interactive review team at Beam are notified and will begin a review. While a project is in review you won't be able to edit the project. A Beam representative may also reach out to you with questions.

After a review is conducted, your project will either be accepted for publishing or denied and returned the draft state with feedback on what would need to change to get the project to a publishable state.

Should your project be accepted, a date can be discussed with the Beam team and the developers of the project. On this date, the project will be made available for all Beam users in our Interactive Store.

Sharing an Interactive Project

By default only the project's owner can use a project in a broadcast. However if you'd like other beam broadcasters to use it, then you have several options.

To manage a project's share settings click the share button in the top right of the editor.

studio share button

A dialog will be presented with three options. Changing the sharing settings of a project will delete any previous share settings

The first is the default and only lets the project owner use the project in a broadcast.

Share Codes

The second, “Anyone with the versionId and code can play”, option generates a share code. This code can be handed out to broadcasters who wants to use the project in their broadcasts. These broadcasters, provide it to the Game Client which can then gain access to use the project.

studio share code

Explicit Sharing

The third option, “Only allow specific users to play until published”, is explicit sharing it lets you share the project with named Beam users. Only users in the list can use the project. To share a project with a user search for their username in the search box and then click add.

studio explicit sharing

Protocol Overview

Beam's Interactive protocol is defined in a separate downloadable document that has precise implementation details. This section provides an introduction to the protocol.

Wire Format

The Interactive Service communicates using a protocol similar to JSON-RPC except that it is bi-directional. Clients and Servers can both call and respond to methods.

The protocol operates over a standard WebSocket connection. Both Participants and Game Clients use the same protocol definition, but different subsets of methods are available to each.

Packets

The protocol contains two types of packets: methods and replies.

Method

A method is a request for a connected entity to perform an operation. Methods are sent by both the client and the server. When a method is received, it is processed and acknowledged by the recipient, who can then reply to the method with a result or an error.

A method can contain parameters which get provided to the recipient.

Methods contain an additional property called discard which when true indicates that the recipient can choose not to respond. Methods that can be treated as events have the discard property set to true.

Reply

A reply is sent from a recipient back to the caller to indicate the result of executing that method. It can contain a result or an error which indicates what went wrong.

For full packet implementation details please refer to the protocol specification which you can download here.

Compression

By default packets on the wire are transmitted as plaintext, but the Game Client can opt to use GZIP or LZ4 compression. To do this, the Game Client must call a method providing its supported compression formats. The server will then respond with its chosen compression format.

Authentication

A Game Client needs to authenticate as a Beam user when establishing an interactive session. Two authentication methods are available.

OAuth 2.0

Beam supports OAuth 2.0 flows which enable you to get a valid OAuth 2.0 Bearer token. Tokens can be passed in the Authorization header when you initiate a connection to the interactive service.

The only required scope for an interactive connection is interactive:robot:self. For more information about Beam's OAuth visit the OAuth reference page.

XToken

You can provide an XBL XToken in the Authorization header when you initiate a connection to the interactive service. This authentication method is leveraged for Universal Windows Platform applications that are Xbox Live enabled, as well as games on Xbox One

Where to get help

Have questions? Stuck? We're here to help! We have places you can get help so drop by!

  • Gitter - Chat with our team and other developers.

  • Forums - Post a topic, and we'll get back to you.

  • Community Discord - Hang out with other developers in our community Discord.