Name what your program creates

What you'll learn#

You will write a small BASIC program, watch the Scene Graph stay empty while it clearly works, and then make each object appear by naming it. By the end you will know why the tree hides most of what a program builds, and how to choose what it shows.

Before you start#

• Engine is a backed module. Inkwell, Vectra and PDF Studio are the three free ones.
• No prior tutorial needed. Everything below is one script.
• Keep the Scene Graph panel open, next to the viewport. It is the point of the exercise.

Steps#

1. Open Engine, start an empty scene, and open the script editor. Paste this and press Play:

   image = LoadImage("hero.png")
   sprite = CreateSprite(image)
   SpritePosition(sprite, 100.0, 120.0)
   CreatePointLight(1, 0.0, 5.0, 0.0, 10.0, 255, 255, 255)
   DO
     Sync()
   LOOP
   

2. Look at the Scene Graph. The sprite is on screen, the light is lit, and the tree shows nothing. This is not a bug, and it is the whole lesson.

   Tip: the panel shows a count of unnamed objects. That number is your program's output that the tree deliberately did not list.

3. Name the sprite. Add one line after SpritePosition, and press Play again:

   SpriteName(sprite, "player")
   

   player appears in the tree. Nothing else changed on screen: naming does not create, move or draw anything. It publishes.

4. Name the light too, with the command that came with this idea:

   LightName(1, "sun")
   

   Two entries now. Click one: the inspector follows, exactly as it would for an object you had placed by hand.

5. Add particles and name them, so you can see that the rule is not about sprites:

   CreateParticles(1, 200.0, 200.0)
   ParticlesName(1, "smoke")
   

6. Now remove the three naming lines and press Play. The scene is identical, the tree is empty again, and the unnamed count is back to three.

   Warning: a name is not an id. SpriteName(sprite, "player") labels the sprite whose id is in sprite; it does not let you find it later by that label. The id stays your handle.

Result#

You can decide what your program shows. A prop, a light and an emitter appear under the names you chose; the hundreds of technical objects a real program builds stay out of the way.

Why the rule exists#

A classic BASIC program creates objects constantly: a sprite per bullet, a text per score digit, an image per tile. Listing all of them would make the Scene Graph unreadable within seconds, and the three objects you actually care about would be lost in the noise.

So the tree does not show everything and hide the rest by guessing. It shows what you named, and it counts the rest so nothing disappears silently. The filter is yours, not the engine's.

Which objects can be named#

Sounds, images, memblocks and fonts have no line in the Scene Graph: they are resources, not scene objects, and naming them would show nothing anywhere.

Going further#

• The rest of the dialect: the BASIC language.
• Every naming command with its parameters: the Studio family.