Developers

How a game client talks to Voidwatch. How to build your own module or add a new server.

The parts

PartWhere it runsWhat it does
moduleinside the game clientwrites the character state to files and runs the commands that it gets
upload scripton the same computer as the clientsends the files to the API and writes the replies back
feed APIon our serversstores the state and answers with the capture rate and the waiting commands

The client itself makes no web requests. The next section tells why.

Why the client sends nothing itself

The HTTP layer of OTClientV8 keeps the body of every request that it sends.

  • In the client source (otcv8-dev), the callback inside Http::post captures the operation id by reference.
  • So the cleanup that erases a finished operation misses it.
  • Each HTTP.post or g_http.post stays in memory until the client exits.
  • A cleanup on the Lua side with HTTP.operations or HTTP.cancel does not help. The bodies stay on the C++ side.

We measured this on game clients.

TestResult
Screenshots of the game view, sent with HTTP.post, about 370 KB each2 clients crashed after about 1,000 uploads, with Critical lua error! in http.lua. The 32-bit client ran out of memory.
The websocket, g_http.wsIt kept about one message per send in a 10-minute test.
The same screenshots, written to a file, with no send from the clientOne client ran 4 h 26 min, with 4,526 screenshots and 0 memory errors.

The memory figure of the client, g_platform.getMemoryUsage(), does not show this growth. The view of the operating system does. That is why the module writes files, and the upload script does the network part.

One loop

Each character has its own folder in the data folder of the client. OTClientV8 calls the data folder the write folder. Clients on one computer often share it.

InstallCharacter folder
module in the modules foldervoidwatch/<character>/
module in the bot folder (Orion)bot/_voidwatch/data/<character>/

The paths below are inside the character's folder.

  1. The module writes outbox/status.json. It writes it every 2 seconds while someone watches the character, and every 5 seconds while Team radar shows it. Otherwise, it writes it every 30 seconds.
  2. The script sends the file to POST /api/v1/status. It writes the reply to inbox/reply.json.
  3. The reply sets how often to send a screenshot. That is every 1–2 seconds while someone watches the character. Otherwise, it is once a minute.
  4. When commands wait, the script fetches them into a new file, inbox/commands-<time>-<n>.json. The module runs each command once and skips a command older than 60 seconds. It adds each result to outbox/results.json.
  5. Between two statuses, the script keeps one request open to GET /api/v1/wait. The request returns when someone opens the character, an alert fires or a command arrives. The client then speeds up within a second. With Team exiva on, the script asks GET /api/v1/wake every 2 seconds instead. Its files then never wait for a long poll. A client with Team exiva on that does not ask reports every 2 seconds.
  6. Once a minute, the script checks every minimap*.otmm file of the client. It sends each file that changed, at most every 30 minutes, with its change time. The website merges each file into the map of the player. A file never removes an area. When the reply says needMap: true, the script sends all files again. Players can turn this off in the module settings.

Pairing

A new client has no token.

  1. The module writes outbox/pair-request.json.
  2. The script calls POST /api/v1/pair.
  3. The reply holds a code and a link for the player. It also holds the token, which the script keeps.

A code that nobody uses expires after 15 minutes. The script then asks for a new code.

Updates

The module never downloads code. The server asks GitHub for the newest release every 5 minutes. Each status reply passes that version on, as latestModule. The upload script also asks GitHub itself every 6 hours. It writes the higher of the two versions to latest.json.

The update files are in the data root, not in a character's folder. The data root is voidwatch/. For a module in the bot folder, it is bot/_voidwatch/data/.

  1. The player clicks Update. The module writes update-request.json with the version and the character.
  2. The script downloads the release zip and its SHA256SUMS from GitHub. It checks the checksum and the version in the zip.
  3. The script copies the old module folder to backup/. It puts the new folder in its place.
  4. The script writes update-result.json. The client that asked reloads the module. Other clients offer Reload.

Roll back writes rollback-request.json. The script then puts the backup back.

The script reads releases only from GitHub, never from the website. So a website that someone breaks into cannot send code to the clients.

Build your own

Everything is open, with the MIT licence:

Keep the file layout, and your module works with our upload scripts. You can also write your own sender, in any language.

A server can also ship the module in its own client. Contact us, and we list the server as a partner.