Skip to content

Objects, flags, and events

Kind Made by How many Client half runs for this. lasts
Weapon the RC weapon editor; given to a player with addweapon one on the server, plus one per owning client players who own it server this. is shared by all players; client this. is per client
Class the RC class editor none of its own; it runs inside the objects that join it, or as an imported type the client of the object that joined it the host object’s
Database NPC the RC NPC editor; named; placed in a level one players in its level saved; survives restarts
Level NPC NPC ... NPCEND in a level file one per NPC per loaded level players in that level until the level is unloaded
Local NPC putnpc2(x, y, script) one per call players in that level until destroy(), the level unloads, or the server restarts

(@"Name") finds a database NPC or a weapon by name. On the client it finds the local player’s weapon. findnpc(name) finds database NPCs and named level NPCs. Names ignore case (OQ-WORLD-12).

putnpc2(x, y, script) makes an NPC in the level of the caller. The script is compiled once per distinct text, so making many of them is cheap. A usual script just joins a class: putnpc2(x, y, "join(\"projectile_aoe\");").

  • new TStaticVar() makes a plain object that holds dynamic variables. It is collected when nothing refers to it.
  • Request objects (TSQLRequest, TCURLRequest, tasks, path requests) report their result in fields and fire onReceiveData or onPathFound.
  • Windows and controls are client objects. See the API reference.

Flags are variables that outlive a script. The prefix says who may see them.

Prefix Owner Saved Server Client Sent to
client. the player’s account yes read, write read, write that player’s client
clientr. the player’s account yes read, write read only that player’s client
server. the server yes read, write none (reads empty) nobody
serverr. the server yes read, write read only all clients
player.name set on the server the player’s account yes read, write none nobody
player.name set on the client the local player no read, write nobody
serveroptions. the Server Options yes read only none nobody

Rules:

  • A flag value is empty, a number, a string, or an array. Setting a flag to empty deletes it.
  • Do not store an object in a flag. A saved flag stores empty and reports R-FLAG-OBJECT.
  • A client write to clientr. or serverr. is refused on the client and reported as R-FLAG-READONLY. A server that receives such a write anyway treats it as a protocol violation.
  • findplayer(account).clientr.x reads and writes another player’s flag. Inside with (findplayer(account)), clientr. and client. mean that player.
  • Flag names are at most 256 bytes. A value is at most 64 KiB. One account has at most 10,000 flags, and the server has at most 100,000.
  • Changes are saved in the background, at most once a second per account, and on logout and shutdown.

Keep what players must not change in clientr. or in server-only player. fields, and validate everything a client sends.

onCreated() runs when an object’s script is created, loaded, or reloaded, after the statements outside functions. obj.destroy() destroys an object after onDestroy(). Players and weapons cannot be destroyed by a script. onRemoved() is raised when an object leaves its level without being destroyed, for example when the level unloads (OQ-WORLD-15).

Event Where When The object that gets it
onCreated() both the object is created, loaded, or reloaded the object
onDestroy(), onRemoved() both the object goes away the object
onTimeout() both setTimer ran out the object
on<Name>(args) both scheduleevent or trigger the object
onPlayerEnters() both a player enters the level each NPC of the level
onPlayerLeaves() server a player leaves the level each NPC of the level
onPlayerTouchsMe() both a player starts touching the NPC the NPC
onPlayerChats() both a player chats; player.chat holds the text NPCs of the player’s level (server); NPCs and weapons of the local client (client)
onAction<Name>(args) both triggeraction at the position of the NPC NPCs whose box has the point
onKeyPressed, onKeyReleased, onMouseDown, onMouseUp client input client weapons and NPCs
onLevelLoaded() both a level is loaded NPCs of the level
onReceiveData() server a SQL or web request finished the request object
onPathFound() both findpathasync finished the request object
onJoinedClassUpdated(className) both a joined class was saved objects that joined it
onRCChat(cmd, params) server an RC chat line starting with / that the engine does not handle database NPCs
onPlayerLogin(player), onPlayerLogout(player) server a player logs in or out every server script: database NPCs, NPCs of loaded levels, weapon server parts
onActionServerSide(args) server triggerserver from a client the weapon or object
onActionClientSide(args) client triggerclient from the server the weapon or object
onUpdate(), onFixedUpdate() client / both frame and tick events objects with keepalive on

Events that the engine raises run whether or not the function is public. If the object has no function with that name, the event is ignored without an error.

After a player logs in and is placed in the world, the server raises onPlayerLogin(player) on every server script that has it: database NPCs, then the NPCs of the loaded levels, then weapon server parts. The only argument is the player object, which is also in scope as player, so the parameter can have any name. Join player classes and give starting weapons here. Logout raises onPlayerLogout(player) before the player object goes away (OQ-WORLD-16).

// Weapon or database NPC, server part.
function onPlayerLogin(pl) {
pl.chat = "Joined the server.";
pl.addweapon("grab");
}

triggerserver("gui", weaponName, args...) on the client runs onActionServerSide(args...) on the server, with the caller as player. triggerclient("gui", weaponName, args...) on the server runs onActionClientSide on that player’s client. The server must check every argument it gets: count, kind, range, and who is asking. A limit of 32 arguments and 64 KiB per trigger applies, and a player may send 50 triggers a second.

With await, the trigger returns the value that onActionServerSide (or onActionClientSide) returned. Treat the answer from a client as untrusted.

// Weapon server half: every argument is checked.
function onActionServerSide(cmd, amount) {
if (cmd != "heal" || !(amount in |1, 3|)) {
return;
}
player.health = min(player.health + amount, player.maxhealth);
}

Engine version 0.1.0. Built 2026-11-18.