Feed API

O que um módulo do cliente envia e recebe. Toda chamada, menos a primeira, leva o token do pareamento:

Authorization: Bearer <token>

Endereço base: http://127.0.0.1:8090/api/v1. A descrição para máquinas está em openapi.json.

POST/api/v1/pair

Ask for a pairing code Call it once, when the module has no token yet. Show the code and the link in the game.

Não precisa de token.

Corpo da requisição

CampoTipoDescrição
characterobrigatóriostringThe character the client playsaté 30 caracteres
serverstringServer slug or name, for example orion, when a server adapter knows itaté 60 caracteres
hoststringThe client's login address: the server is found by its domainaté 200 caracteres
worldstringThe world name the client logged in toaté 60 caracteres
clientVersionintegerThe client's protocol version, for example 860
platformstringOperating system, for example Windows 11até 40 caracteres
modulestringModule name and versionaté 40 caracteres

Resposta

CampoTipoDescrição
codeobrigatóriostringShow it to the player. It is valid for 15 minutes
urlobrigatóriostringOpen it to start a guest dashboard, or to add the client to an account
tokenobrigatóriostringThe client's secret. Store it; it works once the code is used
expiresAtobrigatóriointeger

POST/api/v1/status

Send the character's state As often as the reply says: every 2 s while someone watches the character, 5 s while Team radar shows it, 30 s otherwise. The reply also says when to send the next capture.

Corpo da requisição

