DigitalBacon (0.3.7)

This API document is meant for software developers using the DigitalBacon JavaScript module. Looking for the Application Guide?

For past versions of this document, please checkout the version you need from GitHub

Introduction

DigitalBacon is a library to create and deploy three.js scenes that support PC, Mobile, and VR sessions without all the boilerplate required to do it yourself. Additionally this library hopes to enable developers to create more complex scenes faster by exposing the renderer, scene, camera, helper functions, and more

How to Use

You can download the DigitalBacon module from GitHub under the build folder or using a package manager like npm. Please see below for an example that has DigitalBacon installed locally via npm. Assume a div with id my-container-id is already in our html file

import * as DigitalBacon from '/node_modules/digitalbacon/build/DigitalBacon.js';

let params = { projectFilePath: './my-project.zip' };

DigitalBacon.setup("my-container-id", params);

DigitalBacon Module

Attributes
version

String

The version of DigitalBacon this module is

Assets

Object

See Assets for more info

AudioHandler

Object

See AudioHandler for more info

DigitalBaconUI

Object

See DigitalBaconUI for more info

EditorHelpers

Object

See EditorHelpers for more info

LibraryHandler

Object

See LibraryHandler for more info

OrbitDisablingPointerInteractable

Object

Extension of DigitalBacon-UI's PointerInteractable that disables orbit controls for PC and Mobile users

PartyHandler

Object

See PartyHandler for more info

ProjectHandler

Object

See ProjectHandler for more info

PubSub

Object

See PubSub for more info

Scene

Object

See Scene for more info

SettingsHandler

Object

See SettingsHandler for more info

THREE

Object

See THREE for more info

UserController

Object

See UserController for more info

Functions

setup(containerId, setupParams)

Sets up project without user editing enabled

Returns Promise<App> that resolves after initial assets have loaded

containerId

String

id of the div element you want DigitalBacon to render in

setupParams

Map

Optional

Click here for a detailed list of key/value pairs that can be provided

setupEditor(containerId, projectFilePath)

Sets up project with user editing enabled

Returns Promise<App> that resolves after initial assets have loaded

containerId

String

id of the div element you want DigitalBacon to render in

setupParams

Map

Optional

Click here for a detailed list of key/value pairs that can be provided

setupParams

projectFilePath

String

Optional

File path of the Digital Bacon project you want to load on startup. If not provided, a scene with only ambient lighting will be created

authUrl

String

Optional

The authorization url provided to you by your party service to support multi-user experiences

socketUrl

String

Optional

The party url provided to you by your party service to support multi-user experiences

disableImmersion

Boolean

Optional

If provided and true, will not enable immersive sessions for AR/VR headsets and not provide an avatar to move around the scene with for PC, mobile, and tablet users

onStart

Function

Optional

Will be called upon the user clicking the start button

setKeyboardLock(lock)

Locks/unlocks the keyboard from being used in movement

lock

Boolean

Whether or not the keyboard should be locked

getCamera()

Should only be run after Promise from setup() or setupEditor() resolves

Returns the Camera used for viewing the scene (See Three.js Camera Documentation for more details)

getDeviceType()

Should only be run after Promise from setup() or setupEditor() resolves

Returns one of "XR", "MOBILE", or "POINTER"

getRenderer()

Returns the Renderer (See Three.js WebGLRenderer Documentation for more details)

isImmersionDisabled()

Returns whether disableImmersion is enabled

App

Functions

getRenderer()

Returns the Renderer (See Three.js WebGLRenderer Documentation for more details)

getScene()

Returns the Scene (See Three.js Scene Documentation for more details)

Assets

Click on the below links to see the source code for that asset

Attributes

AudioHandler

getListener()

Useful when needing to create a Custom Asset that uses audio

Returns the AudioListener that represents the virtual listener of all audio

setListenerParent(listenerParent)

Makes the AudioListener a child of the parent

listenerParent

Object3D

The three.js Object3D you want to set as the parent of the AudioListener

DigitalBaconUI

See DigitalBaconUI documentation here

EditorHelpers

