IO Scripting Reference

Reserved Identifiers

_self

The entity that owns this output/script.

_activator

The entity that triggered this chain. May be null.

chain

Pass-variable storage for the current connection’s execution. Indexer syntax: chain["key"].

globals

Persistent key/value storage across level transitions. Indexer syntax.

mapglobals

Key/value storage scoped to the current map session. Indexer syntax.

Engine Functions

Functions specific to this engine — entity queries, tracing, and world interaction:

stopchain()

Halts remaining connections in this output.

spawnentity(classname)

Spawns a new entity of the given classname. Returns the new entity.

phystrace(origin, direction, maxdistance?)

Raycasts the physics world (dynamic entities and props). Returns a TraceResult. maxdistance is optional.

bsptrace(origin, direction, maxdistance?)

Raycasts static world geometry only. Returns a TraceResult. .entity is always null.

entitiesinradius(center, radius)

Returns every entity within radius of center as an array.

ispathwalkable(from, to)

Returns whether a straight-line AI path between two points is walkable.

playsound(name, position?)

Plays a soundscript entry. Positioned in 3D if position is given.

playparticle(path, position)

Spawns a particle system at a position.

debugpoint(position)

Draws a debug point for this frame.

debugline(from, to)

Draws a debug line for this frame.

print(...)

Logs one or more values to the console. Accepts any number of arguments.

Standard Library

General-purpose functions available in every script, independent of any engine host.

Math

random() / random(max) / random(min, max)

Returns a random number. With no arguments, 0–1. With one argument, 0–max. With two, min–max.

min(a, b) / max(a, b)

Returns the smaller or larger of two numbers.

abs(n)

Absolute value.

floor(n) / ceil(n) / round(n)

Rounds down, up, or to the nearest integer.

clamp(value, min, max)

Clamps a number between a minimum and maximum.

lerp(a, b, t)

Linearly interpolates from a to b by t, typically 0–1.

pi() / e()

The constants π and e. Called as functions — pi(), not pi.

Strings

length(s)

Number of characters in a string.

upper(s) / lower(s)

Uppercase or lowercase copy of a string.

contains(s, substring)

Whether s contains substring.

Vectors

vec3(x, y, z) / vec2(x, y)

Constructs a vector from components.

dot(a, b)

Dot product of two vectors of the same dimension.

cross(a, b)

Cross product of two vectors of the same dimension. For vec3, returns a vec3. For vec2, returns a plain number (the scalar cross product) — not a vec2.

magnitude(v)

Length of a vector.

normalize(v)

Unit-length copy of a vector. Throws on a zero-length vector.

distance(a, b)

Distance between two vectors of the same dimension.

Arrays

array(size)

Creates a fixed-size array filled with null.

arrayof(...)

Creates an array containing exactly the given arguments, in order.

resize(arr, newSize)

Returns a resized copy of an array — arrays don’t grow in place.

size(arr)

Number of elements in an array.

Conversion

tostring(value)

Converts any value to its string representation.

tonumber(value)

Converts a number, numeric string, or bool to a number.

tobool(value)

Converts a bool, or the strings "1"/"true" (case-insensitive), to a bool. Throws on anything else.

Reflection & Assertions

hasmember(obj, name)

Whether an object has a readable member or indexer with this name.

assert(condition) / assert(condition, message)

Throws a runtime error if condition isn’t exactly true, optionally with a custom message.

Entity Members

.position / .velocity / .angles

Vector3D. Angles are Euler.

.targetname

The entity’s name, as a string. Settable.

.classname

The entity’s C# class name, e.g. "FuncDoor". Read-only.

.insidebrush

Array of entities currently inside this trigger volume. Only valid on brush-based volumes (FuncTrigger and similar) — errors on anything else.

Entity Methods

These are dedicated script methods with their own validation and argument types — prefer these over the forwarded inputs below wherever one exists for what you’re doing:

.applyimpulse(force) / .applyimpulseat(force, position)

Applies an instantaneous impulse, optionally at a world-space point (inducing torque).

.applyforce(force) / .applyforceat(force, position)

Applies a continuous force for this physics step, optionally at a point.

.addcondition(name) / .removecondition(name)

Applies or removes a named status condition.

.moveto(target)

Requests AI pathing toward a point or entity. Requires an AI-driven controller.

.ispathcompleted()

Whether the AI has reached its current move target. Requires an AI-driven controller.

Forwarded Inputs

Any input registered on an entity’s class can be called by name, and forwards straight to that entity’s C# input handler. This is the same mechanism a plain connection uses, just from inside a script:

door.SetPosition("0,0,64");
_self.Destroy();

Every WorldEntity has these forwarded inputs available: AddVelocity, SetVelocity, SetPosition, SetScale, SetRotation, Destroy, GetValue, SetValue. Individual entity classes may register more.

Note

AddImpulse, AddForce, and TakeDamage are also technically callable this way, but are hidden from autocomplete. Use .applyimpulse(), .applyforce(), and a dedicated damage method instead.

SetValue is a special case: it expects exactly two arguments (key, value) — key:value under the hood — while every other forwarded input joins its arguments with commas.

Types

Vector3D / Vector2D

Component access via .x/.y/.z or numeric indexing (v[0], v[1], v[2]). Support +, - between vectors, *// between a vector and a number.

TraceResult

.hit (bool), .point, .normal (Vector3D), .entity (Entity, may be null). Returned by phystrace/bsptrace.

ChainObject (chain)

String-keyed indexer only — chain["key"] to read, chain["key"] = value to write. No other members.

GlobalsDict (globals, mapglobals)

Same string-keyed indexer as ChainObject. globals and mapglobals are both this same type, differing only in what backs them and how long values persist.

Things to Remember

  • Statements end with ;. Blocks use { }, same as C#.
  • wait() only propagates through statement-level function calls. Calling a function inside an expression (var x = f();) forces it to run fully synchronously.
  • pi and e are functions, not constants. Write pi(), not pi.
  • is can’t distinguish entity subclasses. Every entity reports the same type name to is entity. Use .classname to check for a specific class.
  • .moveto()/.ispathcompleted() require an AI-driven controller. Calling them on anything else throws a runtime error.
  • .insidebrush only works on trigger volumes. Errors on anything that isn’t a brush-based volume.
  • bsptrace never returns an entity, only phystrace can. Use bsptrace when you specifically want to ignore dynamic objects.
  • chain doesn’t survive between separate output firings. Use globals/mapglobals for anything that needs to persist.
Getting Started →