Ask or search…
K
Comment on page

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.