DigitalBacon (0.3.11)
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"
getMenuController()
Should only be run after Promise from setup() or setupEditor() resolves
Returns the Menu Controller
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
- Asset
- AssetEntity
- AudioAsset
- CustomAsset
- CustomAssetEntity
- Component
- PublishComponent
- ImageAsset
- ModelAsset
- System
- PublishSystem
- VideoAsset
- TextAsset
- TextOverlay
- PlainText
- Material
- BasicMaterial
- StandardMaterial
- ToonMaterial
- Texture
- BasicTexture
- CubeTexture
- Light
- AmbientLight
- DirectionalLight
- HemisphereLight
- PointLight
- SpotLight
- Shape
- BoxShape
- CircleShape
- ConeShape
- CylinderShape
- PlaneShape
- RingShape
- SphereShape
- TorusShape
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
- AssetEntityHelper
- ComponentHelper
- CustomAssetHelper
- CustomAssetEntityHelper
- EditorHelper
- EditorHelperFactory
- MaterialHelper
- LightHelper
- ShapeHelper
- SystemHelper
- TextAssetHelper
- TextureHelper
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 |