Finding entities

Each recipe is self-contained: copy it, then change the names. See Entities, components and levels for how the hierarchy works.

The entity my script is on

let me: Entity = $entity.get()

A child by name

true searches children’s children too; false looks only one level down.

let arrival: Entity = $entity.get_child_named("arrival", true, $entity.get())
if !arrival {
  return
}

A sibling by name

Siblings share your parent, so search from there:

let parent: Entity = $entity.get_parent($entity.get())
let pad: Entity = $entity.get_child_named("pad", false, parent)

Something nearby, wherever it is placed

The partner of a prefab-placed object may be several parents up. Search your own children, then each parent’s in turn, until the name turns up:

fn find_named_upwards(name: string) -> Entity {
  let mut at: Entity = $entity.get()
  while at {
    let found: Entity = $entity.get_child_named(name, true, at)
    if found {
      return found
    }
    at = $entity.get_parent(at)
  }
  return null
}

This is how the teleport pad finds the pad it sends players to. Close things are found first, so a sibling wins over a same-named entity elsewhere in the level.

Caution

The search starts from each parent’s children, never the parent itself, so an entity at the very top of a level finds nothing above it. Place the things you search for inside a group.

Every child with a name

let lamps: list = $entity.get_all_children_named("lamp", $entity.get(), true, false)
for i in 0..lamps.len() {
  let lamp: Entity = lamps.get(i)
  $debug.print_line("found {}", [$entity.get_name(lamp)], false)
}

The last argument true would match every name starting with "lamp": lamp_1, lamp_2, …

Walk up to the top

let mut at: Entity = $entity.get()
while $entity.get_parent(at) {
  at = $entity.get_parent(at)
}
$debug.print_line("top of my hierarchy: {}", [$entity.get_name(at)], false)

Where an entity is

An entity’s position lives in its transform component:

let transform: Component = $support.entity_get_component($entity.get(), "transform.vscript")
let position: vec3 = $entity.get_world_position(transform)
let rotation: vec4 = $entity.get_world_rotation(transform)
let forward: vec3 = $entity.get_forward(transform)

get_world_position gives the position in the world, whatever the parents are doing.

Spawn a level

Put the level to spawn in a Reference setting, then spawn it as a child of your entity:

// The level to spawn; chosen in the level editor.
let spawn_level: Reference = null

event export fn created() {
  if !spawn_level {
    return
  }
  let root: Entity = $entity.spawn_level(spawn_level, $entity.get(), 0, false, 0, null, false, null)
}

The arguments after the parent are: a network name (0; leave it), local only (false, so the new entities replicate), a spawn mode (0), an owner (null), whether to spawn at the end of this event instead of next frame (false), and a package (null). Its entities may not all exist on the same frame; see children_changed.

Destroy an entity

fn remove(target: Entity) {
  $entity.destroy(target, false, false)
}

The second argument false destroys its children too; the third waits until the next frame, which is the safe choice.