Skip to content

OLC Batch API

Kit Oliynyk edited this page Nov 20, 2026 · 4 revisions

TL;DR: /olc is an administrative HTTP endpoint that runs a batch of typed OLC operations without anyone in the game: create, read, edit and delete rooms, mob and object prototypes, resets, area headers and area quests. It drives the same editors as the in-game commands, so the result is what a builder typing those commands would get. Every change goes to the edit journal. Use when: you write a tool or script that builds or edits areas from outside the game, or you need to know what an op does, what it refuses and what comes back. Source of truth: plug-ins/olc/olcops.h and olcops.cpp (OlcOps::apply), plug-ins/olc/olcvalidate.h and olcvalidate.cpp (validators), plug-ins/olc/olcservlet.cpp (endpoint, refusals), plug-ins/servlets/servlet_utils.cpp (servlet_auth_ops), plug-ins/olc/olc.cpp (olc_create_vnum), plug-ins/olc/resetops.h, plug-ins/olc/redit.cpp (room delete), plug-ins/olc/aedit.cpp (area refusals), plug-ins/olc/qedit.cpp (qedit_step_pairing) Verified: 2026-11-18 against dreamland_code 319967e7; validators against PR #2002 (9b73106d), not yet merged

Calling it

POST /olc on the servlet port with a JSON body. Auth is servlet_auth_ops: the administrative ops token. While no ops token is configured, the bot token is accepted too, so set one up on any server that bots can reach.

{"bottype": "telegram", "token": "<admin token>",
 "args": {"ops": [ ... ], "dryRun": false, "verbose": false, "save": false,
          "strict": false, "profile": "agent", "actor": "Builder"}}
Argument Meaning
ops Array of operations, run in order. Strings UTF-8.
dryRun Check every op, apply nothing (see Dry run).
verbose Editor output for every op, not only for ops that changed nothing. Also lists info findings and raises the findings cap.
save After a real batch that changed something, write the changed areas (asave changed). Without it the minute autosave writes them.
strict Validator warnings become errors and every finding is listed (agent profile). See Validators.
profile agent (default) or immortal. Recorded in the journal; decides what a validator finding means, see Profiles. player is refused until it has a field whitelist.
actor Name written to the journal.

The batch stops at the first failing op unless that op has continueOnError: true. Ops before the failure stay applied.

Response

{"ok": true, "dryRun": false, "profile": "agent", "strict": false,
 "changed": [{"kind": "room", "vnum": 12}],
 "errors": [{"op": 3, "error": "..."}],
 "warnings": ["..."],
 "findings": [{"severity": "warning", "check": "text.lang", "kind": "room", "vnum": 12,
               "field": "desc", "lang": "ua", "message": "RU text has no UA version"}],
 "findingsSummary": {"warning text.lang": 1}, "findingsHidden": 0,
 "results": [{"op": 0, "ok": true, "kind": "room", "vnum": 12, "changed": true,
              "data": {}, "xml": "...", "output": "...", "step": 0}],
 "skipped": 0, "saved": ["limbo.are.xml"]}

data, xml, output, step and a result's changed appear only where they apply (no changed on a get or in a dry run). output is the editor's text with colours stripped. A reset op reports its room in changed. skipped counts the ops after a failure. An error that belongs to the whole batch (empty ops, a refused profile, a failed save) has "op": -1. Warnings name trouble the batch left behind, such as a quest whose steps no longer pair up. Findings come from the validators. Nothing is rolled back, for a warning or for an error.

Ops

Every op has kind and vnum. action defaults to cmd. Where a vnum is expected, "$name" refers to a vnum created earlier in the same batch with ref: "name". The same $name also works inside a cmd line, as in "north link $hall".

room, mob, obj

