DEV Community: Decentraland

Decentraland SDK Tutorial room 5: 1/2 Display a UI

Decentraland — Tue, 17 Sep 2019 18:23:43 +0000

Time to enter Room 5! The next videos in our tutorial series will teach you how to click an object to display a 2D UI and create an interactive number pad as a UI.

Decentraland SDK Workshop Series - 101: Decentraland SDK

Decentraland — Tue, 17 Sep 2019 09:18:33 +0000

As part of The Decentraland Global Bootcamp online series, today, our very own SDK guru Nico will be live on Twitch, running you through all you need to know about the building blocks of the Metaverse.

Be sure to tune in! 5pm UTC.
https://www.twitch.tv/decentraland

Decentraland SDK Tutorial room 4

Decentraland — Thu, 12 Sep 2019 16:04:16 +0000

Some have compared Decentraland to an Inception-like dream world. Ridiculous! That said, your next Video Tutorial in Room 4 is how to spin an object. Erm, don’t forget your totem.

Decentraland SDK Tutorial room 3

Decentraland — Wed, 11 Sep 2019 14:00:36 +0000

We’ve added another Decentraland Video Tutorial.
Time to check out Room 3!
Learn how to move an object and trigger an action based on player position

SDK Bootcamp - Building Blocks in Decentraland

Decentraland — Wed, 11 Sep 2019 13:04:31 +0000

If you missed yesterday's live stream SDK Workshop, Building Blocks in Decentraland, you can catch the recap here

Decentraland SDK Tutorial room 2: 1/4 Add a button

Decentraland — Mon, 09 Sep 2019 18:30:26 +0000

Decentraland SDK Video Tutorials continue with Room 2.

Add another cool skill to your toolkit by learning how to activate a switch and open a door on a timer.

Dive into the tutorial below!

Creating a Sprite Fire - Using a classic technique for the newest wave in gaming

Decentraland — Mon, 09 Sep 2019 11:44:01 +0000

In the lead up to our next Game Jam, commencing September 16, participants from our June Hackathon will be taking over the Decentraland blog and revealing their design and building secrets. This week’s guest blogger is Brent Greyling from the collective Design Quarter...

Hi all. I’m a serial 3D experimentalist, qualified product designer, full-stack web developer – specialising in 3D, VR and WebXR applications – graphic designer, 360 virtual and stereo photographer and 3D modeller.

So as you can imagine, maintaining a full-time commitment to Decentraland has its challenges. But still, my dream job would be something like piloting our group’s Cyber Junk concept across the virtual world one day.

The group I speak of is called Design Quarter and we formed in 2017 to inspire and present a vibey hub/hive/lab/gallery for collaboration in matters related to 3D, design, arts and other related disciplines. We’re evolving into a one-stop shop that delivers design originals.

From initial concept to final product, however big or small the project, our aim is to profitably create, build and grow economically – for others and ourselves – within Decentraland.

Design Quarter hits the Hackathon

In the June Decentraland Hackathon, part of the Design Quarter entry was a scene featuring a 2D sprite-based fire.

As animated gifs for textures are not supported natively in the Decentraland SDK, we decided to use sprite animation. I am happy to share with you my basic understanding of this technique – a feature of video games since the late 1970s.

The code reflected here can certainly be improved upon, but I have chosen to reflect it exactly as it was used at the time.

The scene, exactly as entered, can be viewed at https://brent-ooaissvdra.now.sh

Our original source files are also available for download from https://drive.google.com/file/d/10r6vnytLCgc_r7Vb-9p2eWDFx3W9VL36/view

Sprite Animation

A Spritesheet adds texture to a flat planar surface while cycling sequentially through the various still images present on it. The illusion of animated movement or the appearance of three-dimensionality is then perceived, much like our flames growing and rising to the sky.

For economy of resources, a spritesheet is a single image file that combines multiple slightly differing images, known as frames, sequentially in ordered rows and columns. Multiple images prevent having to load a whole new texture file for each frame of animation; instead the spritesheet is re-positioned over the surface for each new render.

Complex spritesheets may contain a series of character actions from different views, each action starting on a specific frame and playing out over a certain number of frames.

A film reel can be viewed as a good example of the spritesheet concept that has a single column with many rows. As the film ‘scrolls’ the rows through the projector, the illusion of smooth movement is created on a planar big screen.

If a .png image is used for sprites, it may contain levels of transparency to better reveal and blend in with the background.

Okay, so now that we have an idea of what a sprite is. How do we actually map this spritesheet to a surface?

UV mapping

When you apply a UV map to a surface, you are assigning a texture image to XYZ coordinates of your object using a new 3D space specific to that surface. This is comprised of three vertices that make up that surface triangle, which we also call a polygon.

The relative co-ordinate values of this UV space are named UVW in order to distinguish them from the object-world XYZ. Since texturing requires only two dimensions on a flat surface, we use the UV coordinate axes and ignore the W.

Tip: By simply reversing the order of the same UV point set of a polygon we can reverse the direction in which the surface faces. This is called polygon ‘winding’ and the surface to face normal is a direct result of clockwise or anti-clockwise winding.

Square or rectangular surfaces, i.e. plane shapes, actually comprise two triangles that lie on the same plane and share one common side and thus also two vertices from each triangle. In describing a plane, instead of stating the three UVs for one triangle and another three UVs for the other – which would then contain two duplicates – we can state the four distinct points as a kind of shorthand.

Detective Work

In the comprehensive and ever-growing set of Decentraland Development Documentation, there is a section on Materials which contains the following example of UV mapping:

Although the example given above is correct for the spritemap originally used, I quickly got confused as to how it actually works. After all, my fire spritesheet is a different size, has a different number of rows and columns and the surface it is projected on has different proportions.

Simply replacing the atlas.png image with another did not work.

So I started altering the numbers, observing what they would do with my texture image as they changed. After skewing, scaling, repeating and even completely losing and then having to re-find the texture, a pattern began to emerge.

A consistent pattern, which along with the concepts above, was starting to look useful. My rough findings are annotated below to give you a basic idea of what I discovered.