CampoTipoDescrição
schema"vw.status/1"Payload schema and version
moduleobrigatóriostringName and version of the sending module, for example voidwatch-feed/0.5.2até 40 caracteres
onlineobrigatóriobooleanThe character is logged in
characterobrigatórioCharacter
character.nameobrigatóriostringCharacter nameaté 30 caracteres
character.vocationstringVocation, for example Elite Knightaté 30 caracteres
character.levelobrigatóriointeger≥ 1, ≤ 5000
character.expobrigatóriointegerTotal experience points≥ 0
posobrigatórioPosition
pos.xobrigatóriointegerMap x≥ 0, ≤ 65535
pos.yobrigatóriointegerMap y≥ 0, ≤ 65535
pos.zobrigatóriointegerFloor, 0 to 15; 7 is ground level≥ 0, ≤ 15
capintegerFree capacity, in oz≥ 0
staminaintegerStamina, in minutes≥ 0, ≤ 2520
expPerHourintegerExp per hour as the client measures it≥ 0
routestringThe loaded cavebot routeaté 80 caracteres
routeOnbooleanThe cavebot is running
labelstringThe route label the bot is ataté 40 caracteres
phase"hunting" | "to_city" | "in_city" | "to_resp" | "parked" | "stopped" | "unknown" | "town" | "at_check" | "leaving"Where the character is in its route, from the labels hunt, refill, city and resp: unknown when a label is missing. town, at_check and leaving come from bot adapters before version 4
labelsMissingstring[]Route parts without a label. check and leave come from bot adapters before version 4até 4 itens
planPlanStateThe bot's plan: a command that acts when the bot reaches a label. An ended plan stays for two minutes
plan.idintegerThe command that started the plan
plan.kindobrigatório"refill" | "go_depot" | "load_route"
plan.routestringThe route a switch loadsaté 80 caracteres
plan.stateobrigatório"running" | "done" | "stuck" | "cancelled" | "taken_over" | "failed"
plan.step"hunt" | "city" | "depot" | "switch"What the running plan waits for
plan.messagestringaté 200 caracteres
plan.sinceintegerUnix seconds when the plan started
plan.untilintegerUnix seconds when the waiting step gives up as stuck
plan.endedintegerUnix seconds when the plan ended
routesstring[]Every route the bot can loadaté 100 itens
suppliesSupplyItem[]até 60 itens
supplies[].nameobrigatóriostringItem name, as the game writes itaté 60 caracteres
supplies[].haveobrigatóriointegerHow many the character carries, closed bags included where the game said≥ 0
supplies[].wantintegerHow many the bot keeps in stock; missing when the list comes from the use lines≥ 0
suppliesSourcestringbot: the bot's own supply list; used: every item the game's use lines namedaté 20 caracteres
tasksTaskItem[]até 10 itens
tasks[].nameobrigatóriostringItem or creature name, as the game writes itaté 60 caracteres
tasks[].haveobrigatóriointegerHow many the character has now≥ 0
tasks[].wantobrigatóriointegerHow many the bot keeps in stock, or the task goal≥ 0
tasks[].expintegerExp reward for the goal, if the server says≥ 0
tasks[].taskPointsintegerTask points for the goal, if the server has them≥ 0
taskPointsintegerThe task points balance, on servers with task points≥ 0
taskWeekTaskWeekTask points this week, on servers with a weekly cap
taskWeek.earnedobrigatóriointegerTask points earned this week≥ 0
taskWeek.capobrigatóriointegerThe most task points a week allows≥ 0
lootLootItem[]até 200 itens
loot[].nameobrigatóriostringItem nameaté 60 caracteres
loot[].countobrigatóriointegerLooted since the session started≥ 0
loot[].sellintegerNPC price per item, if the module knows it. The server fills it in otherwise≥ 0
usedUsedItem[]Supplies used since the loot counter startedaté 200 itens
used[].nameobrigatóriostringItem nameaté 60 caracteres
used[].countobrigatóriointegerUsed since the counter started≥ 0
used[].buyintegerNPC buy price per item, if the module knows it≥ 0
lootHoursnumberHours since the loot counter started≥ 0
lootSourcestringWhere the loot count comes from: corpse, the loot messages every server sends, or the id of an adapter such as an autolootaté 40 caracteres
skullsSkull[]Skulled players in viewaté 20 itens
skulls[].nameobrigatóriostringPlayer nameaté 30 caracteres
skulls[].skullobrigatório"white" | "red" | "black" | "yellow" | "green" | "orange"Skull colour
skulls[].distintegerSquares away from the character≥ 0, ≤ 100
blessedbooleanOnly on servers with blessings
pzbooleanThe character stands in a protection zone
pzLockbooleanThe character is PZ locked: it cannot enter a protection zone
outfitOutfitThe character's look, drawn on the map
outfit.typeobrigatóriointegerThe look type≥ 0, ≤ 10000
outfit.headinteger≥ 0, ≤ 255
outfit.bodyinteger≥ 0, ≤ 255
outfit.legsinteger≥ 0, ≤ 255
outfit.feetinteger≥ 0, ≤ 255
outfit.addonsinteger≥ 0, ≤ 3
skull"white" | "red" | "black" | "yellow" | "green" | "orange"The character's own skull, if it has one
playersInViewintegerOther players in view≥ 0, ≤ 500
redemptionbooleanOnly on servers with death redemption: it is active now
redemptionLeftintegerOnly on servers with redemption≥ 0
targetOnbooleanThe targeting bot is running
botConfigstringThe bot preset, for example vBot_4.8até 60 caracteres
targetProfilestringThe loaded targeting profileaté 80 caracteres
botProfileintegerThe bot settings profile, for example vBot's 1 to 5≥ 1, ≤ 20
adaptersAdapterState[]The adapters the module runs, and whether each is onaté 30 itens
adapters[].idobrigatóriostringAdapter id, for example orion-ots-tasks or botaté 40 caracteres
adapters[].versionstringaté 20 caracteres
adapters[].onobrigatóriobooleanFalse: the adapter stopped after errors, or the bot stopped attaching
adapters[].wantstringFor the bot adapter: the version the module ships. A lower version waits for a bot reloadaté 20 caracteres
addonsAddonState[]The addons in the data folder, and whether each runsaté 30 itens
addons[].idobrigatóriostringAddon id, for example exiva-map
addons[].versionstringThe module version the addon came withaté 20 caracteres
addons[].onobrigatóriobooleanLoaded now
addons[].errorstringWhy it is not loaded: installing, the download failed, or its last erroraté 200 caracteres
featuresstring[]What the module runs, for example status, captures and commands. The dashboard turns off what is not listed. Left out: everythingaté 20 itens
actionsstring[]The command actions this client can run now, for example toggle_cavebot. The dashboard offers only theseaté 40 itens
settingsChangeobjectA change from the Settings tab of the Voidwatch window: {rev, values}. The values follow the rules of the Clients page. A bad value never refuses the status: settingsSaved in the reply says why

Resposta

CampoTipoDescrição
okobrigatórioboolean
statusEveryobrigatóriointegerSeconds until the next status: 2 while someone watches the character, 5 while Team radar shows it, 30 otherwise
captureEveryobrigatóriointegerSeconds until the next capture: short while someone watches or an alert fired
commandsobrigatóriointegerCommands waiting; fetch them from /api/v1/commands
settingsSettingsThe player's module settings, for example minimap: true
latestModulestringThe newest module release on GitHub, as the server last saw it. The upload script offers an update only when this is higher than the running version
needMapbooleanTrue when the player has no map of this server: send every minimap file again
addonCatalogobject[]The addons of the newest release, for the Voidwatch window: id, name, about, points, plan, size in bytes and version
settingsSavedobjectOnly after a status with settingsChange: {rev, ok, error}. The module keeps sending the change until this names its rev
radarRadarMark[]Only while the client runs the Team radar addon: the player's other characters online on this server, and the guild mates who share their position
radar[].nameobrigatóriostring
radar[].xobrigatóriointeger
radar[].yobrigatóriointeger
radar[].zobrigatóriointeger
radar[].kindobrigatório"own" | "guild"own: another character of the player. guild: a guild mate who shares their position
atobrigatóriointegerServer time of this reply, Unix seconds. The reply changes with every send, so the module sees when the upload script last got an answer

