EngineProtocol.wiki
author Wuzzy
Fri, 19 Apr 2019 16:07:50 +0100
changeset 1831 365c30b4c669
parent 1105 4d7c2358c51a
permissions -rw-r--r--
LuaGears: Add temporary mistake to test documentation script
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
     1
#summary Protocol for frontend/engine interaction.
1
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
     2
#labels Documentation,Engine,Frontend,Protocol
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
     3
745
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
     4
= Engine protocol =
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
     5
2
ba21be2f1b7a toc + fix
vittorio.giovara@gmail.com
parents: 1
diff changeset
     6
<wiki:toc max_depth="3" />
ba21be2f1b7a toc + fix
vittorio.giovara@gmail.com
parents: 1
diff changeset
     7
745
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
     8
== Introduction ==
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
     9
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    10
The frontend interacts with the engine in two separate occasions:
1096
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    11
 * map preview generation;
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    12
 * game setup and statistics messages.
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    13
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    14
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).
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    15
745
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
    16
== Map preview ==
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    17
Frontend needs to generate a preview of the map that is going to be used in game; there is no handshaking.
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    18
798
30c5f1ebd552 global replace of http with https for hedgewars.org wiki links
nemo
parents: 745
diff changeset
    19
Files in which this protocol is implemented: [https://hg.hedgewars.org/hedgewars/file/default/QTfrontend/hwmap.cpp hwmapp.cpp], [https://hg.hedgewars.org/hedgewars/file/default/project_files/HedgewarsMobile/Classes/MapConfigViewController.m MapConfigViewController.m]
1
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    20
745
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
    21
=== Protocol ===
1097
959a905adbf8 EngineProtocol: fix curly brace
Wuzzy
parents: 1096
diff changeset
    22
|| *Frontend*      || *Engine*          || *Format*              ||
959a905adbf8 EngineProtocol: fix curly brace
Wuzzy
parents: 1096
diff changeset
    23
|| UUID            ||                   || `eseed { ... }`       ||
959a905adbf8 EngineProtocol: fix curly brace
Wuzzy
parents: 1096
diff changeset
    24
|| Template Filter ||                   || `e$template_filter N` ||
959a905adbf8 EngineProtocol: fix curly brace
Wuzzy
parents: 1096
diff changeset
    25
|| Map Type        ||                   || `e$mapgen N`          ||
959a905adbf8 EngineProtocol: fix curly brace
Wuzzy
parents: 1096
diff changeset
    26
|| Maze Value      ||                   || `e$maze_size N`       ||
959a905adbf8 EngineProtocol: fix curly brace
Wuzzy
parents: 1096
diff changeset
    27
||                 || 128×32 byte array || `0YSD3 ... FSAD0`     ||
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    28
745
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
    29
=== Message format ===
1092
b26366ceabba fix some inaccuracy/missing information wrt seeds.
nemo
parents: 798
diff changeset
    30
==== Seed ====
1096
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    31
In the Qt frontend, the seed is a UUID.
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    32
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.
1093
1fa6884340af elaborate that string can be of variable length
nemo
parents: 1092
diff changeset
    33
1096
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    34
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.
1094
860e2bd4e975 oh, what the heck, include a utf-8 string to make the point.
nemo
parents: 1093
diff changeset
    35
1105
4d7c2358c51a grammar fix
nemo
parents: 1098
diff changeset
    36
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.
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    37
1096
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    38
Example: `eseed {AERTB-62FASDSAD-NNIASDSADASD-12P}`
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    39
745
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
    40
==== Template filter ====
1098
62773b3215bd EngineProtocol: Fix fake MapGen link
Wuzzy
parents: 1097
diff changeset
    41
`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.
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    42
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    43
|| *Value* || *Filter Selected* ||
1
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    44
|| 0       || None              ||
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    45
|| 1       || Large             ||
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    46
|| 2       || Medium            ||
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    47
|| 3       || Small             ||
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    48
|| 4       || Cavern            ||
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    49
|| 5       || Wacky             ||
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    50
1096
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    51
Example: `e$template_filter 0`
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    52
745
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
    53
==== Map type ====
1096
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    54
`N` is a boolean variable (0/1) that selects standard map generation or maze map generation.
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    55
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    56
|| *Value* || *Map Type*   ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    57
|| 0       || Standard Map ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    58
|| 1       || Maze Map     ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    59
1096
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    60
Example: `e$mapgen 1`
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    61
745
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
    62
==== Maze value ====
1096
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    63
`N` selects the type of maze selected, similarly to Template Filter.
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    64
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    65
|| *Value* || *Filter Selected*       ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    66
|| 0       || Small Tunnels           ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    67
|| 1       || Medium Tunnels          ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    68
|| 2       || Large Tunnels           ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    69
|| 3       || Small Floating Islands  ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    70
|| 4       || Medium Floating Islands ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    71
|| 5       || Large Floating Islands  ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    72
1096
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    73
Example: `e$maze_size 4`
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    74
745
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
    75
==== Image array ====
1096
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    76
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.
1
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    77
1096
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    78
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.
1
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    79
1096
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    80
_No example needed._
1
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    81
745
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
    82
== In-game ==
204
feee16fc7297 Edited wiki page EngineProtocol through web user interface.
kyberneticist@gmail.com
parents: 7
diff changeset
    83
1096
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    84
This document needs more fleshing out, but in the interest of contributing, submitting an image I'd made after reading a GCI task.
79417f0b3cfe EngineProtocol: Tweak formatting
Wuzzy
parents: 1095
diff changeset
    85
[https://hg.hedgewars.org/hedgewars/raw-file/default/doc/hwdemo.png 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).