Troubleshooting
Most problems in this engine have the same handful of causes. If something is not behaving, there is a good chance it is on this page — start at the top, since the first two account for most of it.
"It works in preview but not in the editor"
It is not supposed to. The editor does not run your logic — no scripts, no patches, no physics, no timers, no proximity triggers. It draws and edits the scene.
That is deliberate: an animation playing while you author would fight you, and a timer would write changes into your project. Use Preview to see behaviour.
"My script does not run"
Work down this list:
- the object is enabled, and so is everything above it in the hierarchy;
- its scene is active — in an AR scene, that means the marker has been detected;
- the script component is enabled;
- you are in preview or a publication, not the editor.
A script also restarts when you change one of its inspector properties, so a stray edit can look like a crash.
"I change a component and it snaps back"
Two likely causes.
A state is active. While a state is selected, changes to that object are recorded into the state. Switching states then restores the snapshot. If you meant to change the object itself, deselect the state first.
Something else owns that property every frame. A timeline bar, a physics body, or a look-at all write continuously and will overwrite you. See the next item.
"My animation fights another animation"
Two mechanisms are writing to the same object. The timeline writes every frame and always wins against a transition.
Pick one mechanism per object. If you need a transition on something the timeline drives, move it to a child object, or animate it on the timeline instead. See Animation.
"My material change from a script does nothing"
A material is a list of slots, so material.update({ color }) writes a field that does not
exist at that level. Write the slot:
material.update({
materials: [{ ...material.$data.materials[0], color: '#ff0000' }],
});
The same trap applies to any nested value: update replaces what you hand it, so spread what
you want to keep.
"My object falls through the floor" / "the model is not solid"
An imported 3D model has no collision shape unless you give it a collider. Add one — a box or capsule is usually right.
Also check that the floor itself has a rigid body and a collider. Bare decorative geometry is scenery, and things pass through it. See Physics.
"I set the position of a physics object and it ignores me"
Physics owns the position of a dynamic body and rewrites it every step. Use teleport for
placing it, and impulses or forces for moving it.
"My UI is missing from the screenshot"
Cards are drawn in front of the 3D view, and a capture of the 3D view does not include them. Check UI in preview.
"Rotation values do not match"
Everything you can see (the inspector, patch node ports) is in degrees. Values read or written from a script are in radians. Convert at the boundary.
"Nothing happens when I press the key"
Check the casing: triggers are written on-click, steps play_animation. A mistyped name does
not error, it simply never matches.
If the event refers to a project binding, make sure that binding still exists — a reference to a removed binding does not fall back to "any key", it stops firing.
"It fires twice"
The same trigger is handled in two places — an event and a script, or an event and a patch. Pick one. See Events.
"The object appears a moment late"
Resources load while the scene is already running, so models, textures and text arrive shortly after the scene opens. For content that must be present at the first frame, avoid depending on a large download, or keep the scene hidden until it is ready.
"There is no event for 'animation finished'"
There is not one, in any of the animation mechanisms. Use a wait step of the same length, or track elapsed time in a script.
"My undo removed someone else's change"
Undo history is your own and strictly linear — it does not know a collaborator edited the same object in between. On a shared scene, prefer fixing a mistake forward over undoing your way back through it.
Still stuck?
If none of these fit, the two places most likely to have your answer are the reference tables (every setting, generated from the engine) and Objects and scenes, which explains the model the rest of this section assumes.