Back to homepage
DrawnMapFormat
History
Short description of the file format of hand-drawn maps
Updated Thu, 05 Dec 2019 18:11:15 +0000 by Wuzzy

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