frame academy

Learn how to create immersive, cross-platform webxr sites.

project #3: relative position + grouping entities

a few helpful notes about This project

Project goals

I hope that by going through this small project, you will learn:

part 1: meeting the relatives

setup your project

Each part of the project has a video at the top where I guide you through the project. The video is the best place to start, but I also break down the content below so that you can follow along step by step.

To code our projects, we're going to use something called Glitch, a sweet tool that gives you a way to write your code from a web browser. Glitch also hosts your website for you, letting you see the results of your code immediately! If you did Project 1, you can keep building on your existing project, but if you want to make a new one use this button:

start your own project on Glitch

You can also "Remix" any of the code samples you see throughout the project by using the "Remix to Edit" button you'll see next to them. This lets you make a copy of my code that you can edit, build upon, and make your own. You can also always copy and paste my code into your own project..

To save your Glitch project so you can keep working on it whenever you want, you have to sign in to Glitch with a free account. The sign in button is on the top right of Glitch.

Reminder: Have a question or idea? Check out the Frame Academy Community on Discord.

parents, children, and siblings

In Project #1, we learned a little bit about position. To review the main points: you set position with three numbers. The first number represents the x axis (where the element is positioned to the right or the left), the second number represents the y axis (where the element is positioned up or down), and the third number represents the z axis (where the element is positioned forwards or backwards). In my starter project, I'm simply going to throw a few box entities in my scene and give them each a position, color, and rotation. I'm also going to put a background component on the scene element, and set its color property to a nice blue color I found.

Take a peek at the project I'm starting with:

As you can see, our a-box entities are inside our a-scene entity. When an entity is inside of another one, it's called a child.

As you might have guessed, an entity that has a child inside of it is called a parent. In this project, the scene is the parent, and the boxes are its children.

Our scene has more than one box inside of it, so these boxes are siblings of each other - after all, they have the same parent! I know this family lingo is a bit weird when we're talking about HTML, but it's a decent way of understanding the relationship between the entities and at least it gives us a standard way to talk about it.

Now, let's mix it up. I'm going to nest the two bottom boxes inside the first box. I do this by putting them inside the opening and closing tags of the first box. Now, although the first box is still a child of the scene, it's also the parent of the other two boxes!

relative position

Woah! Now the scene might not look as you expect it to. Why did the two child boxes change position? Why are they now higher up than the first box, and farther away?

This gets into the concept of relative position. If one entity is the parent of another entity, it becomes the origin point for all of its children entities. This means that instead of using the scene's origin point (0, 0, 0) to determine its position, the child entity will use the position of its parent entity. Let's make sense of this.

Notice how all of the boxes have a vertical position (the second value in the position property) of 1. Because the second and third boxes are children of the first box, though, their position will be relative to the position of the first box. So if the vertical position of the second and third boxes is 1, they will be 1 above the position of their parent, the first box. So that's why we see the second and third box are higher than the first box now. Their position is determined relative to the position of their parent.

This is also why the children boxes are farther back. All of the boxes have a z value (the third number in the position property) of -3, but the second and third box will now be -3 away from their parent, the first box, putting them even farther in front of the camera than the first box.

Now, you might be wondering: isn't the y value of the child boxes really 2 then? If the parent box has a y value of 1, and the other boxes are positioned 1 above the parent, then the real y position of the other boxes must be 2. Same with the z value: if the parent box has a z value of -3, and the children boxes are -3 away from the parent box, then isn't their z value really -6?

You would be right! The position that you're figuring out there, though, is called the global position. Global position is the true position of an entity relative to the scene. The position of the child boxes you see in the code is called local position.

looking at parents + children in a-frame inspector

A good place to help you understand the relationship between parent entities and children is in the A-Frame Inspector. In the GIF above, I visited my immersive web site and pressed control-alt-i to open up the Inspector.

In the entity list on the left, any entity that is a parent will have a little arrow next to it that you can click to expand out and see all of its children. When I expand out my parent box, I see my two other boxes appear in the list. If you move around the parent entity, notice that the children move with it. When I rotate the parent, the children also change position to account for the new orientation of the parent. If I scale the parent up in size, the children scale too.

Why would you make one entity the parent of another? This is a very handy way to group entities that you know need to be linked together. Instead of changing all of their positions in your code or in inspector, you can just change the parent entity! Later on, when we make our WebXR sites interactive, you'll see how helpful it can be to strategically group your entities together.

Tip: Remember that you can open up the Inspector on any WebXR site made with A-Frame, not just your own!

🔥 challenge #1 🔥

In your own project, bring in a few entities (shapes, images, models, anything you want), and nest some entities inside of others so that you have some parent-child relationships. View your site by clicking the "show live" button on Glitch and make sure that you've nested them properly and there aren't any errors in your code.

With your web site open, open up the A-Frame Inspector with control-alt-i and experiment with moving, rotating, or scaling the parent entities and then the child entities so that you can see how they relate. Moving the parent around should change the position of its children, but moving a child won't move the position of its parent.

Move on to part 2 >
keep it in the family