DigitalBacon (0.1.9)

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. When importing it into your project, Digital Bacon requires three.js, three-mesh-ui, and three-mesh-bvh to be included in the import map. Please see below for an example that has the dependencies installed locally via npm

<script type="importmap">
  {
    "imports": {
      "DigitalBacon": "/node_modules/digitalbacon/build/DigitalBacon.js",
      "three": "/node_modules/three/build/three.module.js",
      "three-mesh-ui": "/node_modules/three-mesh-ui/build/three-mesh-ui.module.js",
      "three-mesh-bvh": "/node_modules/three-mesh-bvh/build/index.module.js"
    }
  }
</script>

Then in the script you want to use the module in, you can import either the attributes and functions you need individually or everything as so

import * as DigitalBacon from 'DigitalBacon';

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
EditorHelpers	Object See EditorHelpers for more info
InputHandler	Object See InputHandler for more info
Interactables	Object See Interactables for more info
LibraryHandler	Object See LibraryHandler for more info
MenuInputs	Object See MenuInputs for more info
PartyHandler	Object See PartyHandler for more info
PartyMessageHelper	Object See PartyMessageHelper for more info
ProjectHandler	Object See ProjectHandler for more info
PubSub	Object See PubSub for more info
SettingsHandler	Object See SettingsHandler 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
onStart	Function Optional Will be called upon the user clicking the start button

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"

disableImmersion()

Disables immersive capabilities such as the UserController and Menu. Must be run before calling either setup() or setupEditor()

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

• Asset
• AssetEntity
• AudioAsset
• ClampedTexturePlane
• CustomAsset
• CustomAssetEntity
• GLTFAsset
• Component
• Material
• BasicMaterial
• StandardMaterial
• ToonMaterial
• AmbientLight
• BoxShape
• CircleShape
• ConeShape
• CylinderShape
• Light
• Shape
• PlaneShape
• PointLight
• RingShape
• SphereShape
• TorusShape
• Texture
• BasicTexture
• CubeTexture
• System

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

EditorHelpers

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

Attributes

• AssetEntityHelper
• AudioHelper
• ComponentHelper
• CustomAssetHelper
• CustomAssetEntityHelper
• EditorHelper
• EditorHelperFactory
• MaterialHelper
• LightHelper
• ShapeHelper
• SystemHelper
• TextureHelper

InputHandler

addExtraControlsButton(id, name)

Adds html button to the bottom right of the screen

Returns an html button with the provided id and name

id	String The id of the button you're creating
name	String The text on the button that will be seen by the user

getExtraControlsButton(id)

Returns the html button with the provided id

id	String The id of the button you've already created

hideExtraControlsButton(id)

Sets the css display property of the html button to none

id	String The id of the button you've already created

showExtraControlsButton(id)

Sets the css display property of the html button to inline-block

id	String The id of the button you've already created

getXRGamepad(handedness)

Returns the XR Gamepad associated with the controller with the provided handedness if it exists

handedness

String (LEFT or RIGHT) The handedness associated with the controller you want the XR Gamepad for

isPointerPressed()

Returns a boolean that signifies if the mouse is currently being pressed down

isScreenTouched()

Returns a boolean that signifies if the touch screen is currently being touched

isKeyCodePressed(code)

Returns whether the key associated with the provided code is currently pressed on the keyboard

code	String The code that represents a physical key on the keyboard. Please see here for more information

Interactables

Make assets interactive by creating Interactables for them and adding them to their corresponding InteractableHandler

Attributes

• Interactable
• GripInteractable
• PointerInteractable
• GripInteractableHandler
• PointerInteractableHandler

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

MenuInputs

Object containing different Input Types. Particularly useful when defining new EditorHelpers for your 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 with MenuInputs for newly defined parameters

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

AudioInput

No additional fields

CheckboxInput

suppressMenuFocusEvent

Boolean Optional Suppresses the Menu Focus Event from being published

ColorInput

CubeImageInput

No additional fields

EnumInput

map	Object<String, Any> Map of user friendly names to their corresponding value to be used when setting the Asset's parameter

EulerInput

ImageInput

MaterialInput

No additional fields

NumberInput

min	Number Optional Maximum value this field can be set to
max	Number Optional Minimum value this field can be set to

TextureInput

filter

TextureType Optional Only allow user to select from textures of this type

TextInput

Vector2Input

Vector3Input

No additional fields

PartyHandler

Functions

isHost()

Returns whether or not the user is the Party Host

PartyMessageHelper

Functions

registerHandler(topic, handler)

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

registerBlockableHandler(topic, handler)

Same as registerHandler, but will ensure that the callback is triggered after the callbacks for other messages that are received as blockable before this message finish processing first

topic	String Topic that is listened to
handler	function(peer, message) Callback function triggered when messages with the provided topic are found

publish(message)

Publishes a message to all other peers

publishQueue(message)

Same as publish, but will ensure that the message is sent after other messages published to the queue before this are sent

message

JSON-String JSON formatted string that must include a top level parameter named "topic" that is used to forward received messages to the correct handler

ProjectHandler

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

addNewAsset(assetId, params, 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
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)

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

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