Guide:Getting started with scripting

This is a guide on getting started with scripting in your custom VVVVVV level.

Creating a script

Scripts can be run by terminals, script boxes, or other scripts. A script box is an invisible area that will trigger its associated script when the player enters it, a terminal requires the player to press a button to activate it.

To place down a terminal, use the terminal (T) tool; to place down a script box, use the script box (Y) tool and click the top left and bottom right corners. After placing it, enter a script name (for example, intro or area2_foundvictoria), and hit Enter. This will automatically create a script for you, which you can find with Esc > "edit scripts" (if you use the in-game editor) or by pressing "Scripts" (if you use Ved) and selecting the script with the name you just entered.

Writing a simple script

To demonstrate a simple cutscene, this is a script you could enter in the script editor:

The say command can be used to make terminals and other crewmates talk, the reply command is reserved for Viridian. Both take a number of lines (for simplicity, it's always included in this example, even if it's not always needed for 1-line textboxes), and the say command optionally takes a color.

Making your script not repeat

If you leave and re-enter a room, scripts can be activated again. This is annoying for cutscenes which are expected to run only once. To solve this problem, you can use flags, which are little variables that you can set to be on or off (you can see them as little light bulbs), and can decide whether to jump to another script from within a script. There are 100 flags in each level, numbered from 0 to 99. When you start a level from the beginning, all 100 flags are off by default.

You can turn a flag on/off with the flag command (for example, flag(5,on) to turn flag 5 on, flag(5,off) to turn it off). In scripts, you can make decisions based on these flags with ifflag. How does this work?

ifflag(5,otherscript)

• If flag 5 is on: jump to the script called otherscript.
• If flag 5 is off: continue in the current script.

To make a script non-repeating, you need two scripts: a load script, and your existing script with dialogue in it. Replace your terminal or script box, and instead of assigning the original script name (like intro), use a different name for the load script (conventionally intro_load). This new script should have the following contents:

The first line (ifflag(0,stop)) jumps to the script called stop if flag 0 is on. Since you didn't make a script called stop, the script just silently ends there, which is what you want to happen if you already visited this. (You can create a script called stop and leave it empty, but it's not necessary for it to exist).

Since flag 0 is off by default at the start of a level, the game will continue in the current script instead, but only this one time, because the next line, flag(0,on) turns flag 0 on, for the rest of the playthrough.

The last line will jump to the script intro if the player has collected 0 or more trinkets, which is always. There's no simpler command to always jump to a script, and if you try this construction with only one script (so ifflag and flag at the top of your dialogue script), the game will always show cutscene bars because the script contains some dialogue, even if it never gets reached.

Since flags are unique per level, you have to use a different flag number for each script you need to run only once - otherwise triggering one script will stop the other from running as well.

Non-repeating scripts in Ved

Now that you know how load scripts work - if you use Ved, you can automate this process. When placing a terminal or script box, there's a set of radio buttons on the right.

If you set this to Run once, Ved will create a load script automatically for you.

More scripting possibilities

TODO: other simplified commands, or link to a list. Ved has a reference with all commands.

Internal scripting

TODO: you may have heard of it, it's more complicated but much more powerful. See Guide:Internal scripting