plane.uvs = [
    // ONE FACE
    0.33,  // (B) Horizontal width right end position
    0,  // (C) Vertical height bottom start position
    0,  // (A) Horizontal width left start position
    0,  // (C) Vertical height bottom start position

    0,  // (A) Horizontal width left start position
    0.33,  // (D) Vertical top height end position
    0.33,  // (B) Horizontal width right end position
    0.33,  // (D) Vertical top height end position

    // OTHER FACE
    0.66,  // (B) Horizontal width right end position
    0.0,  // (C) Vertical height bottom start position
    0.33,  // (A) Horizontal width left start position
    0.0,  // (C) Vertical height bottom start position


    0.33,  // (A) Horizontal width left start position
    0.33,  // (D) Vertical top height end position
    0.66,  // (B) Horizontal width right end position
    0.33  // (D) Vertical top height end position
]

I noticed that, for the image not to be misaligned or skewed, I had to use the values in identical pairs in certain places. Please note, A, B, C and D are just my commented markers solely to indicate the matching pairs. Each value itself, between 0 and 1, expressing a dimension between 0 and 100% relating to my texture, be it the left, width, top, height, start or end.

After some more fiddling I discovered precisely what these needed to do to make the above practical.

Stepping through commented code will give you a clear and useful idea of the result.

Note how I kept the spriteRow and spriteCol variables flexible as they are unique to the image used.

Also, don’t get thrown by the dynamic calculations of the spritePlane.uvs. They are like this so that any User-defined variables are applied automatically without you having to worry.

Commented Code follows:

// User defined variables
let spriteCols = 10   // number of columns
let spriteRows = 6   // number of rows
let timer = 0.1   // timer speed
let currSpriteCel = 1   // starting position

// Calculated variables
let spriteCels = spriteCols * spriteRows
let colFactor = 1/spriteCols
let rowFactor = 1/spriteRows

// Create material
const spriteMaterial = new BasicMaterial()
spriteMaterial.texture = new Texture("materials/fire.png")

// Create shape component
const spritePlane = new PlaneShape()

// Set the starting UV's
let currRowStart = spriteRows - Math.floor((currSpriteCel-1)/spriteCols)
let currColStart = ((currSpriteCel-1)%spriteCols)

spritePlane.uvs = [

        (currColStart+1)*colFactor, (currRowStart-1)*rowFactor, 
        currColStart*colFactor, (currRowStart-1)*rowFactor,

        currColStart*colFactor, currRowStart*rowFactor, 
        (currColStart+1)*colFactor, currRowStart*rowFactor,

        (currColStart+1)*colFactor, (currRowStart-1)*rowFactor, 
        currColStart*colFactor, (currRowStart-1)*rowFactor,

        currColStart*colFactor, currRowStart*rowFactor, 
        (currColStart+1)*colFactor, currRowStart*rowFactor
]

// Create sprite entity and assign shape and initially mapped sprite material
const spriteFire = new Entity()
spriteFire.addComponent(spritePlane)
spriteFire.addComponent(new Transform({
    position: new Vector3(16, 7.3, 16),
    rotation: Quaternion.Euler(0, 0, 0),
    scale: new Vector3(2,2,2)
}))
spriteFire.addComponent(spriteMaterial)
engine.addEntity(spriteFire)

// Define system to update sprite on every frame
export class spriteAnimate {
    update(dt: number) {
        if (timer > 0) {
            timer -= dt
        } else {
            timer = 0.1
            currSpriteCel += 1

            if (currSpriteCel == spriteCels) { currSpriteCel = 1 }
            else { currSpriteCel = currSpriteCel + 1 }
            let currRowStart = spriteRows - Math.floor((currSpriteCel-1)/spriteCols)
            let currColStart = ((currSpriteCel-1)%spriteCols)
            spritePlane.uvs = [
                (currColStart+1)*colFactor, (currRowStart-1)*rowFactor, 
                currColStart*colFactor, (currRowStart-1)*rowFactor,
                currColStart*colFactor, currRowStart*rowFactor, 
                (currColStart+1)*colFactor, currRowStart*rowFactor,
                (currColStart+1)*colFactor, (currRowStart-1)*rowFactor,
                currColStart*colFactor, (currRowStart-1)*rowFactor,
                currColStart*colFactor, currRowStart*rowFactor, 
                (currColStart+1)*colFactor, currRowStart*rowFactor
            ]
        }
    }
}

// Add instance of the system to the scene
let animationSystem = engine.addSystem(new spriteAnimate())

Adding billboard functionality

Our next step toward rounding off would be to make the plane always face you.

Thankfully, Decentraland have made that part simple by supplying you with a Billboard component that takes care of that automatically. We just need to add this component to the entity that holds our sprite.

spriteFire.addComponent(new Billboard(false, true, false))

You’ll notice that there are three arguments we’re passing here, each enables or disables the billboard mode on the x, y, and z axis of rotation. Here our billboard only rotates in the Y axis, which means it will follow the player’s movements at ground level, but will keep its upwards direction fixed.

You can read more about billboards in Decentraland in the documentation site. Also, although beyond the scope of this article, to understand the math behind the Billboard a little better you are welcome to contact me.

In summary

We have now covered a few fundamentals, as well as hopefully animated a texture on a plane. We did so using a generic approach that should work correctly for various individual texture images according to how many rows and columns they contain.

Feel free to reach out in general, you'll find me hanging around Design Quarter or on Discord.

Have fun and be sure to sign up for the Game Jam, coming soon on September 16! Design Quarter plans to be there. In the meantime, I will be sharing more of my discoveries as I continue to learn and understand.

[The original fire.png is attached] This and more examples of fire can be found at: https://opengameart.org/content/animated-fire

Building Blocks of Creation

Decentraland — Mon, 09 Sep 2019 11:27:22 +0000

This is the first instalment of a series of video tutorials that will teach you the basics of using the Decentraland SDK.

We're fast approaching September 16th and the kick off of our Game Jam – a two-week event where artists and developers will create interactive 3D scenes using the Decentraland SDK and compete for over $250,000 USD of MANA and LAND prizes.

