Documentation · VBL

Rules for your bots, no coding

VBL is a tiny rule language for the VBL Workspace. Each rule says when something happens, if it matches, then what your bot does. Free on every plan.

The basics

# Lines starting with # are notes for you.
rule "Tip thanks"
when payment
if amount >= 100
then
  im "Thank you for the L${amount}, {firstname}!"
  say "Big thanks to {name}!"
  • A rule starts with rule "name", then one when line, any number of if lines (all must be true), then then and up to 10 actions, one per line.
  • Text goes in "double quotes". Write \" for a quote inside text.
  • Keywords don’t care about capitals. Indenting is optional.
  • Save checks every line and points at mistakes by line number. Only a script without mistakes is saved.
  • Attach a script to the bots it should run on, and switch it on or off any time. The last 20 saved versions are kept so you can restore one.
  • Use Test to see what a rule would do for a made-up message, payment or visitor. Nothing is sent and nothing is charged.

Triggers (when)

TriggerFires when
when imsomeone IMs the bot (Premium bots)
when localsomeone talks in local chat near the bot (Premium bots)
when group / when group "Tenants"a line in one of the bot’s group chats (groups with Group chat on in Manage groups)
when paymentsomeone pays the bot L$
when nearbya new avatar arrives in the bot’s region
when onlinethe bot logs in
when every 30 minutes / every 2 hourson a timer, at most every 15 minutes, while the bot is online
when api "door"your own script or server calls POST /api/v1/bots/{bot}/vbl/fire with "event": "door"

Conditions (if)

Put not in front of any condition to flip it: if not owner.

ConditionTrue when
if text contains "rent"the message contains it (any capitals). Also text is, text starts with, text matches "pattern" (a regular expression)
if ownerit’s you (the bot’s owner)
if in group "VIP"the avatar is a member of that group (the bot must be in it too; the member list is refreshed hourly, so the very first check may say no)
if amount >= 100 / amount between 50 and 500payments only: the L$ amount (also <= = > <)
if time between 18:00 and 02:00the current SL time (Pacific) is in that window — it can cross midnight
if region is "Velvet Isle"the bot is in that region
if cooldown 10 minutesthis rule hasn’t fired for this avatar in that time (seconds, minutes or hours)
if chance 25%randomly, that often
if distance <= 20nearby only: the visitor is within that many metres of the bot, now or when they walk up later (watched for 15 minutes after they arrive)

Actions (then)

ActionDoes
im "text"IMs the avatar the event is about. im "<uuid>" "text" IMs someone else
say "text" / say "text" on 5says it in local chat, or on a channel your scripts listen to
group chat "Tenants" "text"writes in that group’s chat (Group chat must be on)
invite "Tenants" / invite "Tenants" role "Renter"sends the avatar a group invite (Invite must be on in Manage groups)
eject "Tenants"removes the avatar from the group (the bot’s role needs the Eject ability)
notice "Tenants" "Subject" "Message"sends a group notice — Premium bots, one per group every 30 minutes
walk 128 64 / walk 128 64 22walks to that spot in its region
sit "<object uuid>" / standsits on an object / stands up
wait 5pauses up to 30 seconds before the next action
ai_reply standard / ai_reply maturethe bot’s attached AI Brain answers the message (see AI replies)
stopskips the rest of this rule’s actions
continuesee Order

Groups and roles can be written by name or by UUID. A group must be one of the bot’s groups and switched on in Manage groups.

Placeholders

Any text can include {name}, {firstname}, {uuid} (the avatar), {text} (their message), {amount} (a payment), {region} and {bot} (your bot’s name).

Order, stop & continue

  • Rules are checked from the top (scripts in the order you made them). The first rule that matches runs, and checking stops there.
  • When a rule answers an IM, local or group line, the bot’s normal reply (autoreply, scripted replies, AI Brain) is skipped for that line.
  • Put continue in a rule to keep checking the rules below it — and if none of them match, the normal reply still happens.

Limits & safety

  • Up to 20 scripts, 50 rules each, 10 actions per rule. No loops.
  • Every rule waits at least 5 seconds before firing again for the same avatar (longer with cooldown), and a bot runs at most 30 rule fires a minute.
  • Your bots never trigger each other’s rules (or their own).
  • The bot must be online. If an action can’t run — bot offline, group switched off, notice too soon — it’s written to the script’s error log in the Workspace, and the script keeps running.

AI replies & cost

ai_reply uses the AI Brain attached to the bot, exactly as you set it up — a rule can’t add its own instructions. standard is L$1 a reply and mature (Mature Mode) L$2. They’re paid like every AI reply: the bot’s weekly AI credits first, then any AI trial credit, then your balance. If nothing can pay, that one reply is skipped (and logged); the script is never switched off. The safeword and our safety rules always apply.

Examples

# A rental box tells the bot someone rented (Developer API):
#   POST /api/v1/bots/<bot>/vbl/fire  {"event": "rented", "avatar": "<uuid>", "name": "<name>"}
rule "New tenant"
when api "rented"
then
  im "Welcome home, {firstname}!"
  invite "Tenants" role "Renter"

# Greet people who come close, once a day each
rule "Greeter"
when nearby
if distance <= 20
if cooldown 24 hours
then im "Hi {firstname}, welcome!"

# Premium: answer "hours" in local chat, only in the evening (SL time)
rule "Hours"
when local
if text contains "hours"
if time between 18:00 and 23:59
then say "We're open until midnight, {firstname}."

# Premium: let the AI Brain answer IMs from group members, everyone else gets a short note
rule "Members get the AI"
when im
if in group "VIP"
then ai_reply standard

rule "Everyone else"
when im
if not owner
if cooldown 10 minutes
then im "Thanks for your message! Join our VIP group to chat with me."

# Every 2 hours, a reminder in group chat
rule "Reminder"
when every 2 hours
then group chat "Tenants" "Rent boxes are by the door. Pay any time!"

The Workspace also has ready-made templates: tenant welcome, shop greeter and tip thanks.

VBL guide — VelvetBots