Engine protocol
Introduction
The frontend interacts with the engine in two separate occasions:
- map preview generation;
- game setup and statistics messages.
Messages are always in form of a string of bytes, and the first byte contains the message size (hence the maximum length is 255-1).
Map preview
Frontend needs to generate a preview of the map that is going to be used in game; there is no handshaking.
Files in which this protocol is implemented: hwmapp.cpp, MapConfigViewController.m
Protocol
| Frontend | Engine | Format |
| UUID | |
eseed { ... }
|
| Template Filter | |
e$template_filter N
|
| Map Type | |
e$mapgen N
|
| Maze Value | |
e$maze_size N
|
| | 128×32 byte array |
0YSD3 ... FSAD0
|
Message format
Seed
In the Qt frontend, the seed is a UUID.
The UUID is a 32 bytes array composed of ASCII characters; groups of letters should be separated by “-”. There are standard function calls to automatically generate this string depending on the tools used.
This is however just due to convenience. UUIDs are not a particularly good source of entropy and any 1-249 character string can be used. For example “人算不如天算” is a valid seed.
If the string is of the form
AAAAAAAAA|BBBBB
(2 pipe separated strings) then only
AAAAAAAAA
will be used for terrain generation while
AAAAAAAAA|BBBBB
will be used for everything else. This allows players keep using a terrain they generated but change the rest of the seed to ensure new positions etc.
Example:
eseed {AERTB-62FASDSAD-NNIASDSADASD-12P}
Template filter
N
selects the type of map that is going to be generated. This command is ignored when
MapGen
is not 0, but it must be set anyways.
| Value | Filter Selected |
| 0 | None |
| 1 | Large |
| 2 | Medium |
| 3 | Small |
| 4 | Cavern |
| 5 | Wacky |
Example:
e$template_filter 0
Map type
N
is a boolean variable (0/1) that selects standard map generation or maze map generation.
| Value | Map Type |
| 0 | Standard Map |
| 1 | Maze Map |
Example:
e$mapgen 1
Maze value
N
selects the type of maze selected, similarly to Template Filter.
| Value | Filter Selected |
| 0 | Small Tunnels |
| 1 | Medium Tunnels |
| 2 | Large Tunnels |
| 3 | Small Floating Islands |
| 4 | Medium Floating Islands |
| 5 | Large Floating Islands |
Example:
e$maze_size 4
Image array
The reply from engine is a 128×32 bytes array which contains the preview image in pixel-dot notation: every bit represents a pixel of the image, 1 is black, 0 i white. Clearly it can only contain a monochromatic image, but it can be colored by the rendering engine of the frontend.
This image format is supported by many platforms, but it's very easy to parse anyways. The result is always a 256×128 pixel image.
No example needed.
In-game
This document needs more fleshing out, but in the interest of contributing, submitting an image I'd made after reading a GCI task.
HWD file with a little colour markup of various interesting parts of the game. By the way, if you ever need to debug a crashing demo, appending
032BFF
to the end is a good way to make sure the demo doesn't close too early (see the image to see why).
