DrawnMapFormat.wiki
author Wuzzy
Thu, 05 Dec 2019 17:37:56 +0000
changeset 2116 4ec7db0d0e06
parent 2115 43bd12e66491
child 2117 14fa1f3ec020
permissions -rw-r--r--
DrawnMapFormat: remove HedgeEditor link
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
1222
111d15f81dbd DrawnMapFormat: Fix typos
Wuzzy
parents: 798
diff changeset
    26
Second and further points of polyline have 8th bit of *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
2113
115b171c7e3e DrawnMapFormat: More about polylines
Wuzzy
parents: 2112
diff changeset
    28
A polyline begins when a point with the 8th bit in flags was set. Subsequent points will extend the 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. A single-point polyline defines a circle.
115b171c7e3e DrawnMapFormat: More about polylines
Wuzzy
parents: 2112
diff changeset
    29
2115
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    30
=== Special points ===
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    31
The file format supports special points. Special points are points that are not actually drawn but used to store coordinates alongside 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.
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    32
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    33
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.
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    34
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    35
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
    36
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    37
==== Usage in scripts ====
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    38
This section explains how the special points are used in various official scripts.
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    39
2116
4ec7db0d0e06 DrawnMapFormat: remove HedgeEditor link
Wuzzy
parents: 2115
diff changeset
    40
===== !HedgeEditor =====
4ec7db0d0e06 DrawnMapFormat: remove HedgeEditor link
Wuzzy
parents: 2115
diff changeset
    41
!HedgeEditor uses special points to spawn various gears and other things such as mines, crates or waypoints. Consult the script file to find out how they work.
2115
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    42
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    43
===== Racer =====
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    44
The special points are used to store coordinates of waypoints. This is utilized by the Official Racer Challenge on the official server.
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    45
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    46
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.
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    47
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    48
===== TechRacer =====
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    49
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    50
* `flags == 0`: Waypoint
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    51
* `flags == 99`: A position of the best racer ghost (like in Racer)
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    52
* Otherwise: Place a gear or girder (see script source code for reference)
43bd12e66491 DrawnMapFormat: All about special points
Wuzzy
parents: 2113
diff changeset
    53
2113
115b171c7e3e DrawnMapFormat: More about polylines
Wuzzy
parents: 2112
diff changeset
    54
=== Compression ===
115b171c7e3e DrawnMapFormat: More about polylines
Wuzzy
parents: 2112
diff changeset
    55
115b171c7e3e DrawnMapFormat: More about polylines
Wuzzy
parents: 2112
diff changeset
    56
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
    57
f38a002a0796 Give the article more flesh
Wuzzy
parents: 432
diff changeset
    58
== Sharing hand-drawn maps ==
f38a002a0796 Give the article more flesh
Wuzzy
parents: 432
diff changeset
    59
Hand-drawn maps will be automatically transferred when playing online.
f38a002a0796 Give the article more flesh
Wuzzy
parents: 432
diff changeset
    60
1681
nemo
parents: 1621
diff changeset
    61
But if you wish you can still share your creations in the [https://www.hedgewars.org/node/2849 Hand-Drawn Maps Submission Thread].