#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 the start bit in `flags` unset, the content of others are ignored for those.

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.

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

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.

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

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

----

== Appendix: Usage of special points 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 ===

!TechRacer is similar to Racer, but has more features. Depending on the `flags` value, different things happen when a special point is read:

|| *Value* || *Action* ||

|| 0 || Place waypoint ||

|| 98 || Read portal distance from X coordinate and flying saucer fuel from Y coordinate ||

|| 99 || A coordinate for the smoke trace of the best racer. Used in Official Racer Challenge ||

Additionally, with one of these values, a gear is spawned:

|| *Value* || *Object* ||

|| 1 || Mine (0s) ||

|| 2 || Mine (1s) ||

|| 3 || Mine (2s) ||

|| 4 || Mine (3s) ||

|| 5 || Mine (4s) ||

|| 6 || Mine (5s) ||

|| 7 || Sticky mine ||

|| 8 || Air mine ||

|| 9 || Health crate (25 HP) ||

|| 10 || Health crate (50 HP) ||

|| 11 || Health crate (75 HP) ||

|| 12 || Health crate (100 HP) ||

|| 13 || Cleaver ||

|| 14 || Target ||

|| 15 || Barrel (1 HP) ||

|| 16 || Barrel (25 HP) ||

|| 17 || Barrel (50 HP) ||

|| 18 || Barrel (75 HP) ||

|| 19 || Barrel (100 HP) ||

|| 20-82 || Weapon/utility crate (each number is a different [AmmoTypes ammo type]) ||

|| 100-107 || Girder ||

|| 108-115 || Indestructible girder ||

|| 116-123 || Icy girder ||

|| 124-127 || Rubber ||

=== !HedgeEditor ===

!HedgeEditor uses special points to spawn gears and other things. It supports the same `flags` values as in !TechRacer, except 99.