Scripting Reference

1. Execution model and source layout

rat5.v2 is the supported event-script version. RAT selects enabled definitions for an event, builds read-only event and runtime values, validates the script, and executes statements from top to bottom. Scripts can calculate values, branch, update definition-local persistent state, call reusable functions, and perform controlled side effects.

1. Event and runtime values are fixed for the logical execution.
2. Validation rejects unknown names, invalid object paths, malformed blocks, and incorrect argument counts.
3. Only the first matching branch of an if block executes.
4. wait(...) suspends this execution without blocking other scripts.
5. Successful global.* mutations are persisted for this definition.

Source layout

• Statements are separated by line breaks; semicolons are unnecessary.
• # starts a comment outside a quoted string or telnet command.
• Strings use double quotes and support \", \\, \n, \r, and \t.
• Keywords and function names are case-insensitive. Lowercase is used throughout this reference.
• Indentation is optional but recommended.

# A minimal chat command
set local.message = lower(trim($chat_content))
if local.message == "!hello" then
  set global.hello_count = coalesce(global.hello_count, 0) + 1
  gs_broadcast(format("Hello {0}! Use #{1}", $player.name, global.hello_count), "say")
end

2. Statements and control flow

set and unset

set assigns a local or persistent global value. Object paths are created as needed. unset removes the selected local or global path and its descendants.

set local.normalized = lower(trim($chat_content))
set global.last_player = $player.name
unset global.last_error

if, else if, else, and end

if $players_online == 0 then
  log("Server is empty")
else if $players_online < $players_max then
  log("Slots are available")
else
  log("Server is full")
end

Calls, actions, and return

Value-returning calls may appear inside expressions. Action calls are complete statements. return is valid inside reusable functions and may return a value or stop with no value.

FOR EACH ... IN ... END

FOR EACH repeats a block once for every item in an array or compatible collection. The item is placed in a local variable for the duration of each pass. Start with the arrays and loops guide before using nested loops.

for each local.player in $players
  log(local.player.name)
end

wait(milliseconds)

wait suspends the current logical execution and resumes from the following statement. Its limits and restart behavior are documented below.

3. Values, operators, and conditions

RATScript values are null, strings, numbers, booleans, objects, and arrays. Function results and variables retain their type. Strings can interpolate scalar values, but arrays must be indexed, joined, or processed with FOR EACH.

null, false, numeric zero, an empty string, and an empty array are falsey; other values are truthy. Arrays and objects support equality checks. Prefer explicit comparisons and exists(...) when optional data matters.

4. Variables, objects, and scopes

Objects use dotted paths, for example $player.position.x. Arrays use brackets, and access can be chained: $players[0].position.x or local.groups[0].players[1].name. Missing optional properties and out-of-range reads evaluate to null. Use exists(...) before relying on optional data.

5. Arrays, indexing, and FOR EACH

An array is an ordered list of values. Use arrays when the same action should be applied to several names, numbers, players, attachments, or other items. Array positions start at zero, so the first item is at position [0].

Create and read arrays

set local.names = ["Alice", "Bob", "Charlie"]
set local.first = local.names[0]
set local.chosen = local.names[local.index]
set local.matrix = [[1, 2], [3, 4]]
set local.value = local.matrix[1][0]

Array items may be strings, numbers, booleans, null, objects, other arrays, or expressions. Empty arrays are written as []. Brackets can be followed by more brackets or object properties, such as $players[0].position.x.

Change a local array

set local.names[1] = "Robert"
set local.names = append(local.names, "Charlie")

Indexed assignment works only through a mutable local.* native array. Replacing an existing item does not change other copies of the array. Assignment cannot grow an array; use append(...), which returns a new array.

Repeat work with FOR EACH

for each local.player in $players
  log(format("{0} is level {1}", local.player.name, local.player.level))
end

The iterator must be a simple local.* name. RAT evaluates the collection once when the loop starts, then runs the body once per item in order. An empty collection runs zero times and leaves the iterator as null; after a nonempty loop, the iterator contains the final item.

Loops may be nested, may call reusable functions, and may contain wait(...). A wait resumes at the same item. break and continue are not currently part of RATScript.

Built-in and compatible collections

count(...), join(...), contains_value(...), bracket indexing, and FOR EACH accept native arrays and compatible indexed collections. append(...) accepts native arrays only.

6. Global runtime variables

These values are supplied to event scripts and scheduled tasks..

7. Event variables

Every event supplies only the tokens declared by its catalog entry, in addition to the runtime variables above. The compact index below lists top-level names; object fields, examples, nullability, deprecations, and templates are in the event catalog.

8. String interpolation

Quoted strings and telnet command text support {{expression}} interpolation. Expressions may include bracket access such as {{$players[0].name}}. Arrays cannot be rendered directly; select an item, use join(...) for scalar arrays, or iterate with FOR EACH. Use format(...) when numbered placeholders make a message easier to read.

