Scripting Beta
Preface:
oncyber scripting is in Beta. Everything tied to scripting will change, so please be prepared for changes and do not necessarily expect stable results for now! That said, we'd love your feedback and participation! Jump into our discord and share any thoughts: https://discord.gg/oncyber
What is scripting?
Scripting allows you to use javascript to introduce custom behavior to your World. This allows World Builders to create custom, interactive experiences beyond what the platform offers natively.
How scripts works
Scripting works on a World by World basis.
Go to your World (oncyber.io/studio) & click "Ctrl-E" to open the Code Editor.
In the Code Editor, you'll see different tabs available:
By default, a "main" tab will appear. This is your primary script for the World.
For each asset you add (Uploaded image, NFT, Youtube video, etc), a new tab will appear that will allow you to apply a script to that specific asset.
Certain things are within scope:
World: World Class
UI: UI Class
players.main: Client Player Class
THREE: threejs api
gsap: gsap animation lib
References
🧱 Base Class
Methods
on(eventName: string, callback: (obj: Object) => Void)
off(eventName: string, callback: (obj: Object) => Void)
🏠World Class
Properties
artworks, Get, returns the list of artworks in raw format
lookedAtArtwork, Get, return the artwork that the user is curently looking at
Events
artwork-added: { artwork: ArtworkApi }
artwork-removed: { artwork: ArtworkApi }
artwork-lookedat: { target: ArtworkApi }
artwork-lookedaway: { target: ArtworkApi }
update: delta: Number
Methods
getArtworkById(id: string): Artwork
getArtworksByName(name: string): Artwork[]
queryArtworks(query: object): Artwork[], Fetches all artworks that match the properties specified in the query object
goto(item: SpaceItem || Artwork || Npc, transition?: string ): Promise, NOTE Would be renamed to goToArtwork
createText(text: string, opts: {font: string, align: "left" || "right" || "center", width: number, scale: number, color: number[3]}): Promise => Text
addText(text, opts): Promise => Text, createText don't add the text to the world
playSound(url: string): Void
enableControls(): Void, Enable Client Player Controls, NOTE would be moved to player.main
disableControls(): Void, NOTE would be moved to player.main
add(...objects: threejs scene object): Void
remove(...objects: threejs scene object): Void
📦 SpaceItem Class
Properties
position, Get, returns the position of the space item
quaternion, Get, returns the quaternion (orientation) of the space item
rotation, Get, returns the rotation of the space item
scale, Get, returns the scale of the space item
matrix, Get, returns the object's local transformation matrix
matrixWorld, Get, returns the object's global transformation matrix
modelViewMatrix, Get, returns the model-view matrix
normalMatrix, Get, returns the normal matrix
visible, Get/Set, sets or returns the visibility status of the space item
userData, Get/Set, can be used to store custom data about the object
id, Get, returns the ID of the space item
Methods
distanceToPlayer(): Number, returns the distance to the player position
distanceToCamera(): Number, returns the distance to the camera
getWorldPosition(): Vector3, returns the world coordinates of the space item
getWorldQuaternion(): Quaternion, returns the world quaternion (orientation) of the space item
getWorldDirection(): Vector3, returns the normalized direction of the object in world space
getWorldScale(): Vector3, returns the world scale of the space item
localToWorld(): Vector3, converts a vector from local space to world space
lookAt(): Void, rotates the object to face a point in world space
rotateOnAxis(): Void, rotates the object around an axis in object space
rotateOnWorldAxis(): Void, rotates the object around an axis in world space
rotateX(), rotateY(), rotateZ(): Void, rotate the object around x/y/z axis by a certain angle
setRotationFromAxisAngle(), setRotationFromEuler(), setRotationFromMatrix(), setRotationFromQuaternion(): Void, sets the rotation of the object
translateOnAxis(), translateX(), translateY(), translateZ(): Void, translate the object by distance along an axis
updateMatrix(): Void, updates the local transformation matrix
updateMatrixWorld(): Void, updates the global transformation matrix
updateWorldMatrix(): Void, updates the world matrix and the normal matrix
worldToLocal(): Vector3, converts a vector from world space to local space
reset(): Void, resets the space item to its original state
showText(text: string, opts: object, placementOpts: object): Promise, shows text near the space item
hideText(): Void, hides the text near the space item
add(...objects: threejs scene object): Void, adds objects as children to the space item
remove(...objects: threejs scene object): Void, removes children objects from the space item
🎨 Artwork Class
Has all from SpaceItem
Properties
Properties isLookedAt, Get, returns a boolean indicating whether the artwork is currently being looked at
asset, Get, returns an object with details of the artwork including name, description, creator, collection, and type
type, Get, returns the type of the artwork (image, panorama, video, audio, html, model, text, embedhtml, youtube)
Events
class.on("event_name",function)
"lookedat": emitted when the item is looked at
"lookedaway": emitted when the item is no longer looked at
Methods
playAnimation(name: string): Void, plays the specified animation for the artwork if it's a model
stopAnimation(name: string): Void, stops the specified animation for the artwork if it's a model
play(): Void, plays the video for the artwork if it's a video
pause(): Void, pauses the video for the artwork if it's a video
📹 Camera Class
Properties
position, Get, returns a Vector3 representing the current position of the camera
rotation, Get, returns an Euler object representing the current rotation of the camera
🎮 Player Class
Properties
position, Get, returns a Vector3 representing the current position of the camera
rotation, Get, returns an Euler object representing the current rotation of the camera
🔡 Text Class
Properties
alpha, Get/Set the transparency of the text.
text, Get/Set the actual text.
align, Get/Set the text alignment. Possible values: "left", "right", "center"
color, Get/Set the text color.
fontScale, Get/Set the scale of the text.
width, Get/Set the width of the text.
Methods
snapTo(target: three object, _opts, horzOffset): Aligns the text relative to another object in the 3D space.
Last updated