In the lead up to launch, we’re unveiling two key initiatives:

The first, which we’ll cover in an upcoming post, is a series of offline talks and bootcamps in multiple cities around the world. The second is the SDK Tutorial Series...

The building blocks of creation

The tutorials in this series cover the basic mechanics of the Decentraland SDK. This includes:

How to install the SDK
How to place and animate objects
How to manage click events
How to implement UI
How to use the new ‘utils’ library, which greatly enhances the development experience

By the end of the series you’ll have the knowledge to complete your very own Escape Room game comprising nine different rooms (which can be found in this GitHub repo), so get ready for a lot of fun!

Even if you’ve never done any game development, you’ll find these videos informative and easy to follow. They can be digested as a series or as independent modules:

What you’ll be learning

Come out like a builder. Make out like a bandit

At the conclusion of our Decentraland SDK Tutorial Series, you’ll also have everything you need to come out of the Game Jam with a qualified 3D scene which, should you submit it, could make you the recipient of 1,000 MANA, as well as LAND and prizes ranging from 25,000 to 350,000 MANA for the top 20 winners.

But you gotta be in it to win it, so sign up, scroll up and start watching. Plus make sure you stay tuned to our Decentraland SDK Tutorial Series.

See you in the Metaverse!

Learn how to add basic interactivity to an existing Builder scene

Decentraland — Tue, 27 Aug 2019 10:15:22 +0000

In the lead up to our next Game Jam, commencing September 16, participants from our June Hackathon will be taking over the Decentraland blog and revealing their design and building secrets. This week’s guest blogger is Tak. You can find Tak at Discord or on Slack using @tak.

Hey, I’m Tak-John Cheung and I’m a 3D Artist. In the industry I’m what you call a generalist, in that I pretty much dabble around with all areas of a computer graphics pipeline.

I actually found out about Decentraland from a friend, who suggested I check it out as something that I might be interested in. Turns out he was right. Since then, Decentraland has become my new playground.

In the June Hackathon, I created something called Kabloom Farm, which came second in the Districts category. I’ll be back for the Game Jam on September 16 and gunning for a first prize this time.

Introduction

The Builder provides an easy way for anyone to design a scene without having to worry about creating their own art assets, however its real strength lies in the fact that you can export these scenes for further development, taking advantage of all the tools and utilities available within Decentraland's SDK.

Let’s begin with a simple garden scene created using the Builder. It features a fixed gate which means users will eventually be able to enter the garden without having to leap over the fence. By making use of the new Utils library, we'll quickly be able to have the gate open and close in response to the user's clicks and hopefully by the end of the tutorial, you'll be able to see that anyone can create a simple interactive scene with minimal effort.

Check out the final code for this tutorial here.

The set up

Make sure you have the latest version of the Decentraland SDK installed by running the following command in the terminal:

npm install -g decentraland

You will also need to download the Builder scene files from this link. Once downloaded, extract them to their own folder.

Feel free to use your own Builder scene to follow along. Just download your scene from the Builder itself and you will get a similar .zip file. You can use the steps below as a general guide.

Running the scene

Inside the terminal, run the following command in the directory where we extracted the Builder scene:

dcl start

This will install any missing dependencies and automatically open your default browser to preview the scene. This might take a few seconds to load but once done, you should see a pavilion situated in a small garden that's surrounded by wooden fences.

As mentioned earlier, users can't access the garden without having to jump over the fence so our aim is to have the gate open and close whenever the user clicks on it.

Transforming items

Let’s start by tidying up the gate so that it fills the gaps between the fences. One of the things that we can do in the code, that currently isn't possible in the Builder, is scaling items. To achieve this, we will modify the Transform component of the gate by doing the following:

Open game.ts that's located in the /src directory
Scroll down until you find fencePicketDoor_01 or just perform a search for the term
Modify the Transform component belonging to the gate

TIP: The code from the Builder can be really long as each item in the scene generates a new block of code. To make locating an item in the code easier, you can return to the Builder and hover your mouse cursor over an item you wish to search for within the "Item Catalog" and a tool tip will popup giving you the item’s name, which should be very similar to what’s used in the code, so you can use it as a hint when searching for it.

/// --- Adding Basic Interactivity to gate ---
const fencePicketDoor_01 = new Entity()
fencePicketDoor_01.setParent(scene)
const gltfShape_16 = new GLTFShape('models/FencePicketDoor_01/FencePicketDoor_01.glb')
fencePicketDoor_01.addComponentOrReplace(gltfShape_16)

// Scale and position the gate
const transform_31 = new Transform({
  position: new Vector3(6.65, 0, 0.5),
  rotation: Quaternion.Euler(0, -90, 0),
  scale: new Vector3(1, 1, 1.5)
})
fencePicketDoor_01.addComponentOrReplace(transform_31)
engine.addEntity(fencePicketDoor_01)

You can see in the example above that we adjusted the scale to values that work for us in this scene. If you’re working with your own scene, you may have to play around a bit to see what works for you. In short, the gate’s position and scale has been adjusted to fit the space in between the fences.

We've also replaced the Quaternion rotation values with its Euler equivalent, which will be important later on when it comes to rotating the gate, at least in the sense that we will be able to understand it better conceptually.

Tip: This online tool is a good help when converting from one measurement to the other quaternions.online.

Utils library

It’s nearly time to add some functionality to the Scene and for that we're going to be making use of the new Utils library, which includes a number of pre-built tools that simplifies the process of adding common functionality to your scene.

If you haven't yet exited the preview server, then do that before installing the Utils library, which can be done by running the following command in the terminal, in your scene's project folder:

npm install -g decentraland-ecs-utils

To import the library into the scene's script, add this line at the start of your game.ts file.

import utils from ".../node_modules/decentraland-ecs-utils/index"

We will only be using a few of the available helpers in this library, but if you're interested in learning more then follow this link.

Toggle states

The first component from the Utils library we'll be using is the ToggleComponent, which allows us to switch an entity between two possible states and in doing so, perform a function. The states are specified by the ToggleState, which can either be On or Off. In the case of our gate, we’ll be opening the gate when the ToggleState is On and closing the gate when the ToggleState is Off, so each time the state changes, the gate will rotate to the position corresponding to one of these states.

