Calling natives

A nativenative: A function built into the engine, called with a $ in front: $entity.get_name(e). Natives are how a script reaches anything outside itself. is a function built into the engine. Everything that touches the game world (finding entities, reading positions, playing sounds, printing) goes through one.

let me: Entity = $entity.get()
let where: vec3 = $entity.get_world_position($support.entity_get_component(me, "transform.vscript"))
$debug.print_line("I am at {}", [where], false)

A native call is $, a namespace, a dot, and the native’s name. The namespace groups related natives: $entity for entities, $math for maths, $net for networking, $time for clocks. The Natives reference lists every one, with the engine’s own description of each parameter.

Pass every argument

A native takes its arguments in a fixed order, and you must pass all of them, even the ones the reference calls “optional”. Leaving one out is an error (V0303). When you don’t need a value, pass the one that means none:

Parameter type	“None” value
string (a name to filter by)	""
Entity, Component, User, Reference	null
int, float	0
bool	false
list	null

// Every component of a script in the world: no name, owner or field filter.
let turrets: list = $world.get_all_components("ball_turret.vscript", "", null, "", 0)

null is not “me”

Many natives take an entity and describe it as “omit to use the entity of the calling script”. You can’t omit it, and passing null does not mean “me”. It means “nothing”, and the call does nothing useful. Name your own entity with $entity.get():

✗ Doesn't work

// Looks for a child of nothing.
let fx: Entity = $entity.get_child_named("fx", true, null)

✓ Works

// Looks for a child of the entity this script is on.
let fx: Entity = $entity.get_child_named("fx", true, $entity.get())

Naming a script

Natives that look for components take the script’s file name, like "catch_player.vscript":

let me: Entity = $entity.get()
let transform: Component = $support.entity_get_component(me, "transform.vscript")
let player: Component = $entity.get_hierarchy_singleton("catch_player.vscript", me)

The numbers in shipped scripts

When you read a shipped script you’ll often see a number right after a script name or a field name: "transform.vscript", -1829683308. You can leave those numbers out; the compiler works them out from the name. If you do write one and it’s wrong, the compiler tells you the right one (V0305).

Lists as arguments

Some natives take a list of values, most often the {} fillers of the print natives. Write the list right in the call:

let name: string = "garage"
let count: int = 3
$debug.print_line("{} has {} pads", [name, count], false)

When a native fails

Natives don’t stop your script when something is missing. They return null, 0, false or an empty list, and often print a warning to the log. Check what comes back before using it:

let arrival: Entity = $entity.get_child_named("arrival", true, $entity.get())
if !arrival {
  $debug.print_warning("no arrival point under {}", [$entity.get_name($entity.get())], false)
  return
}

Read-only natives

The reference marks some natives read-only: they only look something up and change nothing. The others do something: move, spawn, destroy, play, send.

For programmers

Natives are resolved against the engine’s own registration table at compile time: unknown names are V0302, wrong counts V0303, wrong types V0304. Some descriptions say “DO NOT CALL MANUALLY”; those are helpers the engine’s compiler emitted for sugar this language partly lacks ($support.entity_get_component, $support.component_assert_type). They are the only way to reach some things from here and are used on purpose in this guide. Named arguments don’t apply to natives.