This is the reference for a program that drives a character: the tools, the events, the HTTP routes and the MCP server.
A session is one character in the world. It starts from uoterm connect,
uoterm populate, uoterm play, a login in the web client of uoterm web,
POST /v1/sessions, or the runtime tools connect and character_create.
You drive it with the CLI (see the command reference in the
README), with HTTP, or with uoterm mcp.
A tool that acts answers at once with an action_id. You learn the end of
the act from an event:
arrivedorpath_failedfor a walk.job_endedfor a hunt, a walk, a loot, a bank deposit, a script or an agent job. Its text is<job>: done,stopped, or the reason.job_failedwhen a job gives up.target_requested,gump_openedand the others for what the shard sends.
A tool call that takes more than 8 seconds fails with tool timed out.
An agent must not miss what happens between its calls. So it runs one loop
around next_event. The driver playbook says in what
order to act on what comes back.
next_event answers the moment something important happens. With nothing,
it answers after timeout_ms (default 5000, most 7000) with no events. The
answer holds events and state, and gumps when a gump is open.
Events wait in the session for you. When you are slow, the next call gives
you all of them, in order, 50 at most per call. The session keeps the last
256. missed counts the events it dropped before you asked. It drops the
busy kinds first.
| Kind | Events |
|---|---|
| Control | control_taken: a human took the character in a play window (the native window or the web client). Your goal, job and script are stopped. Each acting tool is refused with a human has control of the character; look only, and wait for the control_released event. You may still look (observe, look_around, find_*, next_event). control_released gives the character back: read observe again, because the human may have moved her. state.human_control and observe.human_control say which it is now. Control also comes back by itself after 90 seconds with no human act. |
| Danger | died, low_health (health under half), damaged, enemy_near, combatant_changed, pk_flag. died also comes when another mobile dies; its text is then corpse <serial>. |
| Waits for an answer | target_requested, gump_opened, prompt_opened (answer with prompt_answer), trade_opened, party_invite (answer with party), shop_opened, context_menu_opened and menu_opened (observe holds the goods, the lines or the entries), race_change_opened (answer with race_change). |
| Chat | spoken_to. Also read state.unanswered. Answer with reply. See Talking to players. |
| Jobs | job_ended: a hunt or walk job handed back (hunt: <reason> or walk: <reason>). See playbooks/hunt.md and playbooks/walk.md. job_failed: a loot, deposit, gather, ress or agent job gave up, with the reason. |
| Your own task | item_added, arrived, path_failed, lift_rejected, play_along_ended, resurrected, gump_closed. map_changed: a moongate or a recall took her to another map. The old map's mobiles and items are gone, and a walk or follow there is dropped. buff_changed: a buff came on or went off, by icon. system_message: the shard's own words, such as "that is too far away". skill_changed (skill 27 70.3 (+0.1): the skill number, its value and the change). stat_changed (strength 51 (+1)). ability_changed: the armed weapon move is spent, or a stance came on or went off. quest_arrow (shown at x,y or removed). map_opened: a map item opened; watch shows it under maps. |
| Link | disconnected: the link to the shard dropped. The session logs in again by itself after 5 seconds, then after longer waits, up to 60 seconds. Meanwhile each call is refused with words that say so. The reconnect setting (uoterm.toml, and the session create body) turns this off. A logout ends the session for good. |
| Busy | sound, effect, animation (each swing, cast and bow of every mobile in view), item_deleted and member_positions. You get them only when you ask with ambient: a list of kinds, such as ["sound"], or ["all"]. |
The session also logs speech, container_opened and logged_in, but
next_event does not return them.
A death shows the death screen: you get died, state.dead is true, and
the session leaves war mode.
state holds:
hits,manaandstamwith their maximums,war,dead,location,combatant.enemies_near: the 5 nearest mobiles you may fight, within 10 tiles, not party members or friends.unanswered,chat_mode,target_cursor.pack:items,weight,weight_max.doing: thegoal, the tile she iswalking_to, whom she isfollowingorplaying_along_with, the corpse she islooting, whether she isbanking, the firstscriptthat runs and the slots of all of them inscripts, andjob(hunt or walk, with its phase).
job_start with replace true stops the old job first (job_ended reason
stopped), then starts the new one.
Read doing before you answer a player. Her words must match what she does.
When she already follows the player, say "right behind you", not "I will
stay here". When she is already at the cows, do not say "lead the way".
Never say she will do something unless you start it in the same step.
When another character says your character's name, the session sends a
spoken_to event. Each tool result then carries these lines in
unanswered, whatever the tool, so a busy agent still sees them. A line
leaves the list when it is answered (see reply below), or after three
minutes. observe lists the lines of the last three minutes in
spoken_to, answered or not, 5 at most.
Each line has the speaker's serial and name, the text, the channel
it came in (say, whisper, yell, party, party_private, guild or
alliance), and asks_if_bot. Party, guild and alliance lines count even
when the speaker is out of sight. The name counts only as a whole word:
"Tamara" does not name "Mara". System lines, spell words and your own lines
never count. The answer_when_named setting turns all this off.
To start a line yourself, use say with channel: say (the default),
yell, party, guild or alliance.
Answer with reply. It sends your text back in the channel the line came
in. A yell gets an answer in a normal voice. A private party line gets an
answer to that member only. Give to, a name or a serial, to pick the
speaker when more than one waits. Without it, the newest line is answered.
A reply answers that speaker's lines only. A say, whisper or emote
answers every waiting line said nearby. A party, guild or alliance line
answers the lines of that channel.
A result with unanswered lines also has chat_mode, which observe shows
too: basic or play_along.
The listen_range option (AGENTS.md) makes a line said aloud
by anyone that many tiles away or nearer count as said to the character.
It is off by default. The ignore_list tool (list journal) hides lines by
speaker or words: they do not count as spoken to, and observe,
journal_search and wait_journal leave them out.
Answer with reply the way a player would. What you may agree to depends
on chat_mode:
basic(theplay_alongsetting is off): answer in a few friendly words, and say no to every plan: hunting, following, a party, a trade, "come here". For example "not right now, busy" or "maybe later". Keep doing your own task. The client refuses thefollowtool, and the script commandpartyaccept, for a player who asked in chat, unless that player is on the friends list.play_along: you may say yes to the plans the persona lists (see PERSONAS.md). Withparty, the client joins the party of a player who spoke to you. Withfollow, you mayfollowthem. Withfight, you mayattackwhat they fight. The client refuses afollowthat is not listed. It does not checkfight.observeshowsplaying_along: the player and the minutes left. When the persona's time is up, or the character is hurt past its play-along risk, the character stops following and you get aplay_along_endedevent. Say a short goodbye and go back to your own task. Talk the wayreply_stylesays, when it is given.
In both modes:
- Keep it short and plain. One line is enough.
- Stay in character as a player. Never bring up AI, bots, programs or "a game" on your own.
- When
asks_if_botis true, laugh it off ("lol, you're funny"), dodge it ("too busy chopping to chat"), or just keep working. Never flatly say "I am a real person" or "I am not a bot". - Never say the same line twice. Change the words each time. The session refuses a line said a short time before, and a reply that comes too soon after the last one.
observe shows nearest_bank: the town, the location where its banker
stands, and the dist. It is the nearest bank on this map within 400
tiles. The banks are those of the standard towns on every map. A shard with
its own towns has other banks; find them by their bankers (find_mobiles
with name banker). The bank goal walks to nearest_bank and ends
there.
find_landmarks reads named places from the marker file set in the config
(markers): gates, banks, towns. With no marker file, it fails with words
that say so. You can filter by:
name: part of the place name.kind: the marker word, such asbankormoongate. For a file with no marker words, part of the name.map: the one underfoot by default.distance.closest(a kind): only the nearest place of that kind.
Each place has its map, location, dist (only on the current map) and
kind. When the map underfoot has no match and the call names no map, the
answer is {places, note, elsewhere}: the matches on the other maps (10 at
most), so you know to travel there first.
landmarks_info says what marker data is loaded: loaded, count, and the
count on each map and of each kind. move_to and route take name to walk
to the nearest landmark of that name.
A town moongate is not in the map files. The shard puts it in the world as a
live item. So walk to the landmark, then find_items with the gate graphic
(blue 0x0F6C, red 0x0DDA) to find the gate that stands there. Step onto
it, and answer the moongate gump.
A moongate fires when you step onto its tile, not on use. On most shards a
second use while you stand on the gate does nothing. If the gump did not
open, step off the tile and back on.
Dungeon teleporter pads are not in the map files either. The character
learns a pad the first time she uses one: when she steps onto a tile and is
moved at once on the same map, the session keeps that tile and where she
landed. After that, a move_to whose goal she can reach only across a
learned pad walks to the pad by itself ({partial:true, via:"teleporter"}).
Step on it, and call move_to again from the far side. Moongates are not
learned as pads.
A gump is a window the shard opens: a moongate, a bank question, a vendor
menu. observe gumps and the next_event answer show each open gump in
words. The text numbers are read from the client files.
texts: the words that are not a label.buttons: eachidwith thelabelbeside it. A button withto_pageonly shows another page.choices: each round or square button with itsswitch, itslabel, and thesection, the label of the page it is on.
For example, to take the moongate to Moonglow on Trammel, tick the choice
with that label and section, and press OKAY: gump_respond with button 1
and switches [0].
When another player opens a secure trade, you get a trade_opened event, and
observe shows trade: the player, what theirs and mine hold, and
i_accept and they_accept. Read what they offer before you agree.
trade_acceptticks your accept box.accept: falseunticks it.trade_cancelcloses the trade.trade_goldsets the gold and platinum you offer.
A change to either side clears both accept boxes, so accept again after it.
Several trades can be open at once. observe trades lists each one, the
newest last, with serial (the other player) and box_serial (your box of
that trade). trade is the newest. trade_accept, trade_cancel and
trade_gold take trade (the other player, or a box of the trade) to pick
one. Without it they act on the newest.
A shard says at login whether it sends property lists, the tooltips that name every object. When it does not, the session reads names the way a player does, one every half second. It asks for the name of each mobile with no name, as the client asks for the name it shows over a head. It clicks each item with no name once, and takes the name the shard shows over it.
What a click tells of an item comes back in properties, in the form of the
shard's era. On the oldest shards, these are the label lines, which say it
all in words: for example a vanquishing katana crafted by Bob, or a bag's
name and then what it holds. On later shards, it is the click info: its
name, its maker, its quality and magic, whether the magic is known, and its
charges. properties asks again with a new click when the last answer is
more than 10 seconds old, and never more than once a second for one object.
| Tool | Needs | Result |
|---|---|---|
observe |
a session | self_state, the radar, the journal, mobiles, items, pending_target, gumps, doors, buffs, party, prompt, forbidden (assistant features the shard forbids), abilities (the armed weapon move, and the spells and stances that are on), tracked_members (party and guild members out of sight, after track_members), and latency_ms (the last round trip to the shard). size (5 to 41, default 21) sets the radar width. GET /v1/sessions/{id}/state always uses 21. |
find_mobiles |
in the world | Filters: name, graphic, distance, notoriety (innocent, friend, gray, criminal, enemy, murderer, invulnerable or any), species (read from the body, so a named orc is still an orc), in_sight, z_min and z_max. name also matches the title, so banker finds "Kate the banker". On a shard with no property lists the title comes from the label of a click, so single_click a mobile first. Each mobile has its title, species, notoriety, hits_percent when known, war, hidden, poisoned, dead, in_sight (by the sight_mode option), npc (a guess: no human body, or nobody can harm it), multi (the house or boat it stands on), and what it wears (worn). |
find_items |
in the world | Filters: graphic, graphics (any of a list), hue, container, name, distance, x with y (the items on one tile), z_min and z_max. Each item has its location, dist, hue, movable (a player may lift it), is_container, and multi (the house or boat it is, or stands on). |
find_tiles |
map files, or the mock grid for the map underfoot | Map tiles of a kind in an area of any map, nearest first, one page at a time. What: group (water, trees, ore, forge, anvil, loom, oven, mill), graphics (land ids or static graphics), flags (tiledata flag names, all needed: wet, impassable, surface, wall, door, roof, foliage and the rest), name (a word of the tiledata name). Where: x, y and radius (default: the character and 12, most 64), or the box x1, y1, x2, y2 (at most 129 tiles on a side); map; layer land, statics or both; z_min and z_max. page and page_size (default 50, most 200). Each tile has x, y, z, layer, graphic, name, flags and dist, with total and pages. |
map_tile |
map files or the mock grid | Everything on the tile x, y of any map: land (id, name, z, flags), each static (graphic, name, z, height, hue, flags), and on the map underfoot the items and the multi_parts on it. Also walkable, door, and the standing z from the height z (default: the character's). |
multi_parts |
a house or boat in view | serial gives every part of one house or boat. x and y give the parts of any of them on that tile. A house a player designed gives the parts the shard sent. Each part has multi, graphic, name, x, y, z, height, flags and designed. One page at a time. |
find_entrances |
map files | The ways into a dungeon round a spot: each run of stair or ladder statics once (with its tiles), the teleporter pads the character learned, and dungeon or cave landmarks. x, y, radius (default: the character and 32, most 64), map. Nearest first. |
find_landmarks |
in the world | Named places from the marker file. See Landmarks. |
landmarks_info |
a session | The marker data loaded: loaded, count, maps and kinds with their counts. |
skill_gains |
a session | The skills gained this session. For each one: gained (points), changes, value and per_hour, and the newest changes in recent. skill narrows it to one. clear true starts the record again. |
look_around |
in the world | The surroundings in words: the ground underfoot, named furniture and walls, loose items and people. radius is optional. |
line_of_sight |
in the world | Whether one point sees another, as the shard judges a shot or a spell. To: serial, or x, y and z. From: the character's eyes, or from (a serial), or from_x, from_y and from_z. mode picks the rules: runuo (also modernuo and servuo; the default of the sight_mode option), pol (a window lets sight through), or sphere (one point on each tile crossed; walls and pieces that stop a shot block, windows do not). trace true gives every point of the line with what stops it (land, piece with its flags, off_map, edge_of_world, too_far). Without it, blocked_at names the first stop. Answers {in_sight, from, aim, mode}. |
route |
in the world | Plans the walk move_to would take, with the same choices (x, y, z or name; accuracy, avoid, open_doors, roads). It says if the spot is reachable, where the route ends_at, the steps, the route tiles, or why not, and the search: nodes opened, ms, and flat when the heights had to be ignored. It takes no step. |
journal_search |
a session | Journal lines that match query. With since, only newer lines; the answer is {last_seq, lines}. |
can_walk |
map files or the mock grid | {walkable}, and why when it is not: off the map, a mobile stands there, the shard refused it lately, a door, a named static, a building or an item, the ground, or nothing to stand on at that height. |
properties |
in the world | serial. The tooltip lines of one object, and entries: the same lines as the shard sent them, each a cliloc text number with its arguments, so a caller can read a property by its number in any language. When the session has none, it asks the shard, so the next call has them. |
observe also holds what the shard has open for the character: shop (the
goods and prices of a buy or sell list), context_menu (its lines), menu
(an old-style menu), book (its pages), and paperdoll (the last paperdoll
the shard opened: serial, the text at its top, and a seq that grows
with each one; the worn items are in that mobile's equipment). It holds
what the character knows: skills (those trained or locked, with value,
base, cap and lock), spellbooks (the spells of each book the shard has
sent), and doing.last_walk (how the last walk ended).
| Tool | Needs, and notes |
|---|---|
say, whisper |
In the world. The persona refuses *emotes* and empty text, and say has a rate limit (see PERSONAS.md). A line has at most 128 characters. say takes channel: say (default), yell, party, guild or alliance. hue sets the colour of the line. The default is the speech_hue option, else the client's own. |
reply |
A line waits in unanswered. text, and to to pick the speaker. See Talking to players. |
emote |
allow_emote in the persona. |
move_to |
In the world. x and y (and z), or name (the nearest landmark of that name). Choices: run (true runs, false walks; the default goes by stamina and danger), accuracy (stop within that many tiles, up to 18; the goal may then be a tree or an anvil), open_doors (default true; the shard's rules and the no_doors_hidden option still apply), avoid (a list of {x, y, radius} areas and {serial, radius} creatures to keep away from; r is a short form of radius, and the default is 3; a creature is read where it stands at each plan), roads (default true: grass and forest cost a little more, so the route keeps to roads), exact (fail instead of walking as near as a route goes). The answer names heading_to and the route search (nodes, ms, steps, flat). When one route cannot reach the goal (a wall or a high spot, a gap with a gate or a pad, or too far), it walks to the nearest spot it can reach on the way and answers {partial:true, goal, heading_to, reason}. Call move_to again from there. When a mobile or a refused step blocks the route a few steps ahead, the walk goes round it with a short detour and keeps the rest of the route. |
walk |
In the world. direction (n/ne/e/se/s/sw/w/nw; dir also works), running (run also works), hold_ms (0 = one step). slide true lets a held walk go on beside a wall. force true sends one step the map blocks. open_doors true first opens a shut door on the tile ahead, as a player's client with auto open doors does. |
open_door |
In the world. Opens a door on one of the 8 tiles around you. The character turns to it by itself (0x12/0x58). |
follow, stop |
follow needs a mobile serial. stop ends the follow, the travel, and a hunt, walk, loot or deposit job, as cancel_goal does. |
logout |
In the world. Sends the logout request. A shard may hold it until she is somewhere it allows, such as an inn or a house. The session closes the link when the shard lets her go. then_play (a character of the account) logs in as that character in the same session once the shard lets this one go. Without it, the session ends. |
use, single_click, attack, war_mode |
serial. A call with none is refused. use also takes who last. war_mode takes on. |
lift, drop, equip, unequip |
An item serial. lift takes amount. equip takes layer (default: the one-handed layer). equip with who last wears the last weapon put away, or asks the shard for the last weapon it remembers. drop takes dest: a container, or a mobile to give to. With none it drops at your feet. x and y give an exact place in the container, or a ground tile with z when there is no dest. unequip needs a layer. It refuses layer 0, the backpack, and layers above the bank layer. An empty layer answers layer empty. |
cast, use_skill |
In the world. spell or skill is needed, by number or by name (greater heal, hiding). cast takes target, a serial or self, and answers the spell's cursor with it when it comes. It takes book, a spellbook serial, to cast from that book. A skill no button uses is refused. |
wait_target |
Nothing. |
target |
serial or who answers the cursor that is open. With no cursor open, the target waits up to 5 seconds for the next one. x and y (a ground target) need a cursor that is open. A call with no arguments cancels the cursor. |
open_container, loot, trade_offer |
serial. A call with none is refused. open_container also takes who last. loot sends job_ended loot: done at the end. |
deposit |
A bank box is open: say bank beside a banker first, or the call is refused. It moves the pack into the box, one item a tick. graphic banks only those. It sends job_ended deposit: done. |
vendor_sell |
A vendor near: vendor_name and graphic. It says sell to the vendor and sells every pack item of that graphic from the list that comes. |
vendor_buy |
vendor, item (the serial of a row of observe shop) and amount (default 1). Open the buy list first. |
wait_journal |
A session. q and timeout_ms (default 5000, most 7000). Waits for a new journal line that holds the words. |
prompt_answer, prompt_cancel |
A prompt or a one-field dialog waits (prompt_opened). text is the answer. A prompt takes at most 128 characters. |
party |
In the world. action invite (with serial), accept or decline the invite that waits, leave, kick (with serial), or loot (with on). The loot choice shows in watch party_can_loot. It goes back to false when the party ends. |
mobile_status |
In the world. serial. Asks for the mobile's status, as a click on its health bar does. Its hits come back in find_mobiles. close true tells the shard its status bar is shut. A shard sends the mana and the stamina of a party member (and some shards of a pet). They show on that mobile as mana, mana_max, stam and stam_max. |
gump_respond, gump_close |
An open gump. gump names the gump id to answer (the oldest open one when left out). button is a button id. switches are the choices to tick. texts are the typed fields as [{id, text}] (observe lists them under entries). Button 0 closes. A button or switch that is not on the gump is refused. |
context_menu, close_menu |
serial alone asks for the context menu. Its lines come in observe context_menu, with a context_menu_opened event. With index, it picks that line. With cliloc, one call asks and picks. close_menu closes it with no pick. A shard with no context menus says so. |
shop_checkout, shop_close |
A shop list is open (observe shop). items is [{serial, amount}]. It buys or sells by the kind of list. |
dye |
A dye tub asks for a colour (watch dye). hue is the colour. |
menu_pick, book_close |
An old-style menu or a book is open (observe menu, book). index counts from 1. None walks away. |
book_read |
A book is open. page from 1: its lines when the shard sent them. Else the session asks the shard for the page (asked true), and the next call has it. |
book_write |
A book is open. title and author name it. page (from 1) and text write one page; a line break parts its lines. |
board_read, board_post, board_remove, board_close |
A bulletin board is open: use the board first. watch shows it under board with its posts. board_read takes message, and the lines come in posts[].lines. board_post takes subject, text and, for an answer, reply_to. board_remove takes message. |
map_pin, map_close |
A map item is open: use the map first. watch shows it under maps with its pins and may_plot. map_pin takes x and y in pixels of its picture; action move with pin (its place in the list, from 0) and x, y; action remove with pin; or action clear or edit. map_close takes serial, or none. |
profile |
In the world. serial asks for the profile a player wrote about a character. text writes your own. The words come back in watch under profiles. |
house_edit |
The house designer is open (watch designing). action add, remove, stair, roof or remove_roof with graphic, x, y (and z to remove); floor with level; and clear, revert, commit, exit, backup, restore, sync (the shard sends the design again). The parts to build with are in watch house_parts. |
house_content |
In the world. show true or false: whether the shard shows what stands inside public houses. |
help |
In the world. Asks the shard for its help menu. It answers with a gump. |
chat |
In the world. action open (with name), join (with channel and password), create (a new channel, with channel and password), say (with text), leave. watch shows the chat under chat. |
open_spellbook |
In the world. kind magery, necromancy, chivalry, bushido, ninjitsu, spellweaving or mysticism. Its spells come in observe spellbooks. |
tip, quest_arrow |
A tip of the day or a quest arrow is shown. tip takes next (false for the tip before). quest_arrow clicks the arrow; right true clicks it with the right button. watch shows them as shard_tip and quest_arrow. |
boat_move |
You pilot a boat. direction, and speed stop, slow or fast (default). |
track_members |
In a party or a guild. who party or guild. The places come in observe tracked_members, with a member_positions event. |
race_change |
A race change is open (race_change_opened). observe race_change has the race, female, hair_styles and beard_styles with their graphic and name, skin_hues and hair_hues. hair and beard are graphics (0 for none). skin_hue, hair_hue and beard_hue are hues from the lists. Each one you leave out takes the first choice. cancel true says no. |
trade_accept, trade_cancel, trade_gold |
A trade is open. See Trades. trade_gold takes gold and platinum. |
virtue, virtue_gump |
In the world. virtue invokes one of the eight virtues by name: humility, sacrifice, compassion, spirituality, valor, honor, justice, honesty. Honor, sacrifice and valor go as the virtue macro. The others go as a press on their picture in the virtue gump. virtue_gump asks for the virtue gump of serial, or of the character. |
skill_lock, stat_lock |
In the world. skill (number or name) or stat (str, dex, int), and lock up, down or locked. |
rename |
A pet in view: serial and name. |
set_ability |
In the world. ability primary, secondary, stun or disarm. on false clears it. |
emote_action, fly, menu_button |
In the world. emote_action plays a body action (action bow, salute). fly takes off a gargoyle, or lands with on false. menu_button presses the paperdoll's quests or guild button (which). |
target_resource |
A harvest tool: tool and resource (ore, sand, wood, graves, red mushrooms), with no cursor. |
use_type |
In the world. Double-clicks the first item of graphic, of hue (default: any), in source (backpack by default, ground, world, or a container serial), within range on the ground. |
use_on |
In the world. Uses item on the mobile target with no cursor, as a bandage is used. It takes the time of one act. |
catch_bag |
In the world. serial sets the container loot goes into in place of the backpack. clear true clears it. With neither, it says which. Saved for each character. |
mount, dismount |
mount rides serial, the remount agent's mount, or the nearest pet of the character's that can be ridden. dismount gets off. War mode goes off first, so the double-click is no attack. In a fight both are refused. |
attack_nearest |
In the world. Attacks the nearest mobile in sight (by the sight_mode option) that may be harmed without a crime: never an innocent, a friend, a pet or a party member, or one nobody can harm. notoriety (gray, criminal, enemy, murderer), species, name and distance narrow it. The shard's rule on closest targets is obeyed. |
ignore_list |
A session. list gumps or journal; action add, remove, clear or show (default); value a gump id or words. An ignored gump is left out of observe and does not wake next_event. An ignored line (by speaker or words) is left out of observe, journal_search and wait_journal, and does not count as spoken to. Saved for each character. |
set_goal |
In the world. goal: see Goals. |
cancel_goal |
A session. Ends the goal, and stops a hunt, walk, loot or deposit job (job_ended reason stopped). |
set_persona |
A session. A persona as JSON (see PERSONAS.md). typo_rate is clamped to 0.0..=1.0. |
jobs, job_start, job_stop |
A session, in the world, a job that runs. Hunt: job hunt, with include or avoid (not both). Walk: job walk, x and y or name, watch. replace true stops the old job (job_ended stopped) and then starts the new one. The job hands back with job_ended. See playbooks/hunt.md and playbooks/walk.md. |
set_goal takes goal. A goal is a simple plan the session runs on each
tick. Before the goal, the session always takes care of the character
first: it runs away when health is under the persona's flee share, uses
bandages and potions, and fights back anyone who hit her in the last 30
seconds. A ghost says "i am dead", unless the goal is ress.
| Goal | What it does |
|---|---|
idle |
Nothing more. A name UOTerm does not know also gives idle. |
gather (or chop, lumber) |
Finds the nearest tree within 12 tiles, walks beside it, uses the axe the character carries and aims at the tree, one swing at a time. A tree the shard says is empty is left for 20 minutes. With no axe, no tree near, or a tool that does not work on a mount, the goal ends with job_failed. |
mine |
The same with a pickaxe or a shovel, on rock and cave floors. |
hunt |
Starts the hunt job with empty lists (see playbooks/hunt.md). |
travel |
Walks to x, y (and z). With no spot, it walks to the nearest bank. It ends with arrived. On ground that may have hostiles, use the walk job instead. |
flee |
Walks away from what threatens the character. |
bank |
Walks to the nearest bank within 400 tiles, from the banks of the standard towns on every map, and ends there with arrived. With none that near, or on a shard with its own towns, set_goal refuses, and the agent must find a banker. |
shop |
Uses a nearby innocent mobile, else walks to the bank when it is near. |
social |
Says yo. |
ress (or res) |
A ghost walks to a healer in view and takes the offer to live again. With no healer in view, it walks to the nearest healer of the marker file, else to the nearest bank, where towns keep one. It ends with job_ended ress: alive when the character lives. |
Any goal other than hunt stops a hunt or walk job that runs.
SCRIPTS.md explains the script language and its tools.
AGENTS.md explains the agents, hotkeys and recording, and the
[options] that change how tools work (sight_mode, listen_range,
catch_bag, the ignore lists, speech_hue and the others).
| Tool | Needs | Result |
|---|---|---|
run_script |
no script in that slot | name or text, in a slot of its own (slot). Up to 8 scripts run side by side. loop, for and iterations as in SCRIPTS.md. |
stop_script, script_status, list_scripts, script_read, script_save |
a session | See SCRIPTS.md. |
hotkeys, hotkey |
a session, in the world | List by group or name; press by name. |
agents, agent_set, agent_on |
a session | The settings; replace the settings of an agent (or its list); switch it on. |
agent_run, agent_stop |
in the world | Run a job once: organizer, restock, dress, undress, autoloot. |
damage_meter, target_filter |
a session, in the world | action start, pause, resume, stop, report; pick with the filter name. |
record_macro |
a session | action start (with name), stop (saves), cancel. |
These tools belong to the runtime, not to a session. Before a login there is
no session to call, so they take no session_id.
| Tool | Result |
|---|---|
characters |
The character list of an account: slots (each slot, name and empty) and start_towns (index, town, building). No character is played. |
character_create |
Makes a character and logs in as it. Answers session_id. name (2 to 16 letters, spaces, dashes, dots or quotes), female, race (human; elf from client 4.0.11d; gargoyle from 6.0.14.4; only human in the T2A era), str, dex, int (each 10 to 60, 80 in all, or 90 from client 7.0.16), skills ([{skill, value}]: 3, or 4 from client 7.0.16, each up to 50, 100 or 120 in all), skin_hue, hair, hair_hue, beard, beard_hue, shirt_hue, pants_hue, profession (a profession names its own stats and skills), start_city (an index of start_towns). UOTerm checks the rules before it asks the shard. A refusal of the shard comes back in its words. |
character_delete |
Deletes a character by name or slot, and answers the slots after. The shard may refuse, for example for a character played lately. |
connect |
Logs in as character (or the first of the account). Answers session_id and character. |
disconnect |
Ends the session session_id at once, with no logout. |
The account comes from a saved login, profile, or from account and
password_env. profile is the name of a saved login: a file of the
logins folder of the config folder, else of the profiles folder, as
uoterm connect --profile finds it. password_env is the name of an
environment variable that holds the password. A password is never an
argument, and it is never written to a log or given back. host, port,
shard, era, version, encryption and proxy default to the saved
login and to uoterm.toml.
To play another character of the account in the same session, logout with
then_play.
These are for the native window and the web client, not for an agent. MCP
does not list command, take_control, release_control or game_view.
| Tool | Notes |
|---|---|
watch |
observe with each list at full length, and what only a screen draws: each container with all its items, journal_lines with hue and kind, every skill, party_members (with the hits, mana and stam of each, and their most, when the shard told them), party_can_loot, multis, gump_layouts (each gump piece with its place, page and pictures), maps, profiles, designed_houses (the walls and floors a player designed, with their offsets), placing (a building that waits for its place; answer with target and a tile), chat, designing (the house, the floor worked on, and the plot_width and plot_depth of its plot when the client files hold the foundation), house_parts, cues (damage, animations, effects, the death screen and a status bar the shard shut, each with a seq that counts up), buff_icons (each buff with its icon, title, text and seconds left), live_map (the map blocks an UltimaLive shard changed near the character), season, light, weather, prompt, text_entry, target_cursor, board, and the items of an open trade. It also carries time, personal_light, quest_arrow, waypoints, shard_url, shard_notice and shard_tip (the number of the tip of the day shown; none for a notice). |
command |
One script command line (text) as one act of a human. Needs human true. |
take_control, release_control |
While a human has control, only a call with human true acts. Control goes back by itself after 90 seconds with no human act. |
game_view |
width and height: the size in pixels of the game view the window draws. The window sends it once a new size has held for half a second. The shard hears it (0xBF 0x05) at each login, and at once when it changes in the world. A session with no window tells 600 by 480. |
The shard may send the newer mobile packets 0xD2, 0xD3, 0x2D and
0xDE. They fill the same fields as 0x77, 0x78 and the stat bars, so
nothing changes for a driver. The gear of a corpse is in its container, and
a boat carries what stands on it.
uoterm connect, uoterm populate and uoterm play serve the runtime API
on --api-bind. uoterm play starts it after the first login. uoterm web
serves the same API on --bind, with the web client routes below. The
default address is api_bind in uoterm.toml, else 127.0.0.1:7733.
| Route | Notes |
|---|---|
GET /health |
ok. Needs no token. |
GET /v1/sessions |
{"sessions": [ids]} |
POST /v1/sessions |
Makes a session. Body: host, port, account, password, character, and the optional shard, era, version, obey_shard_rules, answer_when_named, play_along, reconnect and proxy. The encryption is always none. Answers 201 {"id": ...}, or 502 {"error": ...} when the login fails. The client files and the markers come from uoterm.toml. |
GET /v1/sessions/{id}/state |
The observe JSON. When observe fails, a plain snapshot. |
POST /v1/sessions/{id}/tools/{name} |
The body is the JSON arguments of the tool. 200 when the tool succeeds, 409 when it refuses, 400 for a session that does not exist. The body is the tool result: ok, result, and error when it failed. |
POST /v1/tools/{name} |
A runtime tool (connect, disconnect, characters, character_create, character_delete), with JSON arguments. 200 or 409, as above. 404 for any other name. |
POST /v1/web/token |
Gives the token cookie. See below. |
GET /v1/sessions/{id}/live |
The live link. See below. |
GET /v1/login/live |
The login link. See below. |
A session id that does not exist gets 404 {"error": "not found"}, except
on the tool route.
Three rules apply to every route, the page of the web client too.
Token. When UOTERM_API_TOKEN is set to a value, every route except
/health and /v1/web/token needs the token. A caller sends it as
Authorization: Bearer <token>, or in the uoterm_token cookie. The CLI
and MCP send the header when the variable is set. The token may hold only
visible ASCII marks, without ", ,, ; or \, because it goes in a
cookie. The server refuses to start with any other token. A bind to an
address that is not loopback is refused unless the variable is set.
Loopback. An API bound to loopback (127.0.0.1, localhost, ::1)
answers only a caller that names this machine in its Host header
(127.0.0.1, localhost, ::1 or [::1], with any port), or in the
authority of an HTTP/2 request. Any other caller gets 403. This stops a web
page that points a name it owns at this machine. /health follows this rule
too.
Origin. A request with an Origin header must come from a page of this
server: the Origin must be http:// followed by the Host of the
request, and on a loopback API that host must name this machine. Any other
Origin gets 403. A caller that is not a web page sends no Origin, so the
rule does not touch it.
Loopback with no token stays open for local tests. Do not bind the API to a public address without a token.
A web page cannot put headers on a WebSocket. So the page sends the token
once to POST /v1/web/token, with the body {"token": "..."}. The right
token gets 204 and a uoterm_token cookie (HttpOnly; SameSite=Strict; Path=/). A wrong token, or any token when the server has none, gets 401.
GET /v1/sessions/{id}/live is a WebSocket. The web client keeps one open to
the session it shows. A message from the page is 1 MiB at most. The server
calls the watch tool every 33 ms, and sends a frame only when it differs
from the last one it sent on this link. The radar size of the frames is 5
until the page sends a size.
| The page sends | Meaning |
|---|---|
{"kind":"call","id":1,"tool":"say","args":{...}} |
One tool call. |
{"kind":"act","id":2,"calls":[{"tool":"...","args":{...}}]} |
Calls made in order, 650 ms apart (ACT_STEP_GAP_MS). It stops at the first one that fails. 4 steps at most. |
{"kind":"size","size":N} |
The radar size the frames use. |
| The server sends | Meaning |
|---|---|
{"kind":"frame","watch":{...}} |
The result of the watch tool. |
{"kind":"answer","id":1,"ok":true,"result":{...}} |
The answer to the call or act with that id. A refused one has ok: false and error. The answer to an act is the result of its last call. |
{"kind":"ended"} |
The session is gone, and the link closes. |
Each call runs in a task of its own, so a tool that waits does not hold back the other calls of the page. One link runs 8 calls at one time. A call past that gets an error.
An act runs on the server, so a page that closes between a lift and its drop does not leave the item in the hand. The acts of one session run one at a time, whatever link sent them. One act runs and 4 wait. One more gets an error. An act with no call, or with more than 4, gets an error. The server skips a message it cannot read. It closes the link when the page takes more than 5 seconds to take one message.
GET /v1/login/live is a WebSocket, 64 KiB per message. The web client logs
in through it. The first message must come within 10 seconds, and it must
be a login:
{"kind":"login","host":"127.0.0.1","port":2593,"account":"a","password":"p",
"shard":"","character":"","era":null,"version":null,"encryption":"none"}shard, character, era, version and encryption are optional. A blank
shard or character lets the page pick. The era and the version default
to those of uoterm.toml, and encryption is none or osi. The other
session options come from uoterm.toml. The password is used for this login
only, and it is kept nowhere.
The server sends each question of the login, and the page answers each one:
| The server sends | The page answers |
|---|---|
{"kind":"ask","ask":{"kind":"Shard","names":[...]},"version":"..."} |
{"kind":"reply","reply":{"kind":"Pick","index":0}} |
{"kind":"ask","ask":{"kind":"Characters","names":[...],"refused":null,"choices":{"towns":[...],"features":0,"list_flags":0}},"version":"..."} |
{"kind":"reply","reply":{"kind":"Request","request":{"Play":0}}} |
{"kind":"ready","session":"s1"} |
The page opens the live link of that session. The login link closes. |
{"kind":"failed","words":"..."} |
The login ended with a fault. The link closes. |
A character request is one of these:
{"Play":slot}plays the character in that slot.{"Delete":slot}deletes it. The shard answers with a new list or a refusal.{"Make":{...}}makes a new character. The wish hasname,female,race,strength,dexterity,intelligence,skills(a list of[skill, value]pairs),skin_hue,hair,hair_hue,beard,beard_hue,shirt_hue,pants_hue,profession,start_cityandslot."Leave"plays no character, and the login ends at the character list.
version is the client version the login speaks. A new character follows
it. refused holds the words of the last refusal of the shard. A reply that
does not fit the open question is not taken, and the question comes again.
A page that closes before the end plays no character: an open character
question is answered with "Leave", and an open shard question ends the
login. A session the page cannot learn of is stopped. The words of a fault
in a message name only its kind and place, never its text.
uoterm web serves the browser client: a Three.js page from the web/
folder, built with npm run build, that runs the WebAssembly build of
crates/uoterm-web. It shares crates/uoterm-view with the native play
window. --web-dir names the folder of the built page (default web/dist),
and --uopath the client files (default uopath in uoterm.toml).
uoterm web serves the routes below on top of those above, behind the same
token, loopback and origin rules. uoterm connect, uoterm populate and
uoterm play do not serve them. Any path under /v1 (also /v1 and
/v1/) with no route gets 404 {"error": "not found"}, whatever the
method. Any other path gets a file of the built page, or its index.html.
The page itself needs no token, so a browser on another machine can load it
and ask the player for the token. The loopback and origin rules still apply
to it.
These need client files. With none, they answer 503. A picture or a table
that the browser keeps has an ETag from the version of the client files
and of UOTerm, with Cache-Control: public, max-age=31536000, immutable.
The server makes 4 pictures at one time.
| Route | Notes |
|---|---|
POST /v1/art |
JSON ArtRequest, tagged by kind: Land, Texture, Item, Gump, Cursor, Text or Figure. A PNG, with the point of the picture that goes on the tile in the x-uoterm-anchor header (x,y). 404 for no picture, 400 for one too large. |
POST /v1/text/measure |
Body {"text": ..., "look": ...}, as a Text picture asks. Answers {"lines": [...], "line_height": N}: the lines the words break into in a UO font, and the height of one line. 400 for words a picture would refuse, 404 with no UO fonts. |
GET /v1/gump-mask/{id} |
{"width", "height", "bits"}: the drawn pixels of a gump, one bit for each pixel, row by row from the top left, the lowest bit of each byte first, in base64. 404 for no gump. |
The map routes take an optional ?session={id}. With it, the map has the
UltimaLive changes that session sent (see POST /v1/sessions/{id}/map/live).
Without it, the map files alone. A map picture of a facet that a live map
changed is sent with Cache-Control: no-store, so the browser does not keep
it.
| Route | Notes |
|---|---|
GET /v1/map/{map}/{block_x}/{block_y} |
The 64 tiles of one block, row by row from its north west corner. Never kept (no-store). 404 past the edge of the map. |
GET /v1/map/near/{map}/{x}/{y} |
PNG: the land round a tile in radar colours, with the tile in the middle. 404 when no tile round it has a colour. |
GET /v1/map-picture/{map}/{tx}/{ty} |
PNG: one tile of the whole-world picture of a map. 404 past the picture. |
GET /v1/map-item/{facet}/{start_x}/{start_y}/{end_x}/{end_y} |
PNG: the land of a map item between its corners. 400 when the end is not past the start. |
POST /v1/sessions/{id}/map/live |
Body: the live_map value of watch, 8 MiB at most. It lays the changes over the map files of that session, and answers the blocks that changed as [{"map", "bx", "by"}], for the page to ask for again. 404 for a session that does not exist. The changes of a session are dropped when it ends. |
| Route | Notes |
|---|---|
GET /v1/data/{table} |
tiledata, animdata, anim-rules, radarcol, seasons, cliloc and item-layers. With an id: multis/{id} ([] when there is none), lights/{id} and hues-text/{hue}. |
GET /v1/data/frames/{body}/{action}/{direction}/{mounted} |
The frame count of a body for an action (stand, walk, run or a group number), a direction, on a mount or not. 400 for a question the animation files cannot hold. |
GET /v1/data/creation?towns=... |
What the character creation reads: {"professions", "skill_names", "town_texts", "words", "hue_colors"}. towns is a comma-separated list of the text numbers of the start-town words the shard offers (it may be empty or left out). words holds only the text numbers of the professions and of these towns (null when the client files have no Cliloc.enu). hue_colors gives [r, g, b] by hue for each hue of the palettes. 400 for a towns value that is not a list of numbers. |
A table the client files do not hold gets 404.
| Route | Notes |
|---|---|
GET /v1/sound/{id} |
One sound as a WAV file (16-bit mono). 503 when the client files hold no sounds, 404 for no sound. |
GET /v1/music/{id}?midi=true |
The file of a track: MP3, or MIDI only with midi=true (a page with a sound font). The x-uoterm-repeats header says if the track repeats. 503 when the client files hold no music, 404 for no track. |
GET /v1/soundfont?shard=&character= |
The MIDI sound font the profile names: the profile of that character, or the default profile with neither. 400 for one of the two alone. 404 when the profile names none, or names a file that is no sound font, or a file outside the config folder and the client files folder. |
These are the same files the native play window reads, so the options are the same in both clients.
| Route | Notes |
|---|---|
GET, PUT /v1/profiles/default |
The default profile, as JSON. PUT answers 204. |
GET, PUT /v1/profiles/{shard}/{character} |
The profile of a character. shard is host:port; 400 without a port. A character with no profile has the default one. PUT answers 204. |
GET, PUT /v1/kept/{name} |
watch-hotbar.toml and watch-grab-bags.toml, read and written as JSON. PUT answers 204, or 400 for JSON the file cannot hold. markers gives the marker and zone files of the map folder, and is read only (PUT is 405). 404 for any other name. |
POST /v1/map-markers/user |
Changes the player's own marker file, 64 KiB at most. Body: {"add": marker}, {"keep": {"at", "marker", "expected"}} or {"remove": {"at", "expected"}}. 200 {"changed": true}; 400 for a bad marker; 409 when the file no longer holds the marker the change expects; 422 when the file is full. |
GET /v1/fonts, GET /v1/fonts/{name} |
The player fonts of the Fonts folder. Only a listed name is read. |
POST /v1/screenshots |
Body: a PNG, 32 MiB at most. Saves it in the screenshots folder. 201 {"file": name}; 400 for a body that is no PNG. |
GET /v1/logins |
The saved logins, as the login screen of uoterm play lists them, and the server of uoterm.toml: {"host", "port", "logins": [{"name", "host", "port", "account", "shard", "character", "encryption", "era", "version"}]}. No password. |
PUT /v1/logins/{name} |
Saves a login form under name, and gives the list. The body has host, port, account, and the optional shard, character and encryption. A body with any other field, such as a password, is refused. So is an empty name. |
These run in UOTerm, so the TypeSafe key (TYPESAFE_API_KEY) never goes to
the browser. GET /v1/jev tells the page whether Jev can answer. The other
routes answer 503 when there is no key, 404 for an unknown session, and 409
when Jev gives no answer, each with {"error": words}.
| Route | Body | Answer |
|---|---|---|
GET /v1/jev |
None | {"on": bool}: true when UOTerm has the key. |
POST /v1/sessions/{id}/jev/order |
{"words": "...", "frame": {...}} (frame is a watch result) |
{"act": {"calls": [{"tool", "args"}], "words": "..."}}. The calls go on the live link as an act, each one marked human. words tells the player what was done. |
POST /v1/sessions/{id}/jev/pick |
{"question": ..., "names": [...], "wish": "..."}. question is shard, profile, house_part, wear, channel or landmark. |
{"index": N}, or null when Jev is not sure. |
POST /v1/sessions/{id}/jev/lines |
{"wish": "..."} |
{"lines": [...]}: the script lines of the hotkey the wish names. |
uoterm mcp
Start connect, populate, play or web first. uoterm mcp speaks
JSON-RPC 2.0 on stdio (protocolVersion 2024-11-05) and sends each call
to the HTTP API of --api. It reads newline JSON and Content-Length
framing. It skips a blank line, and answers bad JSON with -32700. A
Content-Length body larger than 1 MiB gets a -32700 answer. The server
skips that body and goes on with the next message.
Methods: initialize, ping, tools/list, tools/call, resources/list,
resources/read. It takes the notifications initialized,
notifications/initialized and notifications/cancelled without an answer.
tools/list gives every tool an agent may call. Each tool has its own
arguments, their types, and the ones it cannot do without (required). A
tool that needs one of several says so in its description. The runtime's
tools come first and take no session_id (see
Characters and login). For every other tool,
session_id names the session a call is for. With none, the first session
answers. The tools of a play window are not listed.
A tool result comes as text, and as structuredContent. A failure has
isError true.
Resource URIs:
uo://session/{id}/state: the observe JSON of that session.uo://playbook/{name}: a Markdown playbook (text/markdown), fromdocs/playbooks/.
| Playbook | Use |
|---|---|
driver |
The next_event loop and the order to act in |
login |
One connect owns the socket |
hunt |
The melee job: kill, loot own kills, run away |
walk |
A guarded walk that stops on a hostile |
navigation |
move_to or the walk job, doors, pads |
loot |
Corpses the hunt job did not make |
bank |
Walk to a banker, open the box, deposit |
death |
Come back as a ghost, then restock |
moongate |
Step onto the gate tile, then the gump |
dungeon |
Pads, stairs, z jumps |
mounts |
War mode off, then use; dismount is use on yourself |
runebook |
Recall from the book gump |
buy, sell |
The vendor keywords |
containers |
Open, lift, bags in bags |
talk |
reply and unanswered |
inspect |
Names, look_around, find_* |
equip |
Wear and take off |
Give the model observe, say, move_to, job_start and next_event to
start. Have it read the driver playbook first, then hunt or walk. Do
not ask it to walk tile by tile.
The MCP server adds one tool that is not a session tool: screenshot. It
opens the native watch window for one picture, and gives it back as a JPEG
image, at most 1024 px on its long side. A vision model then sees what a
human sees: the real map, the mobiles with their names, and the panels. Use
it when the text radar is not enough, for example in a crowd or in a
dungeon. It needs a desktop, and it takes some seconds (30 at most). It is
not on the HTTP API.