Scripting is the programming language used to make certain actions on the Level Editor. Simple actions are very easy to make and memorize, while the more difficult ones can give trouble to less focused creators.
These commands are the most basic. They're a pretty good selection so you won't need to move past them most of the time.
Creating a new script Edit
First, you need to create a script. Scripts are like text files in your level data where you can write commands into, which will then be played by either a script box item or a terminal item. Unfortunately, you can't create a script just by itself. For a script to be created, you need to make a terminal or a script box and name its script id with the name of the script you want to make. Deleting the item won't delete the script. Naming the script id the same as a script that already exists will link the item to the existing script instead of creating a new one.
Editing your new script Edit
To start writing your commands, you need to access your script. To do so, press ESC and then go to edit scripts. Once in the script screen, select your script and you'll now be able to type in it. Scripts are automatically "saved" so you don't need to worry about leaving the page and losing your work. You do need to worry about not having your game crash, since scripts are only temporarily saved until you save your level, and will be lost if you leave the level editor without saving or if the game is suddenly closed.
Say command Edit
This command is the most basic of all and the one you'll use the most. It creates a text box which can also be linked to a character or an object.
n is the number of lines your text box will have. c is the color of the text box. You can use a number, the character the color relates to, or of course, the color. The text box will always be linked to the character its color is related to, if possible. So if Violet is in the room and the command is played with c set as "pink," the text box will appear close to Violet. If it isn't possible to link the text box, the text box will just float in the screen. c can be omitted if you want, like so:
If you omit c, the text box will be grey. Grey text boxes are linked to the terminal playing the script. It can't link to different terminals or to script boxes. Another property of c is that even if your next say command does not have c, c will carry over from the last command, so if you want to reset to the default (grey), you need to type out the color "grey" as c.
short for "say(1)"
say(1,yellow)|Hello there!|say|This is a yellow dialogue!
("|" represents a new line) In the code above, Vitellary would say "Hello there!" in a yellow text box, and then say "This is a yellow dialogue!" in a new yellow text box, right after.
Last but not least, you can set c to cyan, in which case it will make Viridian talk. Keep in mind, though, that while this can link to the Viridian that you're playing with, it prioritizes crewmate Viridian (the one you can place with the Crewmate item).
Reply command Edit
This command is very similar to the say command with c set as cyan. However, there are a few situations where it is useful.
- You want to have player Viridian and crewmate Viridian talk to each other.
- You want to have player Viridian talk while crewmate Viridian is in the screen.
- You want to have player Viridian talk without changing the current say chain's color.
- You just want to type 8 characters instead of the 11 of say(n,cyan).
Like said before, this command doesn't support color, being always cyan and always linking to player Viridian. You type it similarly to say, with n being the number of lines of the text box:
Of course there is a short version for reply (1):
Delay command Edit
An easy command. It delays the next command by a t amount of time.
You don't type units here, only a number. 1 means 1/30 second, so you should probably get your calculator ready here.
say(1,red)|Hey Captain!|reply(1)|What?|delay(15)|say(1,red)|...|delay(15)|say(1,red)|Forget about it.
In the code above, Vermillion will say "Hey Captain!", for which Viridian will reply "What?". After half a second of delay, a red "..." text box, and another half a second of delay, Vermillion will finally say "Forget about it."
Destroy command Edit
You can use this command to destroy things.
x is equivalent to gravitylines, warptokens or platforms.
When this command is played, whatever you placed as x will disappear. For example:
This command will make all gravity lines on the screen disappear.
This command is very useful to make big doors or just doing some inventive puzzles.
Music command Edit
This command will change the music currently being played, even if it is currently set to off.
n is the number of the music you want to play. The number is the same as the ones shown in the change music screen of the level editor. With a few exceptions that don't appear there:
- "0a" will play Path Complete
- "5a" will play Pause
- "7a" will play Plenary
- "9a" will play ecroF evitisoP
- "15a" will play Predestined Fate Remix
Flash command Edit
This command will shake the screen, make the screen white and play the flashing sound when played. There is not much to it other than that.
Flag commands Edit
Flags are the logic of VVVVVV scripting. You can set a flag on or off by using the following command:
The number is any number below 100 (not including 100). After setting a flag on, you can use the following command:
This command will run a different script if flag of n number is on. By using this, the script you set it to change to will be what happens if the flag is on, and the rest of the script will be what happens if the flag is off.
Trinket commands Edit
This is very similar to what you do with flags, but it is tied to trinket completion. See the following command:
n is the number of trinkets you want to gate-keep. If the number of trinkets the player has is equal or higher than the one set, then the script written here will run. If not, it will continue in the current script. You can also do the inverse:
This command will do the same as iftrinkets, but instead of running the script when the player has the set number of trinkets or more, it will run a script when the player doesn't have the set number of trinkets.
Happy and Sad commands Edit
These commands will change the mood of the characters they are referring too.
Both above and below, c is the character you want to change the mood to. Like with the say command's c, it works with numbers, character names and colors. Using grey will not work here, though, since terminals don't get happy or sad.
You can also omit c from the command, which will always make the command affect Viridian (cyan as c also works for Viridian, however, it will prioritize crewmate Viridian).
Comment lines Edit
(comment your code like this)
Apparently you can insert text into your script which is entirely ignored by the game engine by putting it into round brackets ().
Though it requires further testing and validation this technique can help one keep track of scripts in more complex projects.
Internal scripting are scripts that were not supposed to be used in levels created by the editor and were made for the real game. Many of them don't work or outright corrupt the game, so when working with them, extra care is recommended. This tutorial will only go over the ones which are absolutely safe to use. For more info, take a look at the VVVVVV Internal Scripting Resource.
Creating a new internal script Edit
Internal scripts, like the name suggests, are scripts inside scripts. They need to be "called" to work by tricking the parser. Internal scripts unfortunately will always have cutscene bars. There are methods to call them which make the bars not appear, but they will limit the amount of scripts you can use.
So, first type this command:
n is the amount of lines you will use of internal scripting. Notice the "+1"; you need to add 1 more line to the amount you will be using, so if you're using 34 lines of internal scripting, you write 35 on say.
After typing commands like the ones you'll see further down the guide, finish with this:
You can also repeat text(1,0,0,4)|say(n+1) for more scripting space, like this:
say(-1)|text(1,0,0,4)|say(10)| | | | | | | | | |text(1,0,0,4)|say(5)| | | | |text(1,0,0,4)|say(4)|endcutscene()|untilbars()|loadscript(stop)
Creating a new internal command Edit
This is a second method of creating an internal script. However, it can only be used for one-line commands and is generally recommended to be used for only one or two lines as it is quite the space-waster.
First, create a new script, with the following inside:
Now, create another script, with the name you put in the first one as script2. This one should contain this:
ic stands for "internal command" and it is here you will put your single line of internal scripting. After this line, be sure to make a blank line so your internal command isn't deleted. Not 0, not 2, one. "#" can be any simplified command. Or you can just keep # as well. What you need is something there before A)Say. Anything before A)Say will load after A)Say though, for some strange reason.
You can make script2 another first script by utilizing your extra space to make another iftrinkets command, like this:
So you can have a chain like this:
Simplified commands inside internal scripts Edit
Before continuing into the tutorial, there is a single methodology that I extremely recommend you to follow. That is, "if you can do something on simplified, don't do it on internal." Internal scripting is a deep rabbit hole, and a buggy one at that. Unless you can absolutely only do what you want to this way, simplified is always better, and as the name says, simpler.
These commands do the same as their simplified counterparts. The only actual reason you might want to use them is to use their functionalities between internal commands. For example, you might want the game to check how many trinkets a player has between a fadein() and a fadeout(). You're not supposed to go internal just to use them since once you start using internal scripts, you're basically adding a hundred more ways for things to go wrong.
The play command actually has a catch: the numbers aren't the same as the music command. The numbers are as follows.
- "0" will play Path Complete
- "1" will play Pushing Onwards
- "2" will play Positive Force
- "3" will play Potential for Anything
- "4" will play Passion for Exploring
- "5" will play Pause
- "6" will play Presenting VVVVVV
- "7" will play Plenary
- "8" will play Predestined Fate
- "9" will play ecroF evitisoP
- "10" will play Popular Potpurri
- "11" will play Pipe Dream
- "12" will play Pressure Cooker
- "13" will play Paced Energy
- "14" will play Piercing the Sky
- "15" will play Predestined Fate Remix
Advanced text manipulating Edit
So, say is cool and all but it can't quite achieve what you want. You want to have more control over stuff, and that's where these commands will fit into!
Squeaking command Edit
This command will make the squeaking (or beeping) sound that appears with a text box. Text boxes created with the commands further down don't include these kind of noises like say does so this command is extremely important. It's generally the first one you want to write when making a text box.
c is, of course, color/character.
Writing command Edit
This command works a little bit like say. You have to type your text below the command, using up lines.
There are a lot of variables here so let's go one by one:
- c is, like usual, color. "cyan", "blue", "red", "yellow;" you know the deal. You can also use character names and numbers. One crucial difference here, is that you have a wider variety of colors you can use with some tricks shown later in the tutorial.
- x and y are the position of the text box in the screen. Yes, they stand for horizontal and vertical. You can use another command to set the position more easily later, so setting these to 0 is not uncommon.
- n is the number of lines you'll be using in your text.
Positioning command Edit
With this command, you can position the text box you just created more easily. This is supposed to go right after the text command and the lines written in it.
There are five modes you can set x to.
- "center" will center both x and y.
- "centerx" will center x.
- "centery" will center y.
- "c,above" will link the text box to the character related to c, which stands for color (you have to replace it with the color like the text or say command).
- "c,below" will do the same as c,above but will place the text box below the character instead of above.
Speak command Edit
These commands will finally play what you written prior to them. There are two of them, "speak" and "speak_active".
speak will show the text box on the screen, without removing any text boxes shown prior. With this, you can make several text boxes appear at the same time.
speak_active will show the text box on the screen, and remove any text boxes prior to it. This is the most useful one since you can maintain normal VVVVVV-like conversations without much work and without it looking like garbage.
Ending the text Edit
Even if you use speak_active, there will always be a line that needs to be ended. That's what this command is for. It is supposed to be placed at the end, even after a Speaking command.
endtext will fade the text box away.
endtextfast will make the text box disappear right away.
Now, with all the main commands, let's try to make a text box:
squeak(player)|text(cyan,0,0,2)|This is a test! A text test!|Text test text!|position(player,above)|speak|endtextfast
Now, let's break this code down:
- First, with squeak(player), we're having Viridian squeak. I've not mentioned it before, but you can use "player" and "terminal" in these situations.
- Second, with text(cyan,0,0,2), we're preparing the script to handle 2 lines of text, which will appear in a cyan text box, positioned at coordinates 0,0 of the screen.
- Third, we write our lines. "This is a test! A text test!" in one, and "Text test text!" in other.
- Fourth, we set the actual position of our lines (which will not be 0,0) with position(player,above), which will tell the script to place the text box of our last text command above the player.
- Fifth, we use speak to make the text box actually appear. We don't need speak_active since this is the first text box and there are none preceding it that need to be erased.
- Last, but not least, we use endtextfast to make the text box disappear after the player presses the ACTION button.
By using the following command you can make so the script doesn't need the ACTION press for the script to progress:
You put this right after the text command and it will make so the text won't lock the script with the ACTION press. You can use this to have multiple text boxes at the same time, or just to have a text box that times itself.
If you want to have a text box that times itself, just putting this command in will not do anything, as the text box will end as soon as it starts. You need to put a delay before your endtext or endtextfast.
Here's an example that has three text boxes appearing at the same time, which time themselves to fade out.
squeak(terminal)|text(grey,0,0,1)|Test text 1|backgroundtext|speak|text(grey,0,50,1)|Test text 2|backgroundtext|speak|text(grey,0,100,1)|Test text 3|backgroundtext|speak|delay(120)|endtext
Making text boxes of different colors Edit
Earlier I said you could make text boxes of different colors than the main six. To do so, you have to input this command after text but before your speak or speak_active command:
This command actually has a different function which will be explained further down, but for now you just need to know this will change the colors of the text boxes. Now a different color from the one on text will appear. Use the image at the right for reference.