DrawnMapFormat.wiki
author Wuzzy
Wed, 08 Jul 2020 18:29:47 +0200
changeset 2173 ad42ab030bd8
parent 2122 9f81b4289d36
permissions -rw-r--r--
TODO: update resurrect
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
432
e441f3f51dac Add summary
almikes@aol.com
parents: 226
diff changeset
     1
#summary Short description of the file format of hand-drawn maps
e441f3f51dac Add summary
almikes@aol.com
parents: 226
diff changeset
     2
748
2051f403ddac DrawnMapFormat: Add title
Wuzzy
parents: 666
diff changeset
     3
= Hand-drawn maps =
666
f38a002a0796 Give the article more flesh
Wuzzy
parents: 432
diff changeset
     4
== Introduction ==
f38a002a0796 Give the article more flesh
Wuzzy
parents: 432
diff changeset
     5
Hand-drawn maps are maps which are created by the player using the in-game map editor.
f38a002a0796 Give the article more flesh
Wuzzy
parents: 432
diff changeset
     6
2113
115b171c7e3e DrawnMapFormat: More about polylines
Wuzzy
parents: 2112
diff changeset
     7
== File storage ==
115b171c7e3e DrawnMapFormat: More about polylines
Wuzzy
parents: 2112
diff changeset
     8
Hand-drawn maps are saved with a file name suffix of “.hwmap”. By default, drawn maps are stored in a directory called “DrawnMaps” in the user directory, but the player could choose any location.
115b171c7e3e DrawnMapFormat: More about polylines
Wuzzy
parents: 2112
diff changeset
     9
2115
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    10
== File format ==
1621
41a7f751b77b DrawnMapFormat: Warning about outdatec file spec
Wuzzy
parents: 1222
diff changeset
    11
2115
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    12
The raw format is defined as follows:
666
f38a002a0796 Give the article more flesh
Wuzzy
parents: 432
diff changeset
    13
2115
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    14
A drawn map is described by a sequence of points, which define polylines to draw and format of each polyline. Each point has an X and Y coordinate (16bit each) and a `flags` field (size of 1 Byte) for additional data.
226
6ca639109e95 Created wiki page through web user interface.
unC0Rr@gmail.com
parents:
diff changeset
    15
2113
115b171c7e3e DrawnMapFormat: More about polylines
Wuzzy
parents: 2112
diff changeset
    16
A point is defined as
226
6ca639109e95 Created wiki page through web user interface.
unC0Rr@gmail.com
parents:
diff changeset
    17
|| Big-endian int16 || Big-endian int16 || Byte ||
6ca639109e95 Created wiki page through web user interface.
unC0Rr@gmail.com
parents:
diff changeset
    18
|| *X* coordinate || *Y* coordinate || *flags* ||
6ca639109e95 Created wiki page through web user interface.
unC0Rr@gmail.com
parents:
diff changeset
    19
6ca639109e95 Created wiki page through web user interface.
unC0Rr@gmail.com
parents:
diff changeset
    20
where *flags* are:
6ca639109e95 Created wiki page through web user interface.
unC0Rr@gmail.com
parents:
diff changeset
    21
|| 8th bit || 7th bit || 6th-1st bits ||
2113
115b171c7e3e DrawnMapFormat: More about polylines
Wuzzy
parents: 2112
diff changeset
    22
|| if set, this is a first point of polyline (“start” bit) || if set, polyline is erasing || *width* (thickness) of line ||
226
6ca639109e95 Created wiki page through web user interface.
unC0Rr@gmail.com
parents:
diff changeset
    23
1222
111d15f81dbd DrawnMapFormat: Fix typos
Wuzzy
parents: 798
diff changeset
    24
… where *width* defines `(width * 10) + 6` pixels width line to draw.
226
6ca639109e95 Created wiki page through web user interface.
unC0Rr@gmail.com
parents:
diff changeset
    25
2122
9f81b4289d36 DrawnMapFormat: Edited via web interface
Wuzzy
parents: 2121
diff changeset
    26
Second and further points of polyline have the start bit in `flags` unset, the content of others are ignored for those.
226
6ca639109e95 Created wiki page through web user interface.
unC0Rr@gmail.com
parents:
diff changeset
    27
2122
9f81b4289d36 DrawnMapFormat: Edited via web interface
Wuzzy
parents: 2121
diff changeset
    28
A polyline begins when a point with the start bit was set. Subsequent points will extend this line as long the “start” bit of those is not set. A new line starts when another point appears with the “start” bit being set.
9f81b4289d36 DrawnMapFormat: Edited via web interface
Wuzzy
parents: 2121
diff changeset
    29
9f81b4289d36 DrawnMapFormat: Edited via web interface
Wuzzy
parents: 2121
diff changeset
    30
A single-point polyline defines a circle.
2113
115b171c7e3e DrawnMapFormat: More about polylines
Wuzzy
parents: 2112
diff changeset
    31
2115
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    32
=== Special points ===
2122
9f81b4289d36 DrawnMapFormat: Edited via web interface
Wuzzy
parents: 2121
diff changeset
    33
The file format supports special points. Special points are points that are not actually drawn but used to store coordinates and arbitrary values. Points are considered special if the first point in the file does not have the “start” bit set. If this is the case, all points up until the first point with the “start” bit set are considered special. The first point with the “start” bit will then mark the start of the first “real” line, as usual.
2115
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    34
2122
9f81b4289d36 DrawnMapFormat: Edited via web interface
Wuzzy
parents: 2121
diff changeset
    35
