Objects and scenes
Everything in your project is built from two ideas: things made of components, and scenes that decide when those things appear. This page covers both.
The editor calls them objects, because that is what they look like on screen. The engine and the scripting API call them entities. There is no difference — this page uses entity where the distinction from components matters, and object everywhere else.
Two relationships, and they are not the same
Almost every misunderstanding of this engine comes from mixing up two things that both look like "inside".
An entity is MADE OF components. Components are not children — they are the parts that decide what the entity is. One of each kind, at most.
Entity "Lamp"
├── Meta its name, whether it is on, whether it is visible
├── Transform where it is, how it is turned, how big
├── Model which 3D model to draw
└── Events what it reacts to
An entity can CONTAIN other entities. Those are children, and they are entities in their own right — each with its own components.
Entity "Lamp"
└── Entity "Bulb" ← a separate entity…
├── Transform ← …with its own components
└── Light
Put together, a real scene looks like this — components on the left of each entity, children indented under it:
Entity "Living room" ◆ Anchor ← this one is a SCENE: it has an anchor
│
├── Entity "Lamp" ◆ Transform ◆ Model ◆ Events
│ └── Entity "Bulb" ◆ Transform ◆ Light
│
└── Entity "Table" ◆ Transform ◆ Model ◆ RigidBody ◆ Collider
Everything in that picture is the same kind of thing: an entity. What makes one a scene, one a lamp and one a physics body is only which components it carries.
Moving the lamp moves the bulb, because the bulb is inside it. Removing the lamp's model component does not remove the bulb — that is composition, not containment.
If you ever find yourself asking "should this be a component or a child object?", the answer is: a component when it is an aspect of this thing, a child when it is a separate thing that should move with it.
An entity is whatever its components say
There is no menu of object types to pick from. You build what you need by combining components:
| Give an entity… | …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 |
Say you want a bouncing ball. Start with a sphere geometry and a material — now you can see it. Add a rigid body and a collider, now it falls and bounces. Add a script, now it does something when it lands. Each component adds one capability, and removing it takes that capability away again.
The three shapes you will meet
The same entity model produces three things that feel different but are not:
| 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 it has nowhere to be: its position comes from the real-world thing it is anchored to. A space-level carrier has none because it is not in the world at all — it is just logic that keeps running.
Need three materials on one model? Use the slots inside its single material component. Need two of anything else? Use child entities — a lamp with two bulbs is a lamp entity with two children.
Every entity also has a name (how you find it) and a parent.
Enabled and visible are different
These two look alike in the inspector and behave nothing alike.
Disabled takes the entity out of the running experience. Not drawn, not tappable, scripts stopped, events silent. As if it were not there.
Invisible only stops it being drawn and tapped. It is still there: scripts keep running, physics keeps colliding.
So: an invisible wall that still blocks the player? Invisible. A prize that appears later? Disabled until you need it.
Parents and children
Entities form a tree. Move a parent and its children come along, keeping their positions relative to it — which is how you build anything with parts. A car body with four wheels parented to it moves as one car.
An entity with no parent sits at the root of its scene.
Children go too, and their children. If you want to keep one, drag it out first.
You cannot make an entity a child of its own descendant — the editor refuses rather than tangling the tree.
Scenes and anchors
A scene is an entity with an anchor on it, and the anchor answers one question: when should this appear?
| 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, no AR involved |
Positioning against a scanned map of a real location is an option on the surface anchor, not a separate type. Set up a surface scene, then switch VPS on.
Several scenes, one marker
Scenes sharing the same trigger (the same image, the same QR code, the same location) form a group, and only one scene in a group shows at a time.
That is how a story works: the same poster opens the first chapter, and later opens the second, because you switched which scene in the group is active.
Showing and hiding on detection is just a pair of events the editor sets up for you
(on-detect shows, on-lost hides). They are ordinary events, so you can change them — for
instance to keep content on screen after the marker leaves the frame, which visitors usually
prefer to content that vanishes the moment their hand shakes.
Surface scenes have three separate settings
They get mixed up a lot, so here they are side by side:
- 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 — only relevant on the web; native apps always use the platform's own.
Behaviour that outlives a scene
Give an entity behaviour and no parent, and it stops belonging to any one scene — it belongs to the whole space. It keeps running while scenes come and go, and it hears every event that happens anywhere.
That is where a score counter, a global controller, or "remember what the visitor picked" belongs. A script inside a scene stops the moment that scene does.
How the editor labels objects
You will see labels like model, primitive, text. The editor works out which by checking what the object carries, 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
This explains a small surprise: a plane playing a video is labelled video, not primitive. It also explains why material and geometry can only be edited on primitives and static models.
Next: Components — what each one actually controls.