The ToggleComponent takes in two arguments:

startingState: Starting state of the toggle (On or Off)
onValueChangedCallback: Function to call every time the toggle state changes

Seeing as the gate starts off being closed, we’ll set the startingState to the value ToggleState.Off. For our first test of the toggle, on the second argument we’ll add a very simple function, whenever the state changes, the function will just log a message to the console describing the action we would like to perform. This way we can check that the toggle is working as expected before implementing the action of opening and closing the gate.

NOTE: Whenever you see utils. that’s an indication that we’re accessing a helper from the Utils library.

// Toggle gate to its open / close positions
fencePicketDoor_01.addComponent(
  new utils.ToggleComponent(utils.ToggleState.Off, value => {
    if (value == utils.ToggleState.On) {
      log("Open")
    } else {
      log("Close")
    }
  })
)

Click behaviors

So far nothing happens when you click on the gate, we want it to switch states when clicked. We’ll add an OnClick component to the gate with a function that toggles between the states each time it’s clicked.

// Listen for click on the gate and toggle its state
fencePicketDoor_01.addComponent(new OnClick(event => {
  fencePicketDoor_01.getComponent(utils.ToggleComponent).toggle()
}))

The function that’s executed by the OnClick component changes the ToggleState back and forth between On and Off. Although you won’t be able to see any changes happening visually in the scene, if you open up your browser’s console you should see messages alternating between Open and Close every time you click on the gate.

TIP: Accessing the browser’s console varies between browsers. For Chrome you use the keyboard shortcut CTRL + SHIFT + J (on Windows) or CMD + OPTION + J (on Mac). You can also open it via the menu through View > Developer >JavaScript Console.

Rotating the gate

It's worth noting that the gate has already been rotated by -90 degrees in the y-axis when it was originally placed inside the Builder. Earlier we converted the Quaternion values for the rotation to its Euler equivalent, which now becomes our starting rotation. For our end rotation, we will need to rotate by another -90 degrees so that it opens inwards making its final y-axis value -180 degrees. Let’s define a couple of variables to reflect these values and we’ll call them startRot and endRot.

// Define start and end rotations for the gate
let startRot = Quaternion.Euler(0, -90, 0)
let endRot = Quaternion.Euler(0, -180, 0)

To help us rotate the gate we’re going to be using another component from the Utils library called RotateTransformComponent, which lets us rotate an entity over a period of time from one orientation to another.

The RotateTransformComponent takes in three arguments:

start: Quaternion for the start rotation
end: Quaternion for the end rotation
duration: duration (in seconds) of the rotation

We can now delete the log statements that were used as placeholders and instead have the ToggleComponent add the appropriate RotateTransformComponent to the gate each time it changes state. When the gate opens, we set the start and end rotation arguments as expected with our startRotand endRotbut when the gate closes, the order is reversed, meaning our endRot is now our starting rotation and the startRot is our end rotation.

// Toggle gate to its open / closed positions
fencePicketDoor_01.addComponent(
  new utils.ToggleComponent(utils.ToggleState.Off, value => {
    if (value == utils.ToggleState.On) {
      fencePicketDoor_01.addComponentOrReplace(
        new utils.RotateTransformComponent(startRot, endRot, 0.5)
      )
    } else {
      fencePicketDoor_01.addComponentOrReplace(
        new utils.RotateTransformComponent(endRot, startRot, 0.5)
      )
    }
  })
)

Here we went with a 0.5 second duration for the opening and closing of the gate, which feels fairly snappy but I encourage you to play around with these values so that you can choose whatever feels right.

Finishing touches

You may have spotted a slight issue when you tried to click on the gate again before it finished rotating. Instead of smoothly transitioning between the open and closed states, it snaps back to its starting position and begins rotating again. A simple fix is to only pay attention to clicks on the gate done after it has finished rotating. This can be done by comparing the gate’s y-axis rotation to see if it matches either startRot or endRot.

TIP: It’s sometimes useful to add an intermediate variable. Although not necessary, it can help shorten your code as well as making it more readable.

// Listen for click on the gate and toggle its state
fencePicketDoor_01.addComponent(
  new OnClick(event => {
    // Adding an intermediate variable
    let doorRotY = fencePicketDoor_01.getComponent(Transform).rotation.y

    // Check if gate is at its start or end positions before toggling
    if (doorRotY == startRot.y || doorRotY == endRot.y)
      fencePicketDoor_01.getComponent(utils.ToggleComponent).toggle()
  })
)

Final thoughts

Try running the Scene. Everything should now be working as intended. If you were just reading along and would now like to explore the Scene then you can find it here.

Using the Builder to navigate around and position items in your scene is a lot more intuitive than doing it purely by code. Hopefully this guide has shown you the possibilities when both the Builder and the SDK are used together and how even a little interactivity can go a long way in adding interest to your Scene.

In the near future, Builder assets will be optimized to load more quickly inside of Decentraland, which provides another benefit to those who wish to develop their scenes in conjunction with the Builder.

Let the games begin

The Decentraland Game Jam offers the perfect opportunity to play around with the SDK. Having participated in the June Hackathon, I can assure you that it’s one of the best ways to learn, not just because you get to build something but because you do it alongside other community members.

I’ve already signed up for the September 16 kick-off and I look forward to seeing what you guys build.

See you in the Metaverse!

References

Adding a UI to your Decentraland Scene - The steps to a basic yet dynamic in-scene interface

Decentraland — Tue, 20 Aug 2019 15:00:46 +0000

In the lead up to our next Game Jam, commencing September 16, participants from our June Hackathon will be taking over the Decentraland blog and revealing their design and building secrets. This week’s guest blogger is community member, surz. You can find surz at Discord or on Slack using @surz.

I found out about Decentraland in 2018 and got interested in the clean, low poly design that the project adopted. A year later, I joined the Creator Contest and got more involved. The Builder is a great tool for starting out and developing with pre-made 3D models. Following the Creator Contest, I got an invitation to join the June Hackathon. With some basic knowledge of Javascript, Python and C++ (mainly for scripting) and my interest in 3D modelling, I decided to join the event.

