Instance is the main scripting API. Every script imports it:

import { Instance } from "lambda_script/point_script";

This page covers every Instance function and event. Related reference pages: Entity Methods, Player Methods, Value Classes, and Enums.

Logging and game state

Instance.Msg(value)

Converts value to a string and prints it to the server console with a [lambda_script] prefix. Returns undefined.

Instance.Print(value)

Alias of Instance.Msg(value).

Instance.PrintMessage(destination, message)

Sends a message to every player. Import HUD to select chat, console, or center-screen output. Messages are limited to 255 bytes.

import { HUD, Instance } from "lambda_script/point_script";

Instance.PrintMessage(HUD.PRINTCENTER, "Round starting");

Instance.GetGameTime()

Returns the current server game time in seconds.

Instance.GetMapName()

Returns the current map name as a string.

Instance.IsAvailable(name)

Returns whether the scripting module provides a named class, enum, or built-in export. Names are case-sensitive and limited to 128 bytes. Missing names return false.

For optional project APIs, import the module namespace rather than directly importing a name that might not exist:

import * as Script from "lambda_script/point_script";

if (Script.Instance.IsAvailable("CS")) {
	Script.Instance.Msg(`warmup: ${Script.CS.IsWarmupPeriod()}`);
}

A direct import { CS } ... fails during module loading when CS is unavailable, before script code can perform the check. See optional APIs for the full pattern.

Commands

Instance.ServerCommand(command)

Queues a server console command. The command must be a non-empty string no longer than 1024 bytes. Returns undefined.

Instance.ClientCommand(playerSlot, command)

Runs a command on the client occupying the zero-based playerSlot. The command must be a non-empty string no longer than 512 bytes. Throws if the slot is empty. Returns undefined.

Instance.RegisterCheatCommand(name, callback)

Registers a cheat-protected server console command. The callback receives the complete argument string excluding the command name.

Instance.RegisterCheatCommand("open_security", (argumentsText) => {
	Instance.Msg(`arguments: ${argumentsText}`);
});

Names may contain letters, digits, _, or $, must be at most 64 bytes, and are global to the Source console. Commands are removed when their owning script reloads or is destroyed. At most 256 script commands may exist across the runtime.

Entity I/O

Instance.EntFireAtName(options)

Fires a Source input on every entity matching a target name.

const acceptedCount = Instance.EntFireAtName({
	name: "security_door",
	input: "Open",
	value: "",
	delay: 0,
	activator: undefined,
	caller: undefined,
});

With no delay, it returns the number of entities that accepted the input. With a positive delay, it queues the operation and returns undefined. Delayed name-based inputs resolve matching entities when the input is delivered.

Instance.EntFireAtTarget(options)

Fires a Source input on one Entity. It uses the same options as EntFireAtName, except target: Entity replaces name.

const accepted = Instance.EntFireAtTarget({
	target: door,
	input: "Enable",
	value: "",
	delay: 0,
	activator: player,
});

With no delay, it returns whether the target accepted the input. With a positive delay, it returns undefined; delivery is skipped if the target no longer exists. Each script instance may queue at most 1024 delayed inputs.

Entity search

Instance.FindEntityByName(name)

Returns the first Entity with the matching Source target name, or undefined. The name is limited to 128 bytes and may contain * wildcards.

Instance.FindEntitiesByName(name)

Returns an array of all entities with the matching Source target name. * matches any sequence, for example chess.piece.*.

Instance.FindEntityByClass(className)

Returns the first Entity with the matching classname, or undefined. The classname is limited to 128 bytes.

Instance.FindEntitiesByClass(className)

Returns an array of all entities with the matching classname.

Players

Instance.GetPlayerController(playerSlot)

Returns the player Entity occupying the zero-based slot, or undefined. Garry's Mod does not have separate CS2 controller and pawn entities.

Instance.GetAllPlayerControllers()

Returns an array containing every currently resolvable player Entity.

Think scheduling

Instance.SetThink(callback)

Sets or replaces the instance's retained think callback. Only one think callback is stored per script instance.

Instance.SetNextThink(time)