Action What it does
get The prototype as compact JSON in data, built from the area file serializers: {en, ru, ua} for translated fields, arrays for repeated nodes. fields: [...] keeps only those keys. format: "xml" returns the area file XML in xml instead. A room answers XML by default and JSON when fields or format: "json" is given.
create vnum: <n>, or vnum: "next" with area: <area vnum> for the first free vnum of that area. The same checks as the in-game create: inside an area range, builder rights, not taken. Returns vnum.
set field + value [+ lang: en, ru or ua]. Text fields (name, short, long, desc, sound, smell, also in the rudesc, uaname form) go in through the editor's paste, so a value can hold several lines. clear: true empties a text field. An empty value without clear is refused, and so is clear with a value. Any other field runs as the editor command <field> <value>; the field must be the command's full name, not a prefix. A set the editor turns down is a failed op, not a no-op.
cmd One editor command line in cmd, such as "sector forest" or "flags indoors". text fills the editor buffer for a paste form: "rudesc paste", "north rudesc paste", "ed paste fountain".
delete Without a part: the prototype. A mob or object is marked deleted and leaves the area file on the next save; existing copies stay in the world. Parts: exit: "north" (both sides; unlink: true removes only this side), eexit: <keyword> (rooms only), ed: <keyword> (rooms and objects; mobs have no extra descriptions).
put xml: a whole prototype in the area file format, for example the output of a get with format: "xml". A mob or object is created or fully replaced, and its copies in the world follow as after done. A room is only created under a free vnum, and its exits and resets must point at vnums that exist.

A room delete is refused while any of these hold:

  • anybody or anything is in the room;
  • the room has resets;
  • an exit, an extra exit or a mob/object reset in another room leads to it;
  • it is a fixed engine room or a hometown recall, altar or pit;
  • an in-game room editor is open on it, or was opened from it.

It also needs builder rights on the vnum. A room that is a quest step target or has scripted triggers or behaviors is deleted with a warning.

Delete the room's resets and the exits that lead to it first. A deleted room disappears from the vnum lookups, the room lists and the next save. It stays in memory until the next boot, cut off from the world.

reset

Addressed by the room vnum. Same code as the in-game resets command, see OLC-Resets.

Action What it does
get The room's resets as JSON.
add mob [+ max for the world-wide limit, maxRoom], or obj + to: room (default), inside (+ container, limit, count), or a wear location for the mob of the reset before it (none = carried). max, maxRoom, limit and count default to 1; limit: 0 means no limit. after: <n> places the new reset after reset n, 0 = first; without it the reset is appended.
delete number, counted from 1 as resets shows them.
set number, field (flag, rand, tier, wearloc) and value.
randomize Shuffle the room's exits on every reset.

area

Addressed by the area vnum (alist shows it). get returns the header as JSON plus the file name and the area's quests. set and cmd run area editor commands (see OLC): names, message, speedwalk, preposition as text fields, and levels, vnums, flags, authors, security. cmd: "reset" resets the area. The area editor's quest command is refused: use kind quest. Two changes are refused before they are committed: a new vnum range that leaves out a room, mob or object of the area, and a file name another area already saves into. Areas are not created through the endpoint.

quest

Addressed by the quest vnum. See Area-Quests for what the fields mean.

Action What it does
get The quest as JSON, with vnum and area. fields and format work as for mobs.
create vnum: <n> or "next" with area. A vnum another area's quest holds is refused.
set, cmd Quest editor commands: titles, desc, levels, align, flags, prereq and so on.
step step: <n> (from 0) or step: "add", then any of begin and end as {type: mob | obj | room, vnum, trigger}, info: {en, ru, ua}, qp, gold, exp, item, or delete: true. Returns step.
delete The quest. Its scripted step handlers stay and have to be removed separately.

After a real batch every quest it touched is checked for the step pairing rule: step N ends and step N+1 begins on the same target, the end trigger starts with on and the next begin trigger is the same name with post. A break comes back as a warning.

Validators

After the ops, every prototype the batch changed (a reset counts as its room, an area op as the area header) and every prototype a validate op named goes through a chain of read-only checks. A finding is {severity, check, kind, vnum, field?, lang?, message}. The checks set warning or info; the profile can turn warnings into errors.