Inherit from the provided EditorHelpers when creating your own assets to enable configuring your custom assets in the editor

Attributes

FieldTypes

A static parameter accessible by EditorHelpers.EditorHelper.FieldTypes, this object contains various Field Types useful for when defining new EditorHelpers for custom assets. The tables below list the parameters you can provide for each type when defined for an EditorHelper. To see the actual parameters these Classes accept, please see the source code here

Attributes for use with EditorHelper

Required for all FieldTypes

parameter

String

parameter name of the asset that this Checkbox affects

name

String

User friendly name for this parameter. Optional when listing an inherited parameter

AssetEntityField

excludeSelf

Boolean

Optional

Whether this asset should be included in the list of options. Defaults to false

filter

function(AssetEntity)

Optional

If provided, this function will be used to determine if the asset should be included in the list or not

AudioField

No additional fields

CheckboxField

suppressMenuFocusEvent

Boolean

Optional

Suppresses the Menu Focus Event from being published

ColorField

CubeImageField

No additional fields

EnumField

map

Object<String, Any>

Map of user friendly names to their corresponding value to be used when setting the Asset's parameter

EulerField

ImageField

MaterialField

No additional fields

NumberField

min

Number

Optional

Maximum value this field can be set to

max

Number

Optional

Minimum value this field can be set to

TextField

singleLine

Boolean

Optional

Determines if the input should only allow one line of text. Defaults to false

TextureField

filter

Array<TextureType>

Optional

Only allow user to select from textures of the types provided

Vector2Field

Vector3Field

No additional fields

LibraryHandler

loadAsset(filepath, callback)

Adds image/model to library

Returns Promise<assetId> that resolves after initial assets have loaded

filepath

String

File path of the image/model you want to add

callback

function

Optional

Callback that when called, will pass in the library asset id

getType(assetId)

Returns the type of the corresponding asset. Will be one of "MODEL", "IMAGE", "LIGHT", "SHAPE", "MATERIAL", "TEXTURE", "COMPONENT", or "SYSTEM"

assetId

String

id of the asset in question

PartyHandler

Functions

isHost()

Returns whether or not the user is the Party Host

addMessageHandler(id, handler, skipQueue)

Registers a callback function that triggers when messages to the provided id are received from peers

id

String

Id that is used to filter messages

handler

function(peer, message)

Callback function triggered when messages with the provided id are found

skipQueue

Boolean

Optional

If true, will process message immediately upon receiving it instead of in the order all messages are being received

addBufferMessageHandler(id, handler, skipQueue)

Same as addMessageHandler, but for ArrayBuffer messages

id

8-bit Number | uuid String

Id that is used to filter messages

handler

function(peer, message)

Callback function triggered when messages with the provided id are found

skipQueue

Boolean

Optional

If true, will process message immediately upon receiving it instead of in the order all messages are being received

publishFromFunction(publishFunction)

Typically used when you want to block other messages in the publish queue from being sent while an asynchronous process generates the message(s) you want to publish. See the following code snippet for an example

publishFunction

function()

Callback function triggered from the publish queue

publishMessage(id, message, skipQueue, ...peerList)

Publishes a message to all or optionally some list of peers using the provided id

id

String

The id that is used to filter messages by message handlers

message

Object | String | Number

The message being sent. If message is an object, the object must be parseable by JSON.parse()

skipQueue

Boolean

Optional

If true, will send message immediately

...peerList

Expanded List<Peers>

Optional

List of peers that you want to send the message to. If not provided, message will be sent to all peers

publishBufferMessage(id, message, skipQueue, ...peerList)

Publishes an ArrayBuffer message to all or optionally some list of peers using the provided id

id

8-bit Number | 128-bit uuid Uint8Array | uuid String

The id that is used to filter messages by message handlers

message

ArrayBuffer

The message being sent

skipQueue

Boolean

Optional

If true, will send message immediately

...peerList

Expanded List<Peers>

Optional

List of peers that you want to send the message to. If not provided, message will be sent to all peers

addMessageHandlerLock()

Adds a lock to prevent messages from being processed by the message queue