Schedules the retained think callback at an absolute game time, as returned by Instance.GetGameTime(). The schedule is cleared before the callback runs, so repeating work must schedule the next execution again.

Instance.SetThink(() => {
	Instance.Msg("One second passed");
	Instance.SetNextThink(Instance.GetGameTime() + 1);
});

Instance.SetNextThink(Instance.GetGameTime() + 1);

Instance.QueueAfterThinks(callback)

Queues a one-shot callback after every entity has finished its physics and think work for the current server tick. This is useful when an entity may currently be part-way through handling input, movement, or another computation.

Instance.QueueAfterThinks(() => {
	Instance.Msg("The world is in its post-think state");
});

Callbacks run in queue order. Callbacks added while the queue is being processed can run later in the same tick. Queued callbacks are removed if their script instance reloads or is destroyed. A safety budget limits execution to 1,024 callbacks per tick; any remaining callbacks continue on the next tick.

Timers

Instance.SimpleTimer(delay, callback)

Schedules callback once after delay seconds of game time:

Instance.SimpleTimer(3, () => {
	Instance.Msg("Three seconds passed");
});

delay may be a fractional number and must be finite and non-negative. A zero-delay callback runs no earlier than the runtime's next timer-processing tick.

Instance.CreateTimer(configuration)

Creates, starts, and returns a controllable Timer:

const announcementTimer = Instance.CreateTimer({
	delay: 30,
	repetitions: 0,
	callback: () => {
		Instance.Msg("This runs every 30 seconds");
	},
});

Each script instance may own at most 256 timers, including simple timers. Repeating zero-delay timers run at most once per server tick.

Timer methods

Except for IsValid() and the idempotent Remove(), using a completed or removed timer throws a ReferenceError. A final callback may call Start() to keep its timer alive.

Timers use server game time. They do not progress while the server is not simulating, such as normal empty-server hibernation. Timer callbacks are covered by the JavaScript execution watchdog and standard exception reporting. Every timer is cancelled and its callback released when its owning script reloads or is destroyed; a Timer retained through reload memory will therefore be invalid.

Script lifecycle

Instance.OnActivate(callback)

Registers a no-argument callback that runs after the script executes successfully. It also runs after a successful reload. Up to 256 callbacks may be registered.

Instance.OnScriptInput(name, callback)

Registers or replaces a named map-script input. The callback receives the input value as a string.

Instance.OnScriptInput("OpenDoor", (value) => {
	Instance.Msg(`OpenDoor value: ${value}`);
});

Names are case-sensitive and must contain 1-128 bytes.

Instance.OnScriptReload(options)

Registers optional callbacks for preserving selected state across a script reload.

let counter = 0;

Instance.OnScriptReload({
	before: () => ({ counter }),
	after: (memory) => {
		if (memory !== undefined)
			counter = memory.counter;
	},
});

before() runs in the old script before its callbacks are cleared. Its return value is retained. After the new file executes, the new registration's after(memory) receives the matching retained value. Either callback may be omitted. Up to 256 reload registrations may exist.

Player events

Each event function registers a callback and returns undefined. Up to 256 callbacks may be registered for each event type. Most callbacks use Source game events. OnPlayerChat, OnPlayerLoaded, and OnPlayerReady use Garry's Mod hooks.

Instance.OnPlayerConnect(callback)

Listens for Source's player_connect event.

Instance.OnPlayerConnect(({ player, playerSlot, name, networkId, isBot }) => {});

player may be undefined because the entity might not exist yet.

Instance.OnPlayerActivate(callback)

Listens for player_activate.

Instance.OnPlayerActivate(({ player }) => {});

Instance.OnPlayerDisconnect(callback)

Listens for player_disconnect.

Instance.OnPlayerDisconnect(({ playerSlot, name, networkId, reason, isBot }) => {});

playerSlot is -1 if the entity can no longer be resolved.

Instance.OnPlayerChat(callback)

Listens for Garry's Mod's PlayerSay hook.

Instance.OnPlayerChat(({ player, text, team }) => {});