I created a miniature solar system visualization, for educational and art content. The idea was to create a planetarium-type scene that provides basic information about each planet. Beyond the information, I wanted to make it immersive by creating a simple artscape of each planet's surface. In this way, the comparison between the planets and how they differ from our own becomes more authentic and engaging.

You can take a look at the scene in this link

Or check out some screenshots below:

Tutorial

I’d like to share what I used for the UI and how I built it. This tutorial will focus on three sections from my project's UI: the sun, Mercury and the Disclaimer Menu.

The design of the icons and the character that I feature in my UI are both credited to my brother, Jevicho99.

You can download the code, 2D images and 3D models that I use in this
tutorial from this link

If you have any doubts about how UIs work in Decentraland, or about any of the code examples, check out Decentraland's documentation here.

So, let's get started!

Prepare UI assets

We want to have several different UI menus on our scene that can be used at different times. Each of these menus has a static part that isn't clickable and a dynamic part that's clickable.
You can find the images for this tutorial in the github page under the folder /images.
Download these and follow along as you read this tutorial if you want.

Here are the static non-clickable parts of the disclaimer pages:

Here are the static, non-clickable parts of the Sun and Mercury UIs:

Below are the dynamic parts used in both kinds of UIs. These are added to the larger images we just saw, and serve as buttons. Each performs a specific task when clicked.

Close button: Hides all UI elements. This button will be present on all screens.

Next button: Switches between disclaimer screens.

Facts: Displays a little fact about the planet. When clicked again, it switches to another fact.

Compare: Displays information that compares the current planet to Earth.

Artscape: shows a 3D landscape of the surface of the planet.

When put together, the full UI layouts should look like this:

Now that we're happy with the design of our screens, let's implement this in our code.

Add a canvas and container

The first step of creating a UI is adding a canvas component, and a container rectangle to go in it. The rectangle will wrap every UI element that we’ll add in later and make it easier to position them.

// create canvas
const canvas = new UICanvas()
// create container inside canvas
const rect = new UIContainerRect(canvas)
rect.adaptHeight = true
rect.adaptWidth = true
rect.hAlign = 'left'
rect.vAlign = 'top'
rect.opacity = 0.8

Notice that the rectangle has an opacity of 0.8, so all of our UI will be partly transparent.

Add static content

The following code adds the static part of the sun UI.

let sunUITexture = new Texture("images/UI/UI_sun.jpg")
const sunImgScreen = new UIImage(rect, sunUITexture)
sunImgScreen.hAlign = 'left'
sunImgScreen.vAlign = 'top'
sunImgScreen.sourceLeft = 0
sunImgScreen.sourceTop = 0
sunImgScreen.sourceWidth = 1024
sunImgScreen.sourceHeight = 483
sunImgScreen.width = 1024
sunImgScreen.height = 512

Notice that when we’re creating the UIImage component, the first argument is rect. That’s the name of the rectangle we created to wrap all the UI. By passing this argument, we’re making this image a child of that rectangle and positioning it relative to it.

That there are plenty of fields, but most are quite self explanatory. You might be wondering what sourceLeft, sourceTop, sourceWidth, and sourceHeight are there for. These are sometimes used for displaying a cropped section of an image. Since here we’re using the full image, we’re setting them to cover the full dimensions.

If you’re following through, this is a good time to try your scene out with dcl start. You should now see this image appear on the UI.

Since we don’t want this UI to be always on, we’ll add one more line that sets the visible property to false. This will keep the image invisible until its visible value is changed, which we’ll go into later.

sunImgScreen.visible = false

To add the rest of the information screens in our scene, we use almost identical code, except that each has a different image as texture.

Add a close button

The way we’ll add buttons isn’t very different from how we just added our image, our buttons will be images with extra functionality. For example, this code adds a 'close` button to the screen.

typescript let imgCloseBtn = new Texture("images/UI/close.png") const closeBtn = new UIImage(rect, imgCloseBtn) closeBtn.name = 'close_btn' closeBtn.width = '50px' closeBtn.height = '50px' closeBtn.sourceWidth = 112 closeBtn.sourceHeight = 112 closeBtn.positionX = 953 closeBtn.positionY = -5 closeBtn.isPointerBlocker = true closeBtn.onClick = new OnClick(() => { log("Close Button Clicked") canvas.visible = false })

You'll notice the code isn't too different from the static images we added before. The only significant differences are:

The isPointerBlocker property is set to true, that allows you to click on this component, and not on things that might be behind it
The onClick property, that determines what to execute when clicked. In this case, it sets the visibility of the entire UI to false

For the other buttons in our UI, we use pretty much the same code as above, but with different onClick behavior and positioning.

Adding UI text

We want our UI to have text that can be changed dynamically, unlike the fixed text that we imported as part of our images. For this we will create a UIText component. The following code adds a text component that says “WELCOME”. We’ll later make our scene change this text so that it displays different facts about the current planet.

typescript const factTxt = new UIText(rect) factTxt.outlineColor = new Color4(0.7, 1, 0.8, 1) factTxt.value = 'WELCOME' factTxt.fontSize = 22 factTxt.width = 500 factTxt.height = 205 factTxt.positionX = 455 factTxt.positionY = 0 factTxt.color = new Color4(0.7, 1, 0.8, 1) factTxt.textWrapping = true

Grouping UI objects

What we’ve seen so far is probably good enough for many different use cases where you want a simple UI that won’t be changing too much as it’s used. But what if you want to handle several UI screens, each with various components, and that can be easily switched from one to the other? What follows is a solution I came up with that helps scale things easily.

After following the examples we went over to create all the UIImage components needed for each screen, we can list them all in JSON format, grouped based on functionality. These will then be called when switching between screens.

typescript const staticScreenGroup = { "sun": sunImgScreen, "mercury": merImgScreen, "disclaimer1": discImgScreen1, "disclaimer2": discImgScreen2 } const closeMenuGroup = { "closeBtn": closeBtn } const disclaimerMenuGroup = { "nextBtn": nextBtn } const planetMenuGroup = { "factBtn": factBtn, "compareBtn" : compareBtn, "artscapeBtn" : artscapeBtn, "factTxt" : factTxt }

