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

=== Special points ===

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.