GET/api/v1/wait

Wait for a change A long poll: the answer comes the moment someone opens the character on the dashboard, an alert fires or a command is sent, or after `timeout` seconds (at most 25). Keep one open while the client runs, so it switches to the fast pace within a second and costs no requests while nothing happens. A revoke ends it with 401 at once.

Resposta

CampoTipoDescrição
wakeobrigatóriobooleanTrue when something changed before the timeout
statusEveryobrigatóriointeger
captureEveryobrigatóriointeger
commandsobrigatóriointeger

GET/api/v1/wake

Ask whether to send the status now A cheap check from memory for clients with Team exiva on. Ask every 2 seconds instead of keeping a long poll open, so the files to send never wait. `wake` is true when a command waits, or when the client should report faster than now, for example because someone opened the character: send the status at once, and its reply brings the commands and the new pace.

Resposta

CampoTipoDescrição
wakeobrigatóriobooleanSend the status now: a command waits, or someone opened the character

POST/api/v1/minimap

Send the minimap file One minimap file of the client, any minimap*.otmm as it is on disk, at most 40 MB, with its change time in X-File-Mtime. It merges into the player's own map of the server: new areas are added, and a tile the file has not seen never covers one the map has. Send each file when it changed and the reply's settings say minimap: true; send all of them again when the reply says needMap: true. At most 30 files per hour for one player and server; more get 429.

Corpo da requisição

application/octet-stream

Resposta

any

POST/api/v1/capture

Send a screenshot The game window as JPEG or PNG, at most 2 MB. Send one when /status says so.

Corpo da requisição

image/jpeg, image/png

Resposta

any

GET/api/v1/commands

Fetch waiting commands Commands the player sent from the dashboard, oldest first. Fetching marks them as sent. A command older than 60 seconds is not delivered: it shows as expired.

Resposta

Command[]

POST/api/v1/commands/{cid}/result

Report how a command went

Corpo da requisição

CampoTipoDescrição
okobrigatórioboolean
messagestringShown in the command logaté 200 caracteres
dataExivaResultcast_exiva: the parsed answer and where the caster stood
data.bandobrigatório"beside" | "close" | "far" | "veryfar"next to you, under 100 squares, under 274, or beyond
data.dir"north" | "north-east" | "east" | "south-east" | "south" | "south-west" | "west" | "north-west"Left out for next to you
data.levelobrigatório"same" | "higher" | "lower" | "unknown"The floor: only next to you and close answers name it
data.xobrigatóriointegerWhere the caster stood when it cast≥ 0, ≤ 65535
data.yobrigatóriointeger≥ 0, ≤ 65535
data.zobrigatóriointeger≥ 0, ≤ 15

Resposta

any

POST/api/v1/exiva

Start a team exiva from a cast in the game The player cast exiva in the game and got an answer. Every character of the team with Team exiva on casts on the same target; the result comes back as an exiva_show command. A second cast on the same target within 10 s joins the run.

Corpo da requisição

CampoTipoDescrição
bandobrigatório"beside" | "close" | "far" | "veryfar"next to you, under 100 squares, under 274, or beyond
dir"north" | "north-east" | "east" | "south-east" | "south" | "south-west" | "west" | "north-west"Left out for next to you
levelobrigatório"same" | "higher" | "lower" | "unknown"The floor: only next to you and close answers name it
targetobrigatóriostringThe name the game answered aboutaté 30 caracteres
posobrigatórioPositionWhere the character stood when it cast
pos.xobrigatóriointegerMap x≥ 0, ≤ 65535
pos.yobrigatóriointegerMap y≥ 0, ≤ 65535
pos.zobrigatóriointegerFloor, 0 to 15; 7 is ground level≥ 0, ≤ 15
textstringThe game messageaté 120 caracteres

Resposta

any

Erros

Dados fora do esquema recebem status 422 com todos os problemas listados:

{
  "error": "invalid payload",
  "problems": [
    {
      "field": "pos.z",
      "message": "Input should be less than or equal to 15"
    }
  ],
  "schema": "/developers/schema"
}

Status 401 significa que o token é desconhecido ou que o jogador revogou o cliente. Pareie de novo para ter um novo.