The scripting interface lets you run javascript code on your own server and send updates into the world. Everyone that connects to the world sees the same view of your scripted parcel. You can write scripts inside any feature on a parcel, and access other features from that script.
Once you own a parcel, you can start using the feature scripting engine. Scripting in cryptovoxels is mainly client based. That is, most scripts will be run by the client and not the server.
The hierarchy is:
For scripting examples: click here
This section includes properties, functions and events common to all plots.
ID - parcel.id = 500 - Returns an integer; the parcel's id
Owner - parcel.owner = "0x..." - Returns a string; the parcel's owner
Contributors - parcel.contributors = [] - Returns an array; the parcel's contributors list
allowLoggedInOnly - parcel.allowLoggedInOnly = false- Returns a boolean; whether the parcel allows entry to non-logged in users. Can be set
isPrivate - parcel.isPrivate = false- Returns a boolean; Returns a boolean on whether the parcel is private or not. On set to true, this will cause all players not allowed on the parcel to be kicked out. See allow,disallow.
allowedWallets - parcel.allowedWallets = ["0x..."]- Returns an array; The list of wallets allowed to enter the parcel if the parcel is private. Cannot be set, use allow,disallow.
Note: Setting a parcel private using
isPrivatewill still require the user to be in the parcel first before being kicked out
parcel.getFeatures()let features = parcel.getFeatures();
parcel.getFeatureById(id)let door = parcel.getFeatureById('door');
console.log('door:', door);
parcel.getFeatureByUuid(Uuid)let feature = parcel.getFeatureById('3ed2bdd2-7570-485d-85b3-e5fd950bf3c6');
console.log('feature:', feature);
parcel.getFeaturesByType(type)let allVoxModels = parcel.getFeaturesByType('vox-model');
Valid types are:
'vox-model''button''image''sign''polytext''audio''nft-image''megavox''text-input''slider-input''video'parcel.createFeature(type)let newFeature = parcel.createFeature('vox-model');
When a feature is created it has a scale and position of [0,0,0].
Thus, remember to give it a position and a scale once created. To learn how to that, scroll down to Feature object -> Properties.
parcel.removeFeature(f)let chair = parcel.getFeatureById('chairvox')
parcel.removeFeature(chair);
parcel.getPlayers()parcel.getPlayersWithinParcel()parcel.fetchSnapshots(callback?)parcel.setSnapshot(snapshot_id)Example:
function myCallback(snapshots){
parcel.setSnapshot(snapshots[0].id)
}
feature.on('click',e=>{
parcel.fetchSnapshots(myCallback)
})
Two things to remember:
One, when reverting your parcel to a snapshot via scripting, it will not save on the server. (only the client can see). Note also that your script will be gone because it will be overwritten.
Two, if you edit the parcel AFTER callingsetSnapshotit will save the snapshot on the server.
parcel.allow("0x..")Add wallet to the list of allowed wallets when the parcel is Private.
parcel.disallow("0x..")Remove wallet from the list of allowed wallets when the parcel is Private.
parcel.isWalletAllowedIfPrivate("0x..")Checks if wallet is allowed inside when the parcel is Private.
Player enter - parcel.on('playerenter', (e)=> {})
e containing a player object with the player's information.e.player.name -> returns "Fayelure"Player leave - parcel.on('playerleave', (e)=> {})
e containing a player object with the player's information.e.player.wallet -> returns "0xdbw2fr8..."Player nearby - parcel.on('playernearby', (e)=> {})
e containing a player object with the player's information.e.player.name -> returns "Fayelure"Player nearby - parcel.on('playeraway', (e)=> {})
e containing a player object with the player's information.e.player.name -> returns "Fayelure"move - player.on('move', (e)=> {})
Available from parcel.getPlayers() or feature.on('click', e => console.log(e.player)). Currently is just an object, but will become a class in the future.
player.name => 'captainbenis.eth'player.wallet => '0x2D891ED45C4C3EAB978513DF4B92a35Cf131d2e2'player.uuid => avatar uuid for this instance of the player (player may have multiple tabs open with seperate avatars)There are multiple ways to spoof
player.walletandplayer.name, do not trust or send funds to this address. We will tighten up the security in the future for the grid server and update these docs when we do.
player.teleportTo(coordinates)'N@43W,250N,1U'player.hasWearable(tokenId,collectionId)tokenId which is the token id of that wearable, and collectionId which is the id of the collection that wearable belongs to.player.emote('😋')console.log(emojis).player.animate('Dance')Idle , Dance, Wave, Sitting, Spin, Savage, kick, Uprock, Floss, backflip
You can also find the list within scripting console.log(animations).
player.hasEthereumNFT('0x...',5,(hasNFT)=>.., (reason)=>..(hasNFT)=>{console.log('player has NFT :',hasNFT})player.kick()This section includes properties, functions and events common to all features.
For feature-specific properties and methods, go to the features page in features.
feature.idfeature.id = 'myvoxId' feature.typeTypes include:
feature.positionfeature.position.set(1, 0.72, 2)feature.position.y = 0.72feature.set({position:[1,0.72,2]})See scripting examples for Positions
feature.scalefeature.scale.set(0.75, 0.75, 0.75)feature.scale.y = 0.75feature.set({scale:[0.75,0.75,0.75]})See scripting examples for scales.
feature.rotationset on it eg: feature.rotation.set(0, 0, 0)feature.rotation.y = 3.14.feature.set({rotation:[0,3.14,0]})See scripting examples for rotations.
While the in-world user interface uses degrees, the scripting engine uses radians.
3.14 (pi) will rotate the item 180 degrees.
nb: Position, scale and rotation are Vector3 object, with a ES6 proxy watching for updates to x, y and z.
feature.position.x = 1 works.feature.position.copyFrom(new Vector3(1, 2, 3)) worksfeature.position.set(1, 2, 3) works.feature.position.addInPlace(new Vector3(4, 5, 6)) worksfeature.position = new Vector3() won't work.feature.descriptionset on the object.set to update attributes in the description.feature.clone()feature.remove()Remove feature from the parcel
feature.set({ url: 'http://', ... })Set the properties of the feature
feature.get('url')Set the properties of the feature
feature.createAnimation('position')see Animation API
feature.startAnimations([animation])see Animation API
feature.createBasicGui('id',...)see GUI API
feature.removeGUI()removes the GUI present on this feature
button or vox models or via trigger on image,vox-model,nft-model,particle-system,megavox.
feature.on('click', (e)=> {
console.log(e.player) // Player object
console.log(e.point) // Vector3 of click in parcel space
console.log(e.normal) // Vector3 of normal at face where clicked
})
isTriggered set to true and if the user is within the trigger's range.
feature.on('trigger', (e)=> {
console.log(e.player) // Player object
})
For feature specific properties, go to your desired feature and scroll down to Scripting Properties.
This section includes properties, functions and events for basic GUIs.
gui.idfeature.id = 'myvoxId' gui.uuidgui.featuregui.showinggui.listOfControlsgui.defaultControlgui.addButton('My button')gui.addtext('My text')gui.getControlById('buttonId')gui.getControlByUuid('wdwdw-dwd-wd..')gui.getControlByUuid([1,0])gui.show()gui.destroy()This section includes properties, functions and events for basic GUIs.
guiControl.guiguiControl.idcontrol.id = 'myId' guiControl.uuidguiControl.typebutton or textguiControl.textguiControl.positionInGridguiControl.summaryguiControl.update()Update the control.