Welcome to The VScript Book

This book is your comprehensive guide to creating custom gameplay in Portal 2 using VScript. We will start from the absolute beginning—assuming you have no prior programming experience—and build your skills step-by-step. Our goal is to empower you to turn your creative puzzle ideas into interactive reality.

Who Is This Book For?

This guide is written with a primary focus on Portal 2 and its specific version of VScript (which uses the Squirrel language). Every example and project is tailored for the world of Aperture Science.

However, the fundamental principles of the Squirrel programming language and the VScript system are universal across many Source Engine games (like Team Fortress 2 and CS:GO). While some game-specific functions may differ, the logic and structure you'll learn here provide a rock-solid foundation for any Squirrel-based VScript project, making this book a valuable starting point for any aspiring Source Engine scripter.

About the Author

This guide was written by laVashik, a VScript developer well-known in the Portal 2 modding community for his technical mastery of the engine. His experience is forged from years of pushing Portal 2 to its absolute limits, culminating in the creation of Project Capture—one of the most technically ambitious mods for the game, powered by over 13,000 lines of VScript code.

Much of that work led to the development of PCapture-Lib, the powerful VScript library that you will master in the later parts of this book. This library encapsulates advanced techniques, engine workarounds, and performance optimizations to provide functionality that is both incredibly powerful and easy to use.

Essential Resources

This book is a guided learning path, but you'll also want to keep these official references handy:

• Valve Developer Community - Portal 2 VScript Function List - The official, community-maintained documentation of all VScript functions available in Portal 2. This is your primary API reference.
  
• Official Squirrel Language Reference Manual - The complete documentation for the Squirrel programming language itself. Useful for understanding language features beyond what VScript exposes.
  
• PCapture-Lib GitHub Repository - The source code, documentation, and examples for the PCapture-Lib library. Each module has detailed README files with usage examples.
  
• VDC - VScript Fundamentals - General VScript documentation that applies to all Source Engine games using the system.
  

How This Book is Structured:

• Part 0: The Language of Logic (Programming Fundamentals): We'll learn the universal concepts of coding—variables, loops, functions—in a way that anyone can understand, using Portal 2 scenarios as examples.
• Part 1: Learning the Dialect (Introduction to Squirrel): We'll focus on the specific grammar and rules of Squirrel, the language used in Portal 2's VScript, including its powerful table and array systems.
• Part 2: Connecting to the World (VScript in Portal 2): We'll bridge the gap between your code and the game itself, learning how to make scripts run, how to find and manipulate entities, and how to respond to player actions.
• Part 3: Becoming a Creator (Interacting with the Game): The core of Portal 2 modding. You'll learn to work with vectors, find entities, use hooks and think functions, and debug your creations.
• Part 4: Advanced Techniques (Optimization & Best Practices): Once you've mastered the basics, we'll dive into error handling, performance optimization, sound synchronization, and advanced entity manipulation techniques.
• Part 5: PCapture-Lib & Beyond (Professional Tools): Finally, we'll introduce the powerful PCapture-Lib library, which extends VScript with advanced features like entity tracing through portals, smooth animations, file I/O, and much more.