Handling grouped UI objects

To make use of the component list we just created, we'll also write a function that parses the list and makes the required elements visible, depending on the screen.

This function takes three arguments as booleans, each switching different parts of the UI on or off: planetMenu (displays the fact, compare and artscape buttons, and the fact text), disMenu (displays the next button in Disclaimer screens) and closeMenu (displays the close button)

`typescript
function stateDynamicUI(bPlanetMenu: boolean, bDisclaimerMenu: boolean, bCloseMenu: boolean) {

for (let key in planetMenuGroup) {
planetMenuGroup[key].visible = bPlanetMenu
}
for (let key in disclaimerMenuGroup) {
disclaimerMenuGroup[key].visible = bDisclaimerMenu
}
for (let key in closeMenuGroup) {
closeMenuGroup[key].visible = bCloseMenu
}
}
`

What’s missing is selecting which base static image we want to display. We will create a singleton object that includes a function that makes all static UI elements invisible except for the one we want to currently display.

typescript const stateInfoUI = ( function () { let UI_show: UIImage return { changeCurrentUI: function(ui_screen) { if (UI_show) { UI_show.visible = false } UI_show = ui_screen UI_show.visible = true canvas.visible = true }, getCurrentUI: function () { return UI_show } } }())

Opening UIs from in-world objects

We’ll now add a basic 3D menu made out of three 3D boxes into our scene. When each of these boxes is clicked, it will open a different UI, including all the associated elements.

The desired results will look like the GIF below.

Paste the code below to add the 3D entities:

`typescript
// parent entity
const menu3D = new Entity()
engine.addEntity(menu3D)

const sunMenu = new Entity()
sunMenu.addComponent(new BoxShape())
sunMenu.addComponent(new Transform({
position: new Vector3(8, 1.5, 8),
scale: new Vector3(0.1, 0.25, 0.5)
}))
sunMenu.setParent(menu3D)
engine.addEntity(sunMenu)

const mercuryMenu = new Entity()
mercuryMenu.addComponent(new BoxShape())
mercuryMenu.addComponent(new Transform({
position: new Vector3(8, 1, 8),
scale: new Vector3(0.1, 0.25, 0.5)
}))
mercuryMenu.setParent(menu3D)
engine.addEntity(mercuryMenu)

const disclaimerMenu = new Entity()
disclaimerMenu.addComponent(new BoxShape())
disclaimerMenu.addComponent(new Transform({
position: new Vector3(8, 0.5, 8),
scale: new Vector3(0.1, 0.25, 0.5)
}))
disclaimerMenu.setParent(menu3D)
engine.addEntity(disclaimerMenu)

Now we can add an OnClick component to our 3D entities and reference the functions that display UI elements we created in the previous step.

typescript menu_sun.addComponent( new OnClick(e => { log("sun CLICKED") planetMenuGroup.factTxt.value = "WELCOME" stateInfoUI.changeCurrentUI(staticScreenGroup.sun) stateDynamicUI(true, false, true) }))

The code above works for the ‘sun’ menu, for other menus you can use almost the same code with different arguments inside the stateInfoUI.changeCurrentUI() and stateDynamicUI() functions. The disclaimer menu would call the stateDynamicUI function with (true, true, false), to display the “close” and “next” buttons, but not the others.

Now, when you click on the 3D objects, they should open the corresponding UI menu on screen.

Add functionality to the Next button

Now that we can easily switch between each screen with all of its elements, let’s add functionality to some more buttons from our UI screen. We already demonstrated how to give functionality to the Close button, by setting the visibility of the entire UI. To keep the tutorial short, we’ll only show the Next and the Facts buttons.

Below is the OnClick function for the ‘next’ button, which switches between the two disclaimer screens, using the functions we created:

`typescript
nextBtn.onClick = new OnClick(() => {
log("Next Button Clicked")
log(stateInfoUI.getCurrentUI().name)
if (stateInfoUI.getCurrentUI().name == 'disclaimer1_screen') {
stateInfoUI.changeCurrentUI(staticScreenGroup.disclaimer2)
}
else {
stateInfoUI.changeCurrentUI(staticScreenGroup.disclaimer1)
}
})

Add functionality to the Facts button

Now we’ll add functionality to the "Facts" button so that it shows a fact about the current planet:

First, we define an array of strings that lists the facts we want to show.

typescript const sun_facts: string[] = [ "Sun's gravity holds the solar system together, keeping everything from the biggest planets to the smallest particles of debris in its orbit", "At the equator, the Sun spins once about every 25 days, but at its poles the Sun rotates once on its axis every 35 Earth days", "By mass, the Sun is about 70.6 % Hydrogen and 27.4 % Helium", "Sun releases a constant stream of particles and magnetic fields called the solar wind that can slams worlds across the solar system with particles and radiation" ]

Then we’ll create a singleton to handle the switching of UI texts. This object contains a function that loops over the predefined strings and returns one of them.

typescript const FactsModule = (function () { let facts_sun_ind = 0, facts_mer_ind = 0 let fact_arr: string[] let fact_ind: number return { setFact: function (ui_screen) { if (ui_screen.name == "sun_screen") { log("fact for SUN") fact_arr = sun_facts facts_sun_ind = (facts_sun_ind + 1) % sun_facts.length fact_ind = facts_sun_ind return fact_arr[fact_ind] } } } }())

The final step is to call this function from the OnClick property of the ‘Facts’ button, and change the value of the text component in the UI to what this function returns.

typescript factBtn.onClick = new OnClick(() => { log("Fact Button Clicked") let factStr = FactsModule.setFact(stateInfoUI.getCurrentUI()) planetMenuGroup.factTxt.value = factStr })

For the final complete code of the scene, check my GitHub repository for this project.

Some closing words

I find it interesting and challenging that Decentraland provides a platform to create a virtual world governed by the blockchain. As it develops, I would like to explore possible mechanics and use cases inside the platform to create more quality content.

