#summary Short description of the file format of hand-drawn maps

= Hand-drawn maps =

== Introduction ==

Hand-drawn maps are maps which are created by the player using the in-game map editor.

== File storage ==

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.

== File format ==

The raw format is defined as follows:

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.

A point is defined as

|| Big-endian int16 || Big-endian int16 || Byte ||

|| *X* coordinate || *Y* coordinate || *flags* ||

where *flags* are:

|| 8th bit || 7th bit || 6th-1st bits ||

|| if set, this is a first point of polyline (“start” bit) || if set, polyline is erasing || *width* (thickness) of line ||

… where *width* defines `(width * 10) + 6` pixels width line to draw.

Second and further points of polyline have 8th bit of *flags* unset, the content of others are ignored for those.

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.

=== Special points ===

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.

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.

When Hedgewars loads a drawn map with special points inside, `onSpecialPoint` is called for each special point.

==== Usage in scripts ====

This section explains how the special points are used in various official scripts.

===== Racer =====

The special points are used to store coordinates of waypoints. This is utilized by the Official Racer Challenge on the official server.

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.

===== TechRacer =====

* `flags == 0`: Waypoint

* `flags == 99`: A position of the best racer ghost (like in Racer)

* Otherwise: Place a gear or girder (see script source code for reference)

=== Compression ===

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].

== Sharing hand-drawn maps ==

Hand-drawn maps will be automatically transferred when playing online.

But if you wish you can still share your creations in the [https://www.hedgewars.org/node/2849 Hand-Drawn Maps Submission Thread].