Where scripts live
You can attach a script to an object, a scene, a space or the whole project. The level you pick decides how long the script runs, and this often matters more than the code.
| Attached to | Runs while | Stops when |
|---|---|---|
| An object | the object is on screen | it is hidden, disabled or deleted |
| A scene | the scene is active | the visitor leaves the scene |
| A space | the visitor is in the space | they go to another space |
| The project | always, in every space | they leave |
On an object
This is the default. Use it for behaviour that belongs to one thing: a door that opens, an enemy that chases, a button that reacts.
ctx.entity is that object. The script stops as soon as the object does, so you never have to
clean up after an object that no longer exists.
On a scene
Add it in the scene's Scripts section. Use it for logic about the whole scene: playing an intro in order, counting how many collectables are left, deciding when the visitor can move on.
It starts when the scene becomes active and stops when the scene is no longer active. In an AR project, that means it starts when the scene is detected.
On a space
Add it in the space's Scripts section. A space script keeps running when the scene changes. Use it for a score across three scenes, a timer for the whole visit, or logic that picks the next scene.
A tap or another event on an object reaches the space script too: it goes from the object, to the scene, to the space.
On the project
Add it in the project settings. The script is added to every space, so it is there wherever the visitor goes.
Use it for things that must last from one space to the next: the visitor's choices, overall progress, analytics.
What keeps its value
| Stored in | After a scene change | After a space change | After a reload |
|---|---|---|---|
a variable in init | only if the script is still running | only if the script is still running | no |
ctx.store | yes | no | no |
| a global | yes | yes | no |
a @space: global | yes | no — each space keeps its own, on purpose | no |
Nothing is kept: not store, not globals. If you need a value next time, send it to a place of
your own while the visitor is still on the page.
Pick a level
Ask yourself: what is the smallest thing this logic is about?
- One object — put the script on the object.
- This scene — put it on the scene.
- The whole visit — put it on the space. If there are several spaces, put it on the project.
Do not put everything on the project "just in case". A project script cannot count on any particular scene being loaded. It fills up with checks that a script on an object never needs.
Patches work the same way
You can attach a patch at any of these levels too, and it runs for the same time. A patch on the project is the usual way to build logic for the whole project without writing code.
Next: The ctx API — everything a script can do
with ctx.