dclconnect
v0.5.15
Published
A collection of utilities and helpers for building in decentraland and connecting to dclconnect services
Downloads
10
Readme
dclconnect
Installation
To use any of the helpers provided by the dclconnect utils library
1.) Please install both dclconnect AND the ecs scene utility library
npm install dclconnect
npm install @dcl/ecs-scene-utils
2.) In your tsconfig.json
- add a new path
that points to BOTH the dclconnect package AND the ecs-scene-utils libraries.
3.) Also be sure to add the include
path. You do not need to alter anything else in this file. The code below is what it should look like after a brand new dcl init
project is created.
{
"compilerOptions": {
"outFile": "./bin/game.js",
"allowJs": true,
"strict": true,
"paths": {
"dclconnect": ["./node_modules/dclconnect/dist/index.d.ts"],
"@dcl/ecs-scene-utils": [
"./node_modules/@dcl/ecs-scene-utils/dist/index.d.ts"
]
}
},
"include": [
"src/**/*.ts",
"./node_modules/@dcl/ecs-scene-utils/dist/index.js",
"./node_modules/dclconnect/dist/index.js"
],
"extends": "./node_modules/decentraland-ecs/types/tsconfig.json"
}
Getting the lastest version
npm install --save dclconnect@next
to get the latest version
BoxHighlight
Create New
The BoxHighlight
component is a graphical, non-colliding entity that can be used to attract attention to the user. It's used heavily within this package, but it can also be instanced on it's own.
BoxHighlight
has three required arguments:
position
:Vector3
for the positionscale
:Vector3
for the scaledirection
:String
indicates the direction the effect should face.- Options: "top" | "bottom" | "north" | "south" | "east" | "west"
Example
import { BoxHighlight } from 'dclconnect'
const bh = new BoxHighlight(
new Vector3(5, 2.5, 5),
new Vector3(5, 5, 5),
'north'
)
BoxHighlight.(setStripeColor/setSurfaceColor)
You can set the color (and emission) of the stripes/surface with these methods. The color values are generally between 0-1 instead of 0-255. However, if you set any of the red, green, blue values to above 1, it will glow brightly! It looks cool.
bh.setStripeColor(new Color3(1, 1, 0))
bh.setSurfaceColor(new Color3(0, 10, 1))
BoxHighlight.(setPosition/setScale)
You can adjust the position, height, width and depth of the BoxHighlight by invoking the following methods. You just need to pass along the x, y, z as parameters.
bh.setPosition(8, 3, 8)
bh.setScale(3, 6, 3)
BoxHighlight.(setDirection)
Indicate the direction that the BoxHighlight effect should point. Options: "top" | "bottom" | "north" | "south" | "east" | "west"
It's not encouraged to rotate a BoxHighlight for a few reasons. In short, this is due to the way that triggers, zones and other internal dcl entities work with collisions. You can technically rotate it, however there will be unintended effects.
bh.setDirection('top')
SplitFlap
Example
import { SplitFlap } from "dclconnect"
// Creates a display that is 11 characters long
const sf = new SplitFlap(11)
sf.setText("Event Soon!")
// Alternatively you can include the initial text in the same command
const sf2 = new SplitFlap(11, "Event Soon!")
// To quickly flip to the text without having to wait for it to cycle
// through all of the characters, you can set the `quick` value to true
const sf2.setText("Event Over!", true)
DynamicImage
Examples coming soon
DynamicImageBar
Examples coming soon
AudioControlBar
AudioStreams
Please review the official AudioStreams
docs for setting up your audio streams properly.
// For AudioStreams
const audioControlBar = new AudioControlBar(
new AudioStream('https://ice1.somafm.com/groovesalad-128-mp3')
)
VideoStreams
Please review the official VideoTexture
docs for setting up a video screen properly.
// For VideoTextures
const vclip = new VideoClip('https://Somedomain/Video.m3u8')
const myVideoTexture = new VideoTexture(vclip)
const audioControlVideoBar = new AudioControlBar(myVideoTexture)
Placement
// Once you have created an AudioControlBar you can adjust
// it's placement on the left hand side of the screen
audioControlVideoBar.setOffset(34)
Other Features/Settings
// Mute and Unmute the audio
audioControlVideoBar.mute()
audioControlVideoBar.unmute()
// Set the volume (0-100)
audioControlVideoBar.setVolume(50)
// Set the Maximum Volume (Careful with this. Some videos/streams are LOUD.
// So this is an audio dampener of sorts. Default: .2
audioControlVideoBar.setMaxVolume(1)
Wait system
import { Wait } from 'dclconnect'
//Delay a function for 5 seconds
//Use anywhere
new Wait(() => {
//executes after 5 seconds
}, 5)
Debouncer
The debouncer throttles a previous callback function from executing when the Debouncer.action() is called again subsequently
import { Debouncer } from 'dclconnect'
//add a debouncer with a 1.5 second timer
const debouncer = new Debouncer(args => {
//logic to debounce
log('Delayed action is complete')
}, 1.5)
// enables the debouncer OR reset the debouncer
// optionally you may pass arguments through to the callback function
debouncer.action(args)
onLook
Add an onLook event to your entity with ease.
import { OnLook } from 'dclconnect'
export class HighlightableBox extends Entity {
private material = new Material()
constructor() {
super()
this.addComponent(
new Transform({
position: new Vector3(8, 1, 8)
})
)
this.addComponent(new BoxShape())
this.addComponent(
new OnLook({
onFocus: () => this.highlight(true),
onBlur: () => this.highlight(false),
distance: 100
})
)
this.material.albedoColor = Color3.Blue()
this.material.metallic = 0.9
this.material.roughness = 0.1
this.addComponent(this.material)
engine.addEntity(this)
}
highlight(isActive: boolean) {
this.material.albedoColor = isActive ? Color3.Yellow() : Color3.Blue()
}
}
DCLConnectUIEmote
Add a UI element to control automatic emoting. DCLConnectUIEmote.create() requires triggerEmote
(args[0]), while iconTextureUrl
(args[1]) and menuTextureUrl
(args[2]) are optional arguments.
Update scene.json
to include the following:
"requiredPermissions": [
"ALLOW_TO_TRIGGER_AVATAR_EMOTE"
],
Usage:
import { triggerEmote, PredefinedEmote } from '@decentraland/RestrictedActions'
import { DCLConnectUIEmote } from 'dclconnect'
DCLConnectUIEmote.create(triggerEmote, [
PredefinedEmote.WAVE,
PredefinedEmote.FIST_PUMP,
PredefinedEmote.ROBOT,
PredefinedEmote.RAISE_HAND,
PredefinedEmote.CLAP,
PredefinedEmote.MONEY,
PredefinedEmote.KISS,
PredefinedEmote.TIK,
PredefinedEmote.HAMMER,
PredefinedEmote.TEKTONIK,
PredefinedEmote.DONT_SEE,
PredefinedEmote.HANDS_AIR,
PredefinedEmote.SHRUG,
PredefinedEmote.DISCO,
PredefinedEmote.DAB,
PredefinedEmote.HEAD_EXPLODDE,
])