Check Reports
structure.vnum_range A prototype outside its area's vnum range.
structure.exit An exit or extra exit to a room that does not exist.
structure.reset A reset naming a mob, object or room that does not exist or is deleted.
structure.keyword A mob or object with no keyword; an extra description with an empty keyword, or with no Latin word while it has English text, or no Cyrillic word while it has Russian or Ukrainian text.
structure.keyword_lang A door or extra exit keyword filled in some languages and empty in others.
structure.kw_collision A room extra description and an extra exit share a keyword word, so look reaches only one of them.
structure.eexit_msg Extra exit movement messages: %4 with no noun, a case the noun's declension lacks, an unnumbered placeholder, a trailing full stop, a Russian reflexive ending in the Ukrainian line.
text.charset A byte that is neither ASCII nor a KOI8 letter.
text.mixed_script Latin and Cyrillic letters in one word. Markup glued to a word ({hh1078, %1$G, $n) is stripped first.
text.lang Russian text with no English or Ukrainian version (name, short, long, description).
text.colour A colour opened and never reset with {x.
text.length Visible length over the cap: room name 60, short 100, long line 200, keywords 80, description 2500.
text.kw_in_long A mob's long line or an object's ground line holds none of its own keywords in that language (declension endings allowed).
text.dash Info: a spaced single hyphen; the house dash is --.
power.measure An object's measure in M above the legendary tier window for its level. Weapons (their base dice sit outside the window) and random items are skipped. See Item-Power.
power.spell_price A granted skill or charged spell with no price in fight/spell_value.json, so the measure cannot see it.
power.mob_numbers Mob hit, damage, mana, hitroll or AC that differ from what fight/mob_tiers.json derives: a hand edit that the next rebuild or boot discards.

findingsSummary always counts every finding by severity and check. findings lists the findings of validate targets always, and those of prototypes the batch edited only with verbose or strict: an old area carries a backlog of warnings that would otherwise come back with every one-word fix. Info findings need verbose. The list is capped at 200 (2000 with verbose); findingsHidden says how many were not listed.

validate

{"kind": "room" | "mob" | "obj", "action": "validate", "vnum": N} checks one prototype; {"kind": "area", "action": "validate", "vnum": <area vnum>} checks the area header and every room, mob and object of the area. It applies nothing, writes no journal line and runs in a dry run too. This is the audit entry point.

Profiles

Profile Findings Also
immortal warnings
agent warnings; errors with strict: true
player refused The whole batch is refused until the profile has a whitelist of fields a player may build.

An error sets ok to false, adds a batch error ("op": -1), skips save and answers "saved": []. Nothing is rolled back: the editors change prototypes in place, so the edits stay in memory and the minute autosave writes them like any other change.

Text and refusals

The endpoint takes UTF-8 and converts to the game's KOI8 encoding. Typographic punctuation (ellipsis, dashes, curly quotes, the Ukrainian apostrophe, guillemets, non-breaking space) is mapped to ASCII. Any other character KOI8 cannot hold is refused with its code point and position.

Refused in every op: the editors' own create, done, cancel and pastedone; a bare direction (it would walk the actor through the exit); a paste form without text, which would paste an empty buffer over the field; a command line of 1024 bytes or more. Long text goes through set or text.

behaviors adds to the list instead of replacing it: behaviors X adds X, behaviors -X removes it (a two-word name as -'random weapon'), behaviors = a b sets the list as typed. Behaviors that stay keep their properties.

Dry run

A dry run parses every op, resolves vnums and refs, runs the refusals and stops. A create reserves its vnum for the rest of the batch, so two "next" creates get two vnums and later ops on them pass. Reset adds check that the mob or object exists, the wear location name and the container type. The room delete refusals and the XML parse of a put also run. Field values, reset flags and the area range and file refusals are only checked on a real run, because room commands edit the prototype in place and there is no copy to try them on. A clean dry run is not a promise that the real run passes.

Journal

Every op that changes something is journaled, see OLC, with source api. Reads and dry runs write nothing. An op that runs several editor lines, such as a quest step with a trigger and a reward, writes one line each. Ops that do not go through an editor are journaled as create, delete or put. Reset ops are journaled under kind reset with the room vnum (add mob, add obj, 2 delete, 2 flag, randomize exits), an area reset under kind area as reset.

Pitfalls

  • Saving an area writes the whole file in the game's own format, not only the nodes you touched. On an area file that was edited by hand, expect a large diff.
  • Quest step handlers are scripts. Deleting a quest or a step leaves them behind.
  • An exit link needs both rooms to exist, so create both before link.

See also: OLC, OLC-Rooms, OLC-Resets, Area-Quests, Area-Format.

Clone this wiki locally