Returns the lock that was created

removeMessageHandlerLock(lock)

Removes the lock from preventing messages being processed by the message queue

lock

String

The lock that was provided to you by addMessageHandlerLock()

ProjectHandler

getAsset(id)

Returns a reference to the asset instance with the following id if it exists within the project

getSessionAsset(id)

Same as getAsset(id), except includes asset instances that have been deleted from the project as well

id

String

ID of the asset instance you want a reference to

addNewAsset(assetId, params, ignorePublish, ignoreUndoRedo)

Adds a new instance to the project based on the assetId provided

Returns the asset instance that was created

assetId

String

ID of the asset you want to create that corresponds to some existing asset in the Library

params

object

Optional

Parameters used for creating the Asset

ignorePublish

Boolean

Optional

Whether the creation of this instance should not be broadcasted to other users. Defaults to false (will be broadcasted to other users)

ignoreUndoRedo

Boolean

Optional

Whether the creation of this instance should not be registered as an action that can be undone + redone. Defaults to false (can be undone + redone)

addAsset(asset, ignorePublish, ignoreUndoRedo)

Adds the asset to the project

asset

Asset Instance

The asset you want to add to the project

ignorePublish

Boolean

Optional

Whether the addition of this instance to the project should not be broadcasted to other users. Defaults to false (will be broadcasted to other users)

ignoreUndoRedo

Boolean

Optional

Whether the addition of this instance to the project should not be registered as an action that can be undone + redone. Defaults to false (can be undone + redone)

deleteAsset(asset, ignorePublish, ignoreUndoRedo)

Deletes the asset from the project

asset

Asset Instance

The asset you want to delete from the project

ignorePublish

Boolean

Optional

Whether the deletion of this instance should not be broadcasted to other users. Defaults to false (will be broadcasted to other users)

ignoreUndoRedo

Boolean

Optional

Whether the deletion of this instance should not be registered as an action that can be undone + redone. Defaults to false (can be undone + redone)

load(filepath, successCallback, errorCallback)

Loads the provided Digital Bacon project

filepath

String

File path of the Digital Bacon project you want to load

successCallback

function

Optional

Callback function that is triggered after successfully loading the project file

errorCallback

function

Optional

Callback function that is triggered if an error occerred while loading the project file

PubSub

Functions

subscribe(ownerId, topic, callback)

Registers a callback function that triggers when internal messages to the provided topic are received. A given owner can only have 1 subscription per topic

ownerId

String

An id used to identify the publisher/subscriber. If the same ownerId was used to publish to this topic, then this callback function won't be triggered

topic

String

Topic that is listened to

handler

function(peer, message)

Callback function triggered when messages with the provided topic are found

unsubscribe(ownerId, topic)

Unregisters the callback function that was provided when subscribing with this same ownerId and topic

ownerId

String

The id that was used when subscribing to this same topic before

topic

String

Topic that is listened to

publish(ownerId, topic, message, urgent)

Publishes a message to the given topic

ownerId

String

An id used to identify the publisher/subscriber. If the same ownerId is subscribed to this topic, then that callback function won't be triggered

topic

String

Topic that is published to

message

Any

Data that you want to publish

urgent

Boolean

Optional

If you want the message to be published immediately, instead of during the publishing period that occurs once per frame

SettingsHandler

Functions

setUserSetting(key, value, ignorePublish)

Updates the value of a user setting

key

String

They key associated with the user setting such as "Enable Flying"

value

Any

The value of the setting you want set to

ignorePublish

Boolean

Optional

If true, will suppress the "SETTINGS_UPDATED" message published through PubSub

THREE

See three.js documentation here

UserController

Functions

getAvatar()

Gets the Avatar of the user

getController(handedness)

Returns the XRController of user for the corresponding side. Returns null if the user is not on an XR device

handedness

String (RIGHT or LEFT)

Which XRController you want

getHand(handedness)

Returns the XRHand of user for the corresponding side. Returns null if the user is not on an XR device

handedness

String (RIGHT or LEFT)

Which XRHand you want