Entities, components and levels

Entities form a tree

Every entityentity: A thing in the game world: a player, a ball, a trigger, an empty marker. On its own it only has a name and a place in the hierarchy; components give it behaviour. has at most one parent and any number of children. A child’s position is relative to its parent, so moving a parent carries its children along: a pad’s glow, its trigger and its landing point all move when you move the pad.

• hideout_masterthe level
  • Teleportersa group
    • tp_pair_plazaa placed prefab
      • padtransformmodel
      • triggertransformbox_triggerteleport_pad← your script
        • burst_fxtransformeffect
      • arrivaltransform
    • tp_pair_garageanother placement of the same prefab

Part of a level. The teleport_pad script is on the trigger entity; its sibling arrival, its child burst_fx and its partner pad are all reachable from there.

From the entity your script is on you can move in every direction:

To reach	Use
Your own entity	$entity.get()
Its parent	$entity.get_parent(e)
A child or descendant by name	$entity.get_child_named(name, true, e)
All children	$entity.get_children(e)
An entity’s name	$entity.get_name(e)

Components live on entities

Each componentcomponent: One script attached to one entity. The same script on ten entities is ten components, each with its own copy of the script's fields. is one script on one entity, and an entity can carry many. The ones you meet everywhere:

Script	What it does
transform	Where the entity is: its position, rotation and scale, relative to its parent.
model	Draws a 3D model.
box_trigger	Notices things overlapping a box, and tells the other scripts on its entity.
effect	A visual effect that can be told to play.
catch_player	Makes an entity a player.

Scripts on the same entity cooperate closely: a box_trigger sends trigger_overlapped to every script next to it, which is why your trigger script sits on the trigger’s entity.

Levels and prefabs

A levellevel: A file of entities: a map, or a smaller piece placed inside one. is a file of entities. The map is a level, and so is anything smaller built to be placed inside one.

A prefabprefab: A level built to be placed many times. Each placement is an instance, and its entities become children of the entity that places it. is a level built to be placed many times: one teleport pad, one scoreboard. Each placement is an instance: the prefab’s entities are created as children of the entity that places it. That has a consequence worth remembering:

Prefab entities share names

Every instance of a prefab has entities with the same names; every teleport pad has a child called arrival. Searching the whole world for arrival can’t tell them apart. Search near your own entity instead: its children first, then up through its parents. The teleport pad does exactly that.

Constants are set per placement: the editor lets each instance override the constants of the components inside it, which is how one prefab becomes two pads pointing at each other.

Finding the world’s components

Sometimes the component you need isn’t near you at all: there’s one scoreboard, one match, one of each manager.

// The one catch_world in the game.
let world: Component = $component.get_singleton("catch_world.vscript", null)

// Every ball turret, anywhere.
let turrets: list = $world.get_all_components("ball_turret.vscript", "", null, "", 0)

These search the whole world, so prefer the local searches when the thing is nearby. See the Cookbook for more.

For programmers

It’s an entity–component model without systems: behaviour lives in the components’ scripts, driven by events. Transforms are hierarchical (local to parent). Level spawning is asynchronous: children of a freshly spawned level may not exist yet when created runs; children_changed and $entity.are_children_pending tell you when they do.