If you have any ideas about how to make the above code more efficient or want to talk about it, please join the discussion and share your thoughts in the #sdk channel of Discord. I’d love to hear your feedback!

And of course, if you are interested in building things, get involved in the GameJam which starts September 16th. Join here and I’ll see you in the Metaverse!

Building Blocks in Decentraland

Decentraland — Sun, 18 Aug 2019 10:27:43 +0000

A simple experiment with in-scene content creation

Hey everyone. Interweaver here. By day I build interactive educational websites, but also have a long-standing interest in online multiplayer Metaverses. This stretches back to a childhood spent chopping trees in RuneScape and pulling all-nighters hacking around as a leet scripter in Second Life.

I encountered Decentraland, like many of us, towards the end of 2017, and was very excited to finally see the dream of a true peer-to-peer, trustless virtual world beginning to be realized. Content creation and community are absolutely at the heart of any Metaverse, and so I jumped at the opportunity to participate in the recent Creator Contest and SDK Hackathon as a way of really diving into DCL’s new building tools.

Playing with blocks

As a community Hackathon participant, I worked on several exciting projects, including an educational recycling game for the EcoGames District. In this blog post I’ll be talking about how I designed and implemented my Decentrablocks project. The idea for this scene was simple: I wanted to be able to intuitively build things while actually standing in the scene, not in a separate Builder or with an external text editor and modeling software (as one does with the SDK). Also, I’m not a 3D artist, so it had to be made entirely of primitive shapes.

In true Hackathon fashion, the scene came together between about 8pm one night and 5am the next morning (on a work day – sigh). The end result was a little rough around the edges, but achieved my objectives. The scene allows you to:

Grab a new block from the pile of various blocks by clicking it
Carry it wherever you want just by moving and looking around
Place a carried block by clicking again
Pick up any placed block by clicking it
Delete a block by placing it on a symbol on the floor
Pick the color of new blocks
Choose the block-moving mode:
- Carry Mode, where the block tries to stay a fixed distance away from you
- Ray Mode, where the block goes to the nearest solid object along your line of sight

To make lining the blocks up easy, they snap to a half-meter grid, and they are prevented from intersecting, just like real blocks 😁.

Overall, the scene has a bit of a Minecraft feel, but where most of the blocks are bigger than the grid size, and are carried around in front of you rather than in an inventory. Per my main goal, you can totally build some fun things without ever leaving the scene.

Feel free to try it out for yourself!

Implementing Decentrablocks

Okay, now that the introductions are out of the way, let’s talk about how it works! If you want to check out the code yourself, it’s all on GitHub. Note: To keep the math easy to visualize, I’ll sometimes only describe the 2D case, but the 3D case is equivalent.

Free Carry

The core mechanic for the scene is being able to pick something up, carry it around, and put it back down again with some degree of precision. Now, making a good system for positioning things in 3D can be tricky. Fortunately, walking and looking around in Decentraland already provides a significant degree of spatial control, and so I decided to leverage that to make carrying objects easy. The very first part of the project I implemented was free carry. Simply having an object stay exactly where it is, relative to your screen, while you walk around and rotate the camera, without any snapping or intersection prevention or anything.

The math behind this is pretty simple, once you understand the difference between world space and local space.

World space is the global X, Y, Z coordinate system. In Decentraland scenes, +X goes in the direction of increasing parcel X coordinates on the Genesis City map, +Y goes in the vertical upward direction, and +Z goes in the direction of increasing parcel Y coordinates on the map. (I think that this is confusing, and wish they had chosen to align the Y coordinates and have Z be vertical, but it is what it is). When you describe an object's location according to this coordinate system, you are giving its location in world space.

Local space, by contrast, is a coordinate system relative to some transform (the combination of position, rotation, and scale). It still has X, Y, Z coordinates and you can describe the location of objects in local space by giving those three numbers, just like in world space. The actual values will be different though. You usually talk about the local space of a particular object; for example, user space is the local space of a given user. It's the space where the user's camera is at the origin <0, 0, 0>, the +X direction is along the user's line of sight, the +Y direction is the upwards direction on the user's screen, and distance is the same as in world space (scale = 1).

With this understanding, free carry is really easy to define. If ObjPosWorld is the position of the object you want to carry in world space (bold denotes a vector), and ObjPosUser is its position in user space, you simply want ObjPosUser to remain constant while the object is being carried! This will result in the object not appearing to move on the user’s screen while they are moving around. Note that ObjPosWorld will not be constant if the user moves around. Our goal here is to calculate ObjPosWorld, so that we can update it on every frame using a System, and therefore keep ObjPosUser constant. This will involve transforming between world space and user space (in both directions).

When the object is first picked up, we know ObjPosWorld and want to use it to get ObjPosUser. The math is pretty simple. Let’s take UserPos to be the position of the user (in world space), and UserRot to be a quaternion that represents the rotation of their camera. Quaternions sound scarier than they are – you can simply think of them as a set of four numbers that can represent any possible rotation in 3D.

If you multiply a vector by a quaternion, it essentially gives you a new vector that is the old vector, but rotated by the rotation that the quaternion represents. You can also take the inverse or conjugate of a quaternion, and get a new quaternion that represents the opposite rotation of the old one. These pieces of information are all we need to know to transform from a position in world space (ObjPosWorld) to a position in user space (ObjPosUser):

ObjPosUser = (ObjPosWorld - UserPos) * conjugate(UserRot)

Basically, you’re subtracting the user’s position from the object’s position, and then reversing the user’s rotation from the object’s position. The end result is the local user space coordinates of the object.

As a programmer, I am always frustrated when someone writes out a bunch of math for an algorithm and leaves the code as an exercise for the reader, so let’s avoid that 😁. Here’s what the above equation looks like in TypeScript, using the Decentraland SDK, and where entity is the object you’re carrying:

// Run this once, when you first pick up the object.
let objPosWorld = entity.getComponent(Transform).position

const objPosUser = objPosWorld
  .subtract(Camera.instance.position)              // Subtract UserPos
  .rotate(Camera.instance.rotation.conjugate())    // Unrotate by UserRot

