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.

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, and objects. Function results and variables retain their type; interpolation converts values to display text.

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

4. Variables, objects, and scopes

Objects use dotted paths, for example $player.position.x, $discord.author.id, or local.embed.footer.text. Missing optional paths evaluate to null. Use exists(...) before relying on optional fields.

5. Global runtime variables

These values are supplied to event scripts and scheduled tasks. Catalog revision: 330738ea84ce.

6. 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.

7. String interpolation

Quoted strings and telnet command text support {{expression}} interpolation. The expression may be a variable path or a supported expression. 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.

8. Persistent shared state

global.* is persisted per event definition. Two definitions using global.count do not share the same value. Values may be strings, numbers, booleans, or nested objects. 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.

9. 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. Each call receives fresh locals, while event tokens and the calling definition's globals remain available when the function is context-dependent. Reusable functions may call enabled reusable functions and may 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.

10. 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.

11. Built-in functions

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

12. 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.
• 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.

13. Complete examples

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)

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