Developers
How a game client talks to Voidwatch. How to build your own module or add a new server.
The parts
| Part | Where it runs | What it does |
|---|---|---|
| module | inside the game client | writes the character state to files and runs the commands that it gets |
| upload script | on the same computer as the client | sends the files to the API and writes the replies back |
| feed API | on our servers | stores 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 insideHttp::postcaptures the operation id by reference. - So the cleanup that erases a finished operation misses it.
- Each
HTTP.postorg_http.poststays in memory until the client exits. - A cleanup on the Lua side with
HTTP.operationsorHTTP.canceldoes not help. The bodies stay on the C++ side.
We measured this on game clients.
| Test | Result |
|---|---|
Screenshots of the game view, sent with HTTP.post, about 370 KB each | 2 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.ws | It kept about one message per send in a 10-minute test. |
| The same screenshots, written to a file, with no send from the client | One 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.
| Install | Character folder |
|---|---|
| module in the modules folder | voidwatch/<character>/ |
| module in the bot folder (Orion) | bot/_voidwatch/data/<character>/ |
The paths below are inside the character's folder.
- 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. - The script sends the file to
POST /api/v1/status. It writes the reply toinbox/reply.json. - 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.
- 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 tooutbox/results.json. - 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 asksGET /api/v1/wakeevery 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. - Once a minute, the script checks every
minimap*.otmmfile 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 saysneedMap: true, the script sends all files again. Players can turn this off in the module settings.
Pairing
A new client has no token.
- The module writes
outbox/pair-request.json. - The script calls
POST /api/v1/pair. - 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/.
- The player clicks Update. The module writes
update-request.jsonwith the version and the character. - The script downloads the release zip and its
SHA256SUMSfrom GitHub. It checks the checksum and the version in the zip. - The script copies the old module folder to
backup/. It puts the new folder in its place. - 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:
- the feed API
- the status payload
- the reference module
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.