Hello world

Every language starts with a program that says hello. Here is vscript’s:

hello.vscript

// hello.vscript: prints one line when the component is created.
event export fn created() {
  $debug.print_line("Hello from vscript!", null, false);
}

That’s the whole script. It prints Hello from vscript! to the game’s log when the component is created.

Line by line

// hello.vscript: prints one line when the component is created.

A line starting with // is a comment. The game ignores it; it’s for people reading the script. Say what the script is for and why a line is there.

event export fn created() {

This starts a function called created. The words in front of fn say what kind:

• event: the engine may call it when something happens.
• export: other code outside this script may call it.

Every event is written event export fn. The name created isn’t a free choice: it’s the name of the event the engine sends when your 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. has just been created. The empty () means this event receives no values. The { opens the function’s body.

  $debug.print_line("Hello from vscript!", null, false);

The body. $debug.print_line is 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.: debug is its namespace, print_line its name. It takes three values, separated by commas:

1. "Hello from vscript!" is the text to print. Text in quotes is a string.
2. null stands for the values to fill into the text. We have none, so we pass null, meaning nothing.
3. false controls a detail about replays; leave it false.

The ; ends the statement. You may leave it off at the end of a line; the language adds it for you.

}

The } closes the function.

Running it

1. Create a new script named hello.vscript and paste the code in.

2. Add it as a component to an entity in a level. Any entity will do.

3. Start the game and load that level. When the entity is created, the line appears in the game’s log.

Note

A script only runs when it is on an entity the game loads. A script that nothing uses is never created, so its created event never happens.

Make it say something useful

print_line fills each {} in the text with the next value from a list. A list is written in square brackets:

event export fn created() {
  let me: Entity = $entity.get();
  $debug.print_line("Hello from {}!", [$entity.get_name(me)], false);
}

Now it prints the name of the entity it sits on. $entity.get() answers “which entity am I on?”, and $entity.get_name reads that entity’s name. The let me: Entity = … line stores the answer in a local variablelocal: A variable declared with let inside a function. It exists only until the function returns. called me so we can use it on the next line. The Locals page explains let properly.

For programmers

print_line’s last parameter, during_rollforth, controls whether the line is also printed while the game re-simulates frames during rollback. Leave it false unless you are debugging rollback. The compiler supplies the source file and line for the log itself; you never write them.