The X and Y fields store coordinates, but they might also be abused to store arbitrary numbers. The other bits in the `flags` field can also be used to store an arbitrary number. Because the 8th bit is already used, only numbers 0-127 are possible for data storage.
2115
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    36
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    37
When Hedgewars loads a drawn map with special points inside, `onSpecialPoint` is called for each special point.
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    38
2113
115b171c7e3e DrawnMapFormat: More about polylines
Wuzzy
parents: 2112
diff changeset
    39
=== Compression ===
115b171c7e3e DrawnMapFormat: More about polylines
Wuzzy
parents: 2112
diff changeset
    40
115b171c7e3e DrawnMapFormat: More about polylines
Wuzzy
parents: 2112
diff changeset
    41
Above description describes the raw data, but the final file will be changed. The raw data is first base64-encoded and then compressed with [https://doc.qt.io/qt-5/qbytearray.html#qCompress Qt's `qCompress` function].
666
f38a002a0796 Give the article more flesh
Wuzzy
parents: 432
diff changeset
    42
f38a002a0796 Give the article more flesh
Wuzzy
parents: 432
diff changeset
    43
== Sharing hand-drawn maps ==
f38a002a0796 Give the article more flesh
Wuzzy
parents: 432
diff changeset
    44
Hand-drawn maps will be automatically transferred when playing online.
f38a002a0796 Give the article more flesh
Wuzzy
parents: 432
diff changeset
    45
1681
nemo
parents: 1621
diff changeset
    46
But if you wish you can still share your creations in the [https://www.hedgewars.org/node/2849 Hand-Drawn Maps Submission Thread].
2118
0599403a78ad DrawnMapFormat: fix syntax
Wuzzy
parents: 2117
diff changeset
    47
2119
d0b95475744d DrawnMapFormat: Edited via web interface
Wuzzy
parents: 2118
diff changeset
    48
----
2118
0599403a78ad DrawnMapFormat: fix syntax
Wuzzy
parents: 2117
diff changeset
    49
0599403a78ad DrawnMapFormat: fix syntax
Wuzzy
parents: 2117
diff changeset
    50
== Appendix: Usage of special points in scripts ==
0599403a78ad DrawnMapFormat: fix syntax
Wuzzy
parents: 2117
diff changeset
    51
This section explains how the special points are used in various official scripts.
0599403a78ad DrawnMapFormat: fix syntax
Wuzzy
parents: 2117
diff changeset
    52
0599403a78ad DrawnMapFormat: fix syntax
Wuzzy
parents: 2117
diff changeset
    53
=== Racer ===
0599403a78ad DrawnMapFormat: fix syntax
Wuzzy
parents: 2117
diff changeset
    54
The special points are used to store coordinates of waypoints. This is utilized by the Official Racer Challenge on the official server.
0599403a78ad DrawnMapFormat: fix syntax
Wuzzy
parents: 2117
diff changeset
    55
0599403a78ad DrawnMapFormat: fix syntax
Wuzzy
parents: 2117
diff changeset
    56
If `flags` is set to exactly 99, it's a coordinate for the “best racer ghost” or smoke trace. This is also used for Official Racer Challenge.
0599403a78ad DrawnMapFormat: fix syntax
Wuzzy
parents: 2117
diff changeset
    57
0599403a78ad DrawnMapFormat: fix syntax
Wuzzy
parents: 2117
diff changeset
    58
=== !TechRacer ===
0599403a78ad DrawnMapFormat: fix syntax
Wuzzy
parents: 2117
diff changeset
    59
2120
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    60
!TechRacer is similar to Racer, but has more features. Depending on the `flags` value, different things happen when a special point is read:
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    61
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    62
|| *Value* || *Action* ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    63
|| 0 || Place waypoint ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    64
|| 98 || Read portal distance from X coordinate and flying saucer fuel from Y coordinate ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    65
|| 99 || A coordinate for the smoke trace of the best racer. Used in Official Racer Challenge ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    66
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    67
Additionally, with one of these values, a gear is spawned:
2118
0599403a78ad DrawnMapFormat: fix syntax
Wuzzy
parents: 2117
diff changeset
    68
2120
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    69
|| *Value* || *Object* ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    70
|| 1 || Mine (0s) ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    71
|| 2 || Mine (1s) ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    72
|| 3 || Mine (2s) ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    73
|| 4 || Mine (3s) ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    74
|| 5 || Mine (4s) ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    75
|| 6 || Mine (5s) ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    76
|| 7 || Sticky mine ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    77
|| 8 || Air mine ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    78
|| 9 || Health crate (25 HP) ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    79
|| 10 || Health crate (50 HP) ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    80
|| 11 || Health crate (75 HP) ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    81
|| 12 || Health crate (100 HP) ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    82
|| 13 || Cleaver ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    83
|| 14 || Target ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    84
|| 15 || Barrel (1 HP) ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    85
|| 16 || Barrel (25 HP) ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    86
|| 17 || Barrel (50 HP) ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    87
|| 18 || Barrel (75 HP) ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    88
|| 19 || Barrel (100 HP) ||
2121
c79a36615390 DrawnMapFormat: fix typo
Wuzzy
parents: 2120
diff changeset
    89
|| 20-82 || Weapon/utility crate (each number is a different [AmmoTypes ammo type]) ||
2120
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    90
|| 100-107 || Girder ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    91
|| 108-115 || Indestructible girder ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    92
|| 116-123 || Icy girder ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    93
|| 124-127 || Rubber ||
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    94
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    95
=== !HedgeEditor ===
2e561c57e750 DrawnMapFormat: Add gear table
Wuzzy
parents: 2119
diff changeset
    96
!HedgeEditor uses special points to spawn gears and other things. It supports the same `flags` values as in !TechRacer, except 99.