EngineProtocol.wiki
author Wuzzy
Fri, 25 Mar 2016 11:48:33 +0000
changeset 799 e2c96c00f9f3
parent 798 30c5f1ebd552
child 1092 b26366ceabba
permissions -rw-r--r--
TODO: Fix external Qt documentation link
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:
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    11
  * map preview generation;
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    12
  * game setup and statistics messages.
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 ===
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    22
|| *Frontend*      || *Engine*          || *Format*                  ||
2
ba21be2f1b7a toc + fix
vittorio.giovara@gmail.com
parents: 1
diff changeset
    23
|| UUID            ||                   || {{{eseed { ... }}}}       ||
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    24
|| Template Filter ||                   || {{{e$template_filter N}}} ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    25
|| Map Type        ||                   || {{{e$mapgen N}}}          ||
7
a50f628f1564 fixed e$maze_size (thanks prg)
vittorio.giovara@gmail.com
parents: 2
diff changeset
    26
|| Maze Value      ||                   || {{{e$maze_size N}}}       ||
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    27
||                 || 128x32 byte array || {{{0YSD3 ... FSAD0}}}     ||
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 ===
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
    30
==== UUID ====
1
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    31
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.
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    32
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    33
Example: _eseed {AERTB-62FASDSAD-NNIASDSADASD-12P}_
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    34
745
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
    35
==== Template filter ====
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    36
_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.
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    37
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    38
|| *Value* || *Filter Selected* ||
1
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    39
|| 0       || None              ||
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    40
|| 1       || Large             ||
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    41
|| 2       || Medium            ||
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    42
|| 3       || Small             ||
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    43
|| 4       || Cavern            ||
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    44
|| 5       || Wacky             ||
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    45
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    46
Example: _e$template_filter 0_
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    47
745
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
    48
==== Map type ====
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    49
_N_ is a boolean variable (0/1) that selects standard map generation or maze map generation.
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    50
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    51
|| *Value* || *Map Type*   ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    52
|| 0       || Standard Map ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    53
|| 1       || Maze Map     ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    54
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    55
Example: _e$mapgen 1_
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    56
745
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
    57
==== Maze value ====
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    58
_N_ selects the type of maze selected, similarly to Template Filter
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    59
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    60
|| *Value* || *Filter Selected*       ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    61
|| 0       || Small Tunnels           ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    62
|| 1       || Medium Tunnels          ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    63
|| 2       || Large Tunnels           ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    64
|| 3       || Small Floating Islands  ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    65
|| 4       || Medium Floating Islands ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    66
|| 5       || Large Floating Islands  ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    67
7
a50f628f1564 fixed e$maze_size (thanks prg)
vittorio.giovara@gmail.com
parents: 2
diff changeset
    68
Example: _e$maze_size 4_
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    69
745
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
    70
==== Image array ====
1
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    71
The reply from engine is a 128x32 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.
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    72
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    73
This image format is supported by many platforms, but it's very easy to parse anyways. The result is always a 256x128 pixel image.
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    74
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    75
_No example needed_
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    76
745
99da4e68bc64 EngineProtocol: Add title
Wuzzy
parents: 592
diff changeset
    77
== In-game ==
204
feee16fc7297 Edited wiki page EngineProtocol through web user interface.
kyberneticist@gmail.com
parents: 7
diff changeset
    78
feee16fc7297 Edited wiki page EngineProtocol through web user interface.
kyberneticist@gmail.com
parents: 7
diff changeset
    79
This doc needs more fleshing out, but in the interest of contributing, submitting an image I'd made after reading a GCI task.
798
30c5f1ebd552 global replace of http with https for hedgewars.org wiki links
nemo
parents: 745
diff changeset
    80
[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.  BTW, 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 for why).