Ritual API

Rituals are small Lua scripts that add commands, react to events, and run on schedules on your server. This is everything you can use inside one.

Introduction

A Ritual is a script you install on a server. Inside it you register three kinds of things:

Building block	What it does
`command()`	Adds an in-game chat command like `/home`
`on()`	Runs when something happens — a player joins, chats, dies, or gets a kill
`every()`	Runs on a repeating schedule, e.g. every 10 minutes

You get helper objects — server (do things), storage (remember things), and config (settings the owner can change without editing code).

Quick start

The smallest possible Ritual — a /ping command:

command("ping", function(ctx)
  ctx.reply("Pong, " .. ctx.player.name .. "!")
end)

Install it, then any player typing /ping in chat gets a reply. That's a complete Ritual.

Registering

command(name, handler)

Adds a /name chat command. The handler receives ctx.

command("kit", function(ctx)
  server.give(ctx.player, "resourceWood", 50)
  ctx.reply("Here's some wood.")
end)

on(event, handler)

Runs when an event fires. Events: "join", "leave", "chat", "kill". See Events.

on("join", function(ctx)
  server.say("Welcome " .. ctx.player.name .. "!")
end)

every(interval, handler)

Runs on a repeating timer. Interval is a string: "30s", "10m", "2h", "1d".

every("15m", function()
  server.say("Don't forget to vote for rewards!")
end)

The ctx object

Passed to command and on handlers.

Field	Description
`ctx.player.name`	The player's name
`ctx.player.id`	Their platform id (stable, e.g. `Steam_7656…`)
`ctx.player.eid`	Their entity id while online
`ctx.args`	Command arguments — `ctx.args[1]` is the first word after the command
`ctx.message`	The raw chat message (on `chat` events)
`ctx.reply(msg)`	Send a message back to chat

-- /give <item> <amount>
command("give", function(ctx)
  local item = ctx.args[1]
  local n = tonumber(ctx.args[2]) or 1
  server.give(ctx.player, item, n)
end)

server.* actions

Everything you can make the server do. A player argument can be ctx.player, a name, or a platform id.

Function	Does
`server.say(msg)`	Broadcast a message to everyone
`server.pm(player, msg)`	Message one player
`server.give(player, item, n)`	Give `n` of an item (online: dropped at them; offline: added to their bag)
`server.teleport(player, x, y, z)`	Teleport a player to coordinates
`server.kick(player, reason)`	Kick a player
`server.addCurrency(player, n)`	Add (or subtract, if negative) currency
`server.balance(player)`	Returns the player's current balance
`server.command(raw)`	Run any raw console command
`server.players()`	Returns a list of online players (`{id, name, eid}`)

storage

Remember things between runs — homes, cooldowns, counters. Each Ritual has its own private storage. Values can be numbers, strings, tables, etc.

Function	Does
`storage.get(key)`	Read a value (returns `nil` if unset)
`storage.set(key, value)`	Save a value
`storage.del(key)`	Delete a value

-- count how many times each player says hi
command("hi", function(ctx)
  local n = (storage.get("hi:" .. ctx.player.id) or 0) + 1
  storage.set("hi:" .. ctx.player.id, n)
  ctx.reply("You've said hi " .. n .. " times.")
end)

config

Settings the server owner edits in the ⚙ Configure panel — no code. Declare defaults in the Config (JSON) box, then read them as config.name.

Config JSON:

{ "amount": 250, "message": "Welcome!" }

Lua:

server.addCurrency(ctx.player, config.amount)
server.say(config.message)

Anything you put in the Config JSON automatically becomes an editable field in the ⚙ Configure form — numbers become number inputs, true/false become checkboxes, lists become multi-line boxes.

Events

Event	Fires when	ctx has
`"join"`	A player connects	`ctx.player`
`"leave"`	A player disconnects	`ctx.player`
`"chat"`	A player sends any chat message	`ctx.player`, `ctx.message`
`"kill"`	A player kills a zombie	`ctx.player`

-- pay 5 coins per zombie kill
on("kill", function(ctx)
  server.addCurrency(ctx.player, 5)
end)

Helpers

Function	Does
`now()`	Current time in seconds (for cooldowns)
`log(msg)`	Write to the server console (for debugging)
`math.random()`	Standard Lua — random 0–1 (great for gambling/loot)

Full examples

Homes — /sethome & /home

command("sethome", function(ctx)
  local p = server.players()[1]  -- (position helper coming; use console for now)
  storage.set("home:" .. ctx.player.id, ctx.player)
  ctx.reply("Home set.")
end)

Daily reward with a cooldown

command("daily", function(ctx)
  local last = storage.get("last:" .. ctx.player.id) or 0
  if now() - last < 86400 then
    return ctx.reply("Already claimed today.")
  end
  storage.set("last:" .. ctx.player.id, now())
  server.addCurrency(ctx.player, config.amount)
  ctx.reply("You got " .. config.amount .. " coins!")
end)

Coinflip gamble

command("flip", function(ctx)
  local bet = tonumber(ctx.args[1]) or 0
  if server.balance(ctx.player) < bet then return ctx.reply("Too poor.") end
  if math.random() < 0.5 then
    server.addCurrency(ctx.player, bet);  ctx.reply("You won!")
  else
    server.addCurrency(ctx.player, -bet); ctx.reply("You lost.")
  end
end)

Tips & limits

Use a dot to call API functions: server.say(...), storage.get(...), ctx.reply(...).
Events arrive within a few seconds — great for teleports, rewards, moderation. Not frame-perfect.
The sandbox blocks file/network access (os, io, require) for safety. Everything you need is in server, storage, config.
Errors show up in the server console (log() helps) — the Ritual keeps running.

← Back to the panel