The VScript Book

Chapter 5.10: The Utility Belt: A Tour of PCapture-Lib's Helpers

Beyond the major systems like `TracePlus` and `ActionScheduler`, PCapture-Lib is packed with hundreds of utility functions and improvements. These are the everyday tools that save you time, reduce bugs, and make your code cleaner and more powerful.

This chapter serves as a reference guide to the most important of these utilities. You don't need to memorize them all, but knowing they exist will make you a far more efficient scripter.

Core Engine Improvements

PCapture-Lib directly upgrades several standard VScript functions to be more robust and useful.

  • GetPlayerEx()
    This is the new standard. While the original GetPlayer() returns a basic handle, GetPlayerEx() returns a powerful pcapEntity object, giving you immediate access to all the smart methods you learned about in Chapter 5.2.
  • FrameTime()
    The original function could sometimes return 0, which can cause errors in physics calculations (like division by zero). The library's version ensures it never returns zero, preventing these rare but frustrating bugs.
  • UniqueString(prefix)
    Improves the standard function by allowing you to add a prefix (e.g., "my_prop_"). This is great for creating unique, but readable, entity names for debugging.
  • EntFireByHandle(...)
    The library's version is upgraded to seamlessly accept pcapEntity objects as targets, activators, and callers, removing the need to manually handle different object types.

The Player Event System

Problem: How do you reliably know when a player dies, joins the server, or respawns? Standard VScript has no built-in way to track these events.

Solution: PCapture-Lib runs a system in the background that monitors players and provides "hooks"—empty functions that you can override to run your own code when these events happen.

// In your logic_script, you can simply define this function.
// PCapture-Lib will automatically call it whenever a player dies.
function OnPlayerDeath(player) {
    local playerName = player.GetName()
    dev.warning(playerName + " has been eliminated!")
    
    // Maybe trigger a failure state for a puzzle.
    EntFire("puzzle_manager", "FailPuzzle", "", 0)
}

// Another example: Welcome players when they join.
function OnPlayerJoined(player) {
    HUD.ScreenText(Vector(0.5, 0.5, 0), "Welcome, " + player.GetName(), 5.0).Enable()
}

The available hooks are: OnPlayerJoined(player), OnPlayerLeft(player), OnPlayerDeath(player), and OnPlayerRespawn(player). You can also get a list of all current players at any time with GetPlayers().

Portal-Specific Utilities

These are specialized helpers for maps that heavily feature portals.

  • FindPartnerForPropPortal(portal_handle): Given a handle to a `prop_portal` entity, this function will find and return the handle to its linked partner portal.
  • IsBluePortal(portal_handle): A simple check that returns `true` if the given portal is the blue one.
  • InitPortalPair(id): An advanced function needed for `TracePlus.PortalBbox` to work correctly with custom portal pairs (e.g., in multiplayer or with more than two portals).

The `macros` Library: Your Everyday Toolkit

This is a large collection of helper functions, grouped under the global table `macros`.

Sound & Console

  • Precache(sound_or_array): Precaches sounds to prevent in-game stuttering the first time they are played.
  • GetSoundDuration(soundName): Returns the length of a sound in seconds. Perfect for timing events.
  • CreateAlias(key, action) / CreateCommand(key, command): Lets you create custom console commands for easy debugging.

Data Handling & Conversion

  • StrToVec(string) / VecToStr(vector): Essential for converting between string and Vector formats, especially for the "Model Keyvalue Hack" from Chapter 4.4.
  • DeepCopy(table_or_array): Creates a true, independent copy of a table or array.
  • GetFromTable(table, key, defaultValue): Safely gets a value from a table. If the key doesn't exist, it returns the `defaultValue` instead of an error.
  • GetKeys(table) / GetValues(table): Return an array of a table's keys or values, respectively.
  • PrintIter(table_or_array): Prints the full contents of a table or array to the console for easy debugging.

Math & Geometry Helpers

  • GetDist(vec1, vec2): A shortcut for `(vec1 - vec2).Length()` to get the distance between two points.
  • PointInBBox(point, bbox_min, bbox_max): Returns `true` if a Vector point is inside a bounding box defined by two other Vectors.
  • PointInBounds(point): A quick check to see if a point is within the playable map area (not in the void).

Player & Entity Helpers

  • GetEyeEndpos(player, distance): Calculates the world-space position `distance` units directly in front of where the player is looking.