The payload's team value is the hook's third argument when it is numeric; otherwise it falls back to player:Team(). Compatible custom chatboxes are supported when they invoke hook.Run("PlayerSay", player, text, team, dead).

Instance.OnPlayerDamage(callback)

Listens for player_hurt.

Instance.OnPlayerDamage(({ player, attacker, health }) => {});

attacker may be undefined.

Instance.OnPlayerKill(callback)

Listens for entity_killed, restricted to player victims.

Instance.OnPlayerKill(({ player, attacker, inflictor, damageBits }) => {});

attacker and inflictor may be undefined. The damage bits are Source bitmask numbers, not CSDamageFlags.

Instance.OnPlayerLoaded(callback)

Runs when OnConnectedToLambdaOnline reports that the player's Lambda Online profile has loaded. The callback receives the player Entity directly.

Instance.OnPlayerLoaded((player) => {
	Instance.Msg(`${player.GetPlayerName()} has loaded`);
});

Instance.OnPlayerReady(callback)

Runs when OnPlayerAcceptedMOTD reports that the player accepted the rules and is ready to play. The callback receives the player Entity directly.

Instance.OnPlayerReady((player) => {
	Instance.Msg(`${player.GetPlayerName()} is ready`);
});

Player movement hooks

These callbacks use Garry's Mod's server hooks and receive the player Entity directly. Up to 256 callbacks may be registered for each hook per script instance.

Instance.OnPlayerJump(callback)

Runs when a player jumps off the ground.

Instance.OnPlayerJump((player) => {
	Instance.Msg(`${player.GetPlayerName()} jumped`);
});

Instance.OnPlayerLand(callback)

Runs when a player makes contact with the ground after a jump or fall.

Instance.OnPlayerLand((player) => {
	Instance.Msg(`${player.GetPlayerName()} landed`);
});

Tracing

Instance.TraceLine(options)

Performs an engine ray trace and returns a TraceResult.

const trace = Instance.TraceLine({
	start: { x: 0, y: 0, z: 64 },
	end: { x: 1024, y: 0, z: 64 },
	mask: TraceMask.SHOT,
	ignoreEntity: player,
	ignorePlayers: false,
});

Instance.TraceBox(options)

Performs a swept axis-aligned box trace. It accepts the same options as TraceLine plus required mins and maxs vectors.

const trace = Instance.TraceBox({
	start: { x: 0, y: 0, z: 64 },
	end: { x: 128, y: 0, z: 64 },
	mins: { x: -16, y: -16, z: 0 },
	maxs: { x: 16, y: 16, z: 72 },
});

Debug drawing

Debug drawing functions return undefined. Text is limited to 1024 bytes. Their duration defaults to 5 seconds and their color defaults to opaque white.

Instance.DebugScreenText(options)

Draws debug-overlay screen text. text, x, and y are required.

Instance.DebugScreenText({
	text: "Hello",
	x: 0.02,
	y: 0.1,
	duration: 5,
	color: { r: 255, g: 255, b: 255, a: 255 },
});

Instance.DebugLine(options)

Draws a world-space line. start and end are required.

Instance.DebugLine({
	start: { x: 0, y: 0, z: 0 },
	end: { x: 128, y: 0, z: 0 },
	duration: 5,
	color: { r: 255, g: 0, b: 0 },
});

Instance.DebugBox(options)

Draws an axis-aligned box at the world origin. mins and maxs are required.

Instance.DebugBox({
	mins: { x: -16, y: -16, z: 0 },
	maxs: { x: 16, y: 16, z: 72 },
	duration: 5,
	color: { r: 0, g: 255, b: 0, a: 64 },
});

Save data

Instance.GetSaveData()

Returns the current map's saved string, or "" if it has no saved data. The file is shared by every script instance on the map and is limited to 1 MiB.

Instance.SetSaveData(data)

Stores a string of at most 1 MiB for the current map. This is the only persistent storage exposed to scripts; scripts cannot select arbitrary paths.

const state = JSON.parse(Instance.GetSaveData() || "{}");
state.openCount = (state.openCount ?? 0) + 1;
Instance.SetSaveData(JSON.stringify(state));