Objects, flags, and events
Kinds of script object
Section titled “Kinds of script object”| 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\");").
Other objects
Section titled “Other objects”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 fireonReceiveDataoronPathFound. - 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.orserverr.is refused on the client and reported asR-FLAG-READONLY. A server that receives such a write anyway treats it as a protocol violation. findplayer(account).clientr.xreads and writes another player’s flag. Insidewith (findplayer(account)),clientr.andclient.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.
Starting and ending
Section titled “Starting and ending”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).
Events the engine raises
Section titled “Events the engine raises”| 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");}Triggers between client and server
Section titled “Triggers between client and server”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.