Objects and scenes
Everything in your project is made of objects, and scenes decide when those objects appear. Here is how objects, components and scenes fit together.
The editor says object. The engine and the scripting API say entity. These docs use entity only when they talk about code.
What an object is made of
An object holds two kinds of things:
- Components are its settings. They decide what the object is: its name, where it is, what it looks like, what it reacts to. An object can have only one component of each kind.
- Child objects are other objects placed inside it. Each child has its own components.
Here is a lamp with four components:
Object "Lamp"
├── Meta its name, whether it is on, whether it is visible
├── Transform where it is, how it is turned, how big it is
├── Model which 3D model to draw
└── Events what it reacts to
These are the engine's names. The inspector shows Meta as General.
Here is the same lamp with a bulb inside it. The bulb is a separate object with its own components:
Object "Lamp"
└── Object "Bulb" ← a separate object
├── Transform ← with its own components
└── Light
A real scene looks like this. Components are listed after each name, and children are indented under their parent:
Object "Living room" ◆ Anchor ← a scene: it has an anchor
│
├── Object "Lamp" ◆ Transform ◆ Model ◆ Events
│ └── Object "Bulb" ◆ Transform ◆ Light
│
└── Object "Table" ◆ Transform ◆ Model ◆ RigidBody ◆ Collider
Everything in this picture is an object. Its components decide whether it is a scene, a lamp or a physics body.
Use a component for a property of this object. Use a child object for a separate thing that should move with it.
Moving the lamp moves the bulb, because the bulb is inside the lamp. Removing the lamp's model component does not remove the bulb.
Build objects from components
There is no list of object types to choose from. You combine components to get what you need:
| Give an object… | …and you get |
|---|---|
| geometry + material | a visible shape |
| a model reference | an imported 3D model |
| a light component | a light |
| a text component | a piece of text |
| a rigid body + a collider | something physics can move |
| an anchor | a scene |
| a script or a patch | something with behaviour |
For example, here is how you make a bouncing ball:
- Add a sphere geometry and a material. Now you can see the ball.
- Add a rigid body and a collider. Now it falls and bounces.
- Add a script. Now it can do something when it lands.
Each component adds one ability. Remove the component, and the ability goes with it.
Scenes, objects and space-level logic
You will meet three kinds of objects. They feel different, but they are all objects with different components:
| What it is | Has | Does not have |
|---|---|---|
| A scene | an anchor, and children | a transform |
| An ordinary object | a transform, plus whatever it needs | an anchor |
| Space-level behaviour | a script or a patch, and no parent | a transform, an anchor |
A scene has no transform because its position comes from the real-world thing it is anchored to. Space-level behaviour has no transform because it is not placed in the world. It is only logic that keeps running.
Need three materials on one model? Use the slots inside its material component. Need two of anything else? Use child objects. A lamp with two bulbs is a lamp object with two children.
Every object also has a name, so you can find it, and can have a parent: the object it sits inside.
Enabled and visible
These two switches look alike in the inspector, but they do different things.
- Disabled takes the object out of the experience. It is not drawn and cannot be tapped. Its scripts stop and its events do not fire. It is as if the object were not there.
- Invisible only stops the object from being drawn and tapped. It is still there: its scripts keep running, and physics still collides with it if it has a collider (see what counts as solid).
For example:
- An invisible wall that still blocks the player: make it invisible.
- A prize that appears later: keep it disabled until you need it.
Parents and children
Objects form a tree. When you move a parent, its children move with it and keep their place relative to it. This is how you build anything with parts: a car body with four wheels inside it moves as one car.
Its children are deleted too, and their children. To keep one, drag it out first.
You cannot put an object inside anything that is already inside it. The editor does not allow it.
A scene is the top of its tree. Every object you add to a scene sits inside the scene object, directly or inside another object. Any other object with no parent is not in any scene. It belongs to the whole space, as described in Logic for the whole space below.
Scenes and anchors
A scene is an object with an anchor. The anchor decides when the scene appears:
| Anchor | Your scene appears when… |
|---|---|
image | the camera recognises a printed picture |
qr | a QR code is scanned |
geo | the visitor is at a place |
face | a face is detected |
surface | the visitor places it on a floor, wall, ceiling or table |
panorama | a 360° environment opens |
3d | straight away: a normal 3D scene, with no AR |
VPS places content using a scanned map of a real location. It is not a separate anchor type. Set up a surface scene, then switch VPS on.
Several scenes on one marker
Scenes with the same trigger (the same image, the same QR code or the same location) form a group. Only one scene in a group shows at a time.
Use this to tell a story. The same poster opens the first chapter, and later the second. You only switch which scene in the group is active.
The editor adds two events to show and hide a scene: on-detect shows it and on-lost hides
it. They are ordinary events, so you can change them. For example, you can keep content on
screen after the marker leaves the camera view. Visitors usually prefer this, because otherwise
the content disappears as soon as their hand shakes.
Surface scene settings
Surface scenes have three separate settings. They are easy to mix up:
- Which surfaces to accept: floor, wall, ceiling, table.
- How content is placed: automatically on a detected surface, or where the visitor taps.
- Which tracking engine to use: this matters only on the web. In the native apps, it has no effect.
Logic for the whole space
An object with behaviour and no parent does not belong to any scene. It belongs to the whole space. It keeps running while scenes come and go, and it hears every event anywhere in the space.
Use it for a score counter, a global controller, or to remember what the visitor picked. A script inside a scene stops as soon as that scene stops.
How the editor labels objects
The editor shows labels like model, primitive or text. It picks the label from the object's components, checking them in this order:
splat reference → splat
model + skinning → animated model
model → static model
video → video ← checked before geometry
text → text
audio → audio
light → light
geometry → primitive
anything else → object
So a plane that plays a video is labelled video, not primitive. You can edit material and geometry only on primitives and static models.
Next: Components — what each component controls.