The VScript Book

Chapter 0.1: What is a Script?

At its heart, a video game is a simulation running on a set of rules. A Companion Cube falls due to the rule of gravity. A button, when pressed, sends a signal because of a rule. A door opens when it receives that signal.

A script is a file containing a list of instructions that you, the creator, write for the game to follow. It's your way of adding new rules to the simulation.

VScript is the system within Portal 2 that reads your instruction files. The language we use to write these instructions is called Squirrel. Learning to script is like learning a new language to communicate your ideas directly to the game engine.

Chapter 0.1.5: Setting Up Your Environment

Before we write any real logic, let’s get your tools ready and make sure you can run scripts in-game.

Enabling the Developer Console

Before you can test your scripts, you need to enable Portal 2's developer console:

  1. Launch Portal 2
  2. Go to Options → Keyboard → Advanced...
  3. Check the box for "Enable developer console (~)"
  4. Press the ~ key (tilde) to open the console in-game

Where Scripts Live: The vscripts Folder

All VScript files must be placed in a specific folder for Portal 2 to find them:

Portal 2/portal2/scripts/vscripts/

Create this folder path if it doesn't already exist. Any .nut file you place here can be loaded by entities in your map.

Your First Script: "Hello, Aperture"

Let's create your first working VScript:

  1. Create a new text file in the vscripts folder
  2. Name it hello_world.nut
  3. Open it in any text editor and add this single line:
printl("Hello, Aperture Science!")

Testing Your Script

Method 1: From the Console (Quickest)

Load any Portal 2 map, open the console, and type:

script_execute hello_world

You should see "Hello, Aperture Science!" printed in the console. The .nut extension is optional when using script_execute.

Method 2: In Hammer Editor

  1. Open Hammer and create a new map (or load an existing one)
  2. Place a logic_script entity anywhere in your map
  3. Select it and open its properties
  4. Set the "VScript File" keyvalue to hello_world.nut
  5. Compile and run your map

When the map loads, your script will automatically run, and the message will appear in the console.

Developer Levels: The developer console variable controls how much debug information the game shows. Set it with developer 1 (basic info) or developer 2 (verbose info) in the console. This is essential for debugging.