Now that we have our constant ObjPosUser, we just need to use it, along with the latest UserPos and UserRot values, to recalculate ObjPosWorld at each frame and move the carried object there. Remember that UserPos and UserRot change when the user moves around. This is the same equation as above, but solved for ObjPosWorld instead of ObjPosUser:

ObjPosWorld = (ObjPosUser * UserRot) + UserPos

Or, in code:

// Run this once per frame, in order to move the object as the player moves.
let objPosWorld = objPosUser
  .clone()                           // (Clone stops the .rotate from changing objPosUser)
  .rotate(Camera.instance.rotation)  // Rotate by UserRot
  .add(Camera.instance.position)     // Add UserPos

entity.getComponent(Transform).position = objPosWorld

Also, as a visual thinker, I am always frustrated when someone writes out a bunch of words and leaves drawing pictures as an exercise for the reader, so let’s avoid that too. Here’s a drawing of the situation (in this case, the user happens to be looking straight at the object):

Well that pretty much covers free carry. I’ve made a simple, dependency-free implementation of this as a Component and System pair available on my GitHub, along with a tiny example game.ts showing its use.

Aligning with Snap-to

A design decision I made for this scene was to snap block locations to half-meter increments. This makes aligning blocks a lot easier. My initial implementation of this was basically as simple as calling Math.round() on each of the components of the objPosWorld variable before actually updating the object’s position, but multiplied by 2 first, and then divided by 2 after, to round to the nearest 0.5m instead of 1m:

objPosWorld.set(
  Math.round(objPosWorld.x * 2) / 2,
  Math.round(objPosWorld.y * 2) / 2,
  Math.round(objPosWorld.z * 2) / 2
)

Now users can carry blocks around and their positions are discrete for easy placement! But blocks can still be moved inside of each other – a pretty unrealistic situation.

Detecting Overlaps (or, The Grid)

The next challenge was to detect when a position is already occupied, and prevent moving a block there. A natural way to accomplish this was to have a big multidimensional array that I’ll call The Grid, where every element represents one 0.5m-cubed cell in the single-parcel scene (so a 32x32x32 array.) Then you simply:

Check each element of The Grid that a block would occupy before moving it
If they’re all free, move the block and mark them as occupied in The Grid
If the user moves the block away again, mark them as unoccupied again
If they’re not all free, we’ll need to resolve the overlap somehow (see below)

A nice side effect of this mechanism is that when we check our array indices to make sure they’re in bounds (between 0 and 31) before reading from the array, if they’re not, we can also prevent overlaps in those cases, and avoid the block going underground or outside our parcel’s boundaries.

Resolving Overlaps

So what do you do when the user tries to move a block while carrying it, prompting an overlap? Simply not moving the block would be one option, but would feel unresponsive to the user. A better solution would be to move the block to a different unoccupied spot that’s still along the user’s line of sight. This means that the block would appear to move as expected (remaining directly in front of the user), but also no longer overlap with another block or the edge of the scene.

Rasterizing with the Bresenham Algorithm

To achieve this, I needed some way to determine all the possible positions along the user’s line of sight that the block could be in. After a few minutes of Googling, I came across the Bresenham 3D algorithm, which rasterizes a line segment between two integer points in 3D space; that is to say, it converts the line segment into a set of voxels that are all along that line segment. There are definitely other algorithms I could have used, but this one served my purpose well enough. You can check out the repo to see my TypeScript implementation.

Using the Rasterization

With the set of voxels along the user’s line of sight in hand, we can now resolve overlaps. If you’ll recall, there are two different block-moving modes to account for, Carry Mode and Ray Mode.

In Carry Mode, the block tries to stay at a fixed distance from you as you walk and look around. When an overlap is detected, simply iterate through the voxel set, using The Grid to check for overlaps at each spot, starting with the farthest voxel (the carry position) and moving inwards. The first available spot you encounter is where you move the block. This makes sure the block is as close as possible to the carry position.

In Ray Mode, the block goes as far as it can without hitting anything (another block or the edge of the scene), and then stops there. So simply iterate through the voxel set, again using The Grid to check for overlaps, but this time starting with the nearest voxel (the user’s position) and moving outwards. The last available spot before the first unavailable spot you encounter is where you move the block. This makes sure the block is right in front of the first solid object along the user’s line of sight.

In Conclusion

And that’s pretty much it. We can carry blocks naturally by walking and looking around, they snap to a grid for easy placement, and they can’t intersect with each other. For a nine-hour project, I was pretty happy with the outcome. It certainly showed me that while Decentraland’s SDK is still in the early stages of its evolution, you can already accomplish a great deal with it.

I’m looking forward to the many new features coming out soon! In particular, Decentrablocks would have been a lot less buggy and easier to write if global click events had been available, instead of always needing to click on an actual object, and this feature is planned for SDK v6.3 or earlier.

Going forward, I look forward to being an active member of the Decentraland scene-building community. There’s another Decentraland Game Jam coming up in September, and after my experience with this past Hackathon, starting from zero knowledge of the SDK, I can confirm that they’re a great opportunity to familiarize yourself with it while working with some really skilled creators!

I plan on participating, and if you’re at all interested in building content for a decentralized online world, I hope you’ll join me.

See you in the Metaverse!

Decentraland Game Jam, $250,000 USD in prizes, September 16-30

Decentraland — Thu, 08 Aug 2019 13:27:35 +0000

A two-week online event, building interactive 3D content for Decentraland – the first blockchain-based virtual world.

Blockchain is transforming the gaming industry, adopted by established companies such as Samsung, Ubisoft, HTC and Kakao Games.

The blockchain allows for unprecedented mechanics in gaming, such as

earn-to-play, allowing players to monetize their skills;
true ownership of virtual goods, which lets you trade what you own in global open markets;

verified scarcity and provable fairness, meaning you can verify the exact supply and rules that affect your items and the games you play;

and interoperability of virtual items, so that the skins you purchased for one game can be used in a different franchise
Sign up at gamejam.decentraland.org

For more details, read the Game Jam Survival Guide