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
| Campo | Tipo | Descrição |
|---|---|---|
characterobrigatório | string | The character the client playsaté 30 caracteres |
server | string | Server slug or name, for example orion, when a server adapter knows itaté 60 caracteres |
host | string | The client's login address: the server is found by its domainaté 200 caracteres |
world | string | The world name the client logged in toaté 60 caracteres |
clientVersion | integer | The client's protocol version, for example 860 |
platform | string | Operating system, for example Windows 11até 40 caracteres |
module | string | Module name and versionaté 40 caracteres |
Resposta
| Campo | Tipo | Descrição |
|---|---|---|
codeobrigatório | string | Show it to the player. It is valid for 15 minutes |
urlobrigatório | string | Open it to start a guest dashboard, or to add the client to an account |
tokenobrigatório | string | The client's secret. Store it; it works once the code is used |
expiresAtobrigatório | integer |
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
| Campo | Tipo | Descrição |
|---|---|---|
schema | "vw.status/1" | Payload schema and version |
moduleobrigatório | string | Name and version of the sending module, for example voidwatch-feed/0.5.2até 40 caracteres |
onlineobrigatório | boolean | The character is logged in |
characterobrigatório | Character | |
character.nameobrigatório | string | Character nameaté 30 caracteres |
character.vocation | string | Vocation, for example Elite Knightaté 30 caracteres |
character.levelobrigatório | integer | ≥ 1, ≤ 5000 |
character.expobrigatório | integer | Total experience points≥ 0 |
posobrigatório | Position | |
pos.xobrigatório | integer | Map x≥ 0, ≤ 65535 |
pos.yobrigatório | integer | Map y≥ 0, ≤ 65535 |
pos.zobrigatório | integer | Floor, 0 to 15; 7 is ground level≥ 0, ≤ 15 |
cap | integer | Free capacity, in oz≥ 0 |
stamina | integer | Stamina, in minutes≥ 0, ≤ 2520 |
expPerHour | integer | Exp per hour as the client measures it≥ 0 |
route | string | The loaded cavebot routeaté 80 caracteres |
routeOn | boolean | The cavebot is running |
label | string | The 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 |
labelsMissing | string[] | Route parts without a label. check and leave come from bot adapters before version 4até 4 itens |
plan | PlanState | The bot's plan: a command that acts when the bot reaches a label. An ended plan stays for two minutes |
plan.id | integer | The command that started the plan |
plan.kindobrigatório | "refill" | "go_depot" | "load_route" | |
plan.route | string | The 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.message | string | até 200 caracteres |
plan.since | integer | Unix seconds when the plan started |
plan.until | integer | Unix seconds when the waiting step gives up as stuck |
plan.ended | integer | Unix seconds when the plan ended |
routes | string[] | Every route the bot can loadaté 100 itens |
supplies | SupplyItem[] | até 60 itens |
supplies[].nameobrigatório | string | Item name, as the game writes itaté 60 caracteres |
supplies[].haveobrigatório | integer | How many the character carries, closed bags included where the game said≥ 0 |
supplies[].want | integer | How many the bot keeps in stock; missing when the list comes from the use lines≥ 0 |
suppliesSource | string | bot: the bot's own supply list; used: every item the game's use lines namedaté 20 caracteres |
tasks | TaskItem[] | até 10 itens |
tasks[].nameobrigatório | string | Item or creature name, as the game writes itaté 60 caracteres |
tasks[].haveobrigatório | integer | How many the character has now≥ 0 |
tasks[].wantobrigatório | integer | How many the bot keeps in stock, or the task goal≥ 0 |
tasks[].exp | integer | Exp reward for the goal, if the server says≥ 0 |
tasks[].taskPoints | integer | Task points for the goal, if the server has them≥ 0 |
taskPoints | integer | The task points balance, on servers with task points≥ 0 |
taskWeek | TaskWeek | Task points this week, on servers with a weekly cap |
taskWeek.earnedobrigatório | integer | Task points earned this week≥ 0 |
taskWeek.capobrigatório | integer | The most task points a week allows≥ 0 |
loot | LootItem[] | até 200 itens |
loot[].nameobrigatório | string | Item nameaté 60 caracteres |
loot[].countobrigatório | integer | Looted since the session started≥ 0 |
loot[].sell | integer | NPC price per item, if the module knows it. The server fills it in otherwise≥ 0 |
used | UsedItem[] | Supplies used since the loot counter startedaté 200 itens |
used[].nameobrigatório | string | Item nameaté 60 caracteres |
used[].countobrigatório | integer | Used since the counter started≥ 0 |
used[].buy | integer | NPC buy price per item, if the module knows it≥ 0 |
lootHours | number | Hours since the loot counter started≥ 0 |
lootSource | string | Where the loot count comes from: corpse, the loot messages every server sends, or the id of an adapter such as an autolootaté 40 caracteres |
skulls | Skull[] | Skulled players in viewaté 20 itens |
skulls[].nameobrigatório | string | Player nameaté 30 caracteres |
skulls[].skullobrigatório | "white" | "red" | "black" | "yellow" | "green" | "orange" | Skull colour |
skulls[].dist | integer | Squares away from the character≥ 0, ≤ 100 |
blessed | boolean | Only on servers with blessings |
pz | boolean | The character stands in a protection zone |
pzLock | boolean | The character is PZ locked: it cannot enter a protection zone |
outfit | Outfit | The character's look, drawn on the map |
outfit.typeobrigatório | integer | The look type≥ 0, ≤ 10000 |
outfit.head | integer | ≥ 0, ≤ 255 |
outfit.body | integer | ≥ 0, ≤ 255 |
outfit.legs | integer | ≥ 0, ≤ 255 |
outfit.feet | integer | ≥ 0, ≤ 255 |
outfit.addons | integer | ≥ 0, ≤ 3 |
skull | "white" | "red" | "black" | "yellow" | "green" | "orange" | The character's own skull, if it has one |
playersInView | integer | Other players in view≥ 0, ≤ 500 |
redemption | boolean | Only on servers with death redemption: it is active now |
redemptionLeft | integer | Only on servers with redemption≥ 0 |
targetOn | boolean | The targeting bot is running |
botConfig | string | The bot preset, for example vBot_4.8até 60 caracteres |
targetProfile | string | The loaded targeting profileaté 80 caracteres |
botProfile | integer | The bot settings profile, for example vBot's 1 to 5≥ 1, ≤ 20 |
adapters | AdapterState[] | The adapters the module runs, and whether each is onaté 30 itens |
adapters[].idobrigatório | string | Adapter id, for example orion-ots-tasks or botaté 40 caracteres |
adapters[].version | string | até 20 caracteres |
adapters[].onobrigatório | boolean | False: the adapter stopped after errors, or the bot stopped attaching |
adapters[].want | string | For the bot adapter: the version the module ships. A lower version waits for a bot reloadaté 20 caracteres |
addons | AddonState[] | The addons in the data folder, and whether each runsaté 30 itens |
addons[].idobrigatório | string | Addon id, for example exiva-map |
addons[].version | string | The module version the addon came withaté 20 caracteres |
addons[].onobrigatório | boolean | Loaded now |
addons[].error | string | Why it is not loaded: installing, the download failed, or its last erroraté 200 caracteres |
features | string[] | What the module runs, for example status, captures and commands. The dashboard turns off what is not listed. Left out: everythingaté 20 itens |
actions | string[] | The command actions this client can run now, for example toggle_cavebot. The dashboard offers only theseaté 40 itens |
settingsChange | object | A 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
| Campo | Tipo | Descrição |
|---|---|---|
okobrigatório | boolean | |
statusEveryobrigatório | integer | Seconds until the next status: 2 while someone watches the character, 5 while Team radar shows it, 30 otherwise |
captureEveryobrigatório | integer | Seconds until the next capture: short while someone watches or an alert fired |
commandsobrigatório | integer | Commands waiting; fetch them from /api/v1/commands |
settings | Settings | The player's module settings, for example minimap: true |
latestModule | string | The 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 |
needMap | boolean | True when the player has no map of this server: send every minimap file again |
addonCatalog | object[] | The addons of the newest release, for the Voidwatch window: id, name, about, points, plan, size in bytes and version |
settingsSaved | object | Only after a status with settingsChange: {rev, ok, error}. The module keeps sending the change until this names its rev |
radar | RadarMark[] | 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ório | string | |
radar[].xobrigatório | integer | |
radar[].yobrigatório | integer | |
radar[].zobrigatório | integer | |
radar[].kindobrigatório | "own" | "guild" | own: another character of the player. guild: a guild mate who shares their position |
atobrigatório | integer | Server 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
| Campo | Tipo | Descrição |
|---|---|---|
wakeobrigatório | boolean | True when something changed before the timeout |
statusEveryobrigatório | integer | |
captureEveryobrigatório | integer | |
commandsobrigatório | integer |
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
| Campo | Tipo | Descrição |
|---|---|---|
wakeobrigatório | boolean | Send 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
| Campo | Tipo | Descrição |
|---|---|---|
okobrigatório | boolean | |
message | string | Shown in the command logaté 200 caracteres |
data | ExivaResult | cast_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ório | integer | Where the caster stood when it cast≥ 0, ≤ 65535 |
data.yobrigatório | integer | ≥ 0, ≤ 65535 |
data.zobrigatório | integer | ≥ 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
| Campo | Tipo | Descriçã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ório | string | The name the game answered aboutaté 30 caracteres |
posobrigatório | Position | Where the character stood when it cast |
pos.xobrigatório | integer | Map x≥ 0, ≤ 65535 |
pos.yobrigatório | integer | Map y≥ 0, ≤ 65535 |
pos.zobrigatório | integer | Floor, 0 to 15; 7 is ground level≥ 0, ≤ 15 |
text | string | The 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.