EngineProtocol.wiki
author almikes@aol.com
Wed, 03 Dec 2014 05:43:29 +0000
changeset 415 70961d4eef05
parent 205 e0e1e96e401b
child 587 8105e95297e3
permissions -rw-r--r--
Fixed misleading descriptions of GetState and SetState (use of bitmasks were not mentioned). Added commented examples.
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
2
ba21be2f1b7a toc + fix
vittorio.giovara@gmail.com
parents: 1
diff changeset
     4
<wiki:toc max_depth="3" />
ba21be2f1b7a toc + fix
vittorio.giovara@gmail.com
parents: 1
diff changeset
     5
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
     6
= Introduction =
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
     7
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
     8
The frontend interacts with the engine in two separate occasions:
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
     9
  * map preview generation;
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    10
  * game setup and statistics messages.
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    11
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    12
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
    13
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    14
= Map Preview =
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    15
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
    16
2
ba21be2f1b7a toc + fix
vittorio.giovara@gmail.com
parents: 1
diff changeset
    17
Files in which this protocol is implemented: [http://code.google.com/p/hedgewars/source/browse/QTfrontend/hwmap.cpp hwmapp.cpp], [http://code.google.com/p/hedgewars/source/browse/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
    18
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    19
== Protocol ==
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    20
|| *Frontend*      || *Engine*          || *Format*                  ||
2
ba21be2f1b7a toc + fix
vittorio.giovara@gmail.com
parents: 1
diff changeset
    21
|| UUID            ||                   || {{{eseed { ... }}}}       ||
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    22
|| Template Filter ||                   || {{{e$template_filter N}}} ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    23
|| Map Type        ||                   || {{{e$mapgen N}}}          ||
7
a50f628f1564 fixed e$maze_size (thanks prg)
vittorio.giovara@gmail.com
parents: 2
diff changeset
    24
|| Maze Value      ||                   || {{{e$maze_size N}}}       ||
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    25
||                 || 128x32 byte array || {{{0YSD3 ... FSAD0}}}     ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    26
2
ba21be2f1b7a toc + fix
vittorio.giovara@gmail.com
parents: 1
diff changeset
    27
== Message Format ==
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    28
=== UUID ===
1
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    29
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
    30
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    31
Example: _eseed {AERTB-62FASDSAD-NNIASDSADASD-12P}_
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
=== Template Filter ===
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    34
_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
    35
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    36
|| *Value* || *Filter Selected* ||
1
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    37
|| 0       || None              ||
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    38
|| 1       || Large             ||
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    39
|| 2       || Medium            ||
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    40
|| 3       || Small             ||
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    41
|| 4       || Cavern            ||
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    42
|| 5       || Wacky             ||
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    43
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    44
Example: _e$template_filter 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
=== Map Type ===
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    47
_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
    48
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    49
|| *Value* || *Map Type*   ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    50
|| 0       || Standard Map ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    51
|| 1       || Maze Map     ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    52
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    53
Example: _e$mapgen 1_
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
=== Maze Value ===
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    56
_N_ selects the type of maze selected, similarly to Template Filter
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    57
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    58
|| *Value* || *Filter Selected*       ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    59
|| 0       || Small Tunnels           ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    60
|| 1       || Medium Tunnels          ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    61
|| 2       || Large Tunnels           ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    62
|| 3       || Small Floating Islands  ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    63
|| 4       || Medium Floating Islands ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    64
|| 5       || Large Floating Islands  ||
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    65
7
a50f628f1564 fixed e$maze_size (thanks prg)
vittorio.giovara@gmail.com
parents: 2
diff changeset
    66
Example: _e$maze_size 4_
0
89253999c825 Map preview protocol documentation
vittorio.giovara@gmail.com
parents:
diff changeset
    67
2
ba21be2f1b7a toc + fix
vittorio.giovara@gmail.com
parents: 1
diff changeset
    68
=== Image Array ===
1
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    69
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
    70
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    71
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
    72
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    73
_No example needed_
d51ef96162d8 added explanation of returning array and fixed links
vittorio.giovara@gmail.com
parents: 0
diff changeset
    74
204
feee16fc7297 Edited wiki page EngineProtocol through web user interface.
kyberneticist@gmail.com
parents: 7
diff changeset
    75
= In-Game =
feee16fc7297 Edited wiki page EngineProtocol through web user interface.
kyberneticist@gmail.com
parents: 7
diff changeset
    76
feee16fc7297 Edited wiki page EngineProtocol through web user interface.
kyberneticist@gmail.com
parents: 7
diff changeset
    77
This doc needs more fleshing out, but in the interest of contributing, submitting an image I'd made after reading a GCI task.
205
e0e1e96e401b Edited wiki page EngineProtocol through web user interface.
kyberneticist@gmail.com
parents: 204
diff changeset
    78
[http://hedgewars.googlecode.com/hg/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).