log("Player {{$player.name}} triggered {{$event_type}}")
@say "Welcome {{$player.name}}"
discord_send("general", format("{0}: {1}", $player.name, $chat_content))

The complete shipped templates are maintained with their event entries in RAT 5 Events, preventing a second divergent copy in this page.

9. Persistent shared state

global.* is persisted per event definition. Two definitions using global.count do not share the same value. Persistent values may be strings, numbers, booleans, or null. Arrays and objects cannot be stored in global.*; keep them in local.* and persist only the scalar result you need. Unset a path to remove it.

set global.uses = coalesce(global.uses, 0) + 1
set global.last.player = $player.name
set global.last.at = $current_datetime

if global.uses >= 100 then
  unset global.uses
end

Preview reports proposed mutations without committing them. The Events screen in RAT 5 Client can inspect globals and remove a stored global when it is no longer needed.

10. Reusable functions

A reusable function is a separately stored, versioned rat5.v2 script containing one top-level function declaration. Names begin with a lowercase letter and contain lowercase letters, numbers, and underscores.

function announce(message)
  log(message)
  return upper(message)
end

Parameters are read-only call-frame values and may contain arrays. Reusable functions may return arrays, and each call receives fresh locals. Event tokens and the calling definition's globals remain available when the function is context-dependent. Reusable functions may call enabled reusable functions, use FOR EACH, and suspend through wait(...). Direct and indirect recursion are rejected.

RAT tracks event and function dependencies. A referenced function cannot be deleted, and renames update stored references through the event store. Disabled functions cannot be called.

11. Telnet commands and response capture

A line beginning with @ sends one normalized telnet command. Carriage returns, line feeds, and NUL characters are rejected to prevent command injection.

@say "Maintenance begins in 10 minutes"

Capture is permitted only as the complete right-hand side of a set statement. Use @@command for the one-second response timeout or @@(duration)command to override it.

set local.server_time = @@(3s)gettime
log(local.server_time)

Capture waits up to five seconds for the command queue, treats 250 ms of idle output as completion, strips an echoed command, ignores transport noise, and captures at most 64 lines or 16 KiB. Empty responses, timeout, queue failure, unsafe commands, and limit overruns produce structured runtime errors.

12. Built-in functions

The server currently exposes 98 built-ins. User-defined reusable functions appear alongside these at runtime but are installation-specific.

13. Limits and failure behavior

• A single wait(...) is limited to 60,000 ms.
• One logical execution may live for at most 10 minutes and suspend at most 16 times.
• The process accepts at most 256 pending waits. Pending waits are not persisted across restart or shutdown.
• Telnet capture defaults to a one-second response timeout and is capped at 64 lines or 16 KiB.
• Native arrays may contain at most 256 elements and may nest at most 16 levels deep.
• One logical execution may run at most 1,000 loop iterations in total, including nested loops and resumed waits.
• Reusable-function recursion is rejected during validation.
• A runtime error stops the current definition only. Other definitions for the event continue in order.
• Preview simulates side effects and persistent mutations; it does not send live commands or messages.

14. Complete examples

Welcome every currently online player

$players is a snapshot taken when this script starts. This example sends one message per online player.

for each local.player in $players
  gs_broadcast(format("Welcome, {0}!", local.player.name), "say")
end

Persistent chat-command counter

Event type: chat.global_message

set local.message = lower(trim($chat_content))

if local.message == "!status" then
  set global.status_uses = coalesce(global.status_uses, 0) + 1
  gs_broadcast(
    format("Server: {0}; players: {1}/{2}; uses: {3}",
      gs_status(), $players_online, $players_max, global.status_uses),
    "say"
  )
end

Discord reply with a safe mention

Event type: discord.message_received

if equals_ignore_case(trim($chat_content), "!ack") then
  discord_reply(
    $discord_channel_id,
    $discord_message_id,
    format("{0} acknowledged", discord_mention_user($discord_author_id)),
    false
  )
end

Leaderboard announcement

set local.board = player_leaderboard("zombie_kills", 10)
discord_send("general", local.board)

Check whether a player position is in an area

This example can be used with a player event such as player.spawned_in_world. player_in_area(...) checks the player's latest known position when that event runs. It does not continuously monitor the area between events.

if player_in_area($player.id, 1200, 60, -900, 1300, 100, -800) then
  log(format("{0} is inside the protected area", $player.name))
end

Check whether one area fits inside another

in_area(...) compares two boxes rather than looking up a player. The first six coordinates define the box being tested; the final six define the containing box. Touching the boundary is allowed, but partial overlap returns false.

if in_area(
  1210, 65, -890, 1290, 95, -810,
  1200, 60, -900, 1300, 100, -800
) then
  log("The proposed area fits inside the protected area")
end

Safe player lookup

set local.pinfo = player($player.name)
if exists(local.pinfo.id) then
  debug(format("Resolved {0} as {1}", local.pinfo.name, local.pinfo.id))
else
  debug(format("Could not uniquely resolve {0}", $player.name))
end