PresetMaps.wiki
author Wuzzy
Fri, 27 Nov 2020 13:45:03 +0100
changeset 2200 b285ffef13e0
parent 2057 c95da15c5fb1
permissions -rw-r--r--
Translations: Add TOC
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
279
1d9a5422d1b9 Edited wiki page PresetMaps through web user interface.
sheepyluva@gmail.com
parents: 264
diff changeset
     1
#summary This page describes the technically relevant aspects of preset maps in Hedgewars
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
     2
747
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
     3
= Image maps and mission maps =
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
     4
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
     5
<wiki:toc max_depth="3" />
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
     6
747
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
     7
== Introduction ==
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
     8
2055
b1e2a98c4c26 PresetMaps: paragraph
Wuzzy
parents: 2054
diff changeset
     9
One of the map types Hedgewars supports are maps that were previously drawn by an artist. These are called “image maps” because they use an image file (PNG). The looks of such maps are distinctly defined and are not subject to randomized values.
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    10
2055
b1e2a98c4c26 PresetMaps: paragraph
Wuzzy
parents: 2054
diff changeset
    11
Additionally, these image maps allow [LuaGuide Lua-script] to be associated with them in order to enable adding specific gameplay changes and map behavior, these are called “mission maps”.
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    12
1663
8437809648e4 PresetMaps: Add summary
Wuzzy
parents: 1628
diff changeset
    13
== Summary ==
8437809648e4 PresetMaps: Add summary
Wuzzy
parents: 1628
diff changeset
    14
1664
7c3a4fe7ad4e PresetMaps: clarify
Wuzzy
parents: 1663
diff changeset
    15
Put all map files into `Data/Maps/<YOUR MAP NME>`.
1663
8437809648e4 PresetMaps: Add summary
Wuzzy
parents: 1628
diff changeset
    16
8437809648e4 PresetMaps: Add summary
Wuzzy
parents: 1628
diff changeset
    17
Files:
8437809648e4 PresetMaps: Add summary
Wuzzy
parents: 1628
diff changeset
    18
8437809648e4 PresetMaps: Add summary
Wuzzy
parents: 1628
diff changeset
    19
 * `map.png`: Map in PNG format
8437809648e4 PresetMaps: Add summary
Wuzzy
parents: 1628
diff changeset
    20
 * `preview.png`: Preview image of map. 256×128 PNG image
8437809648e4 PresetMaps: Add summary
Wuzzy
parents: 1628
diff changeset
    21
 * `map.cfg`: Map configuration.
8437809648e4 PresetMaps: Add summary
Wuzzy
parents: 1628
diff changeset
    22
     * First line: Default theme
8437809648e4 PresetMaps: Add summary
Wuzzy
parents: 1628
diff changeset
    23
     * Second line: Maximum recommended number of hedgehogs
8437809648e4 PresetMaps: Add summary
Wuzzy
parents: 1628
diff changeset
    24
 * `mask.png`: Optional map mask for custom land types
8437809648e4 PresetMaps: Add summary
Wuzzy
parents: 1628
diff changeset
    25
 * `map.lua`: Optional Lua script for mission maps
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    26
747
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
    27
== Location ==
2057
c95da15c5fb1 PresetMaps: fix link (2)
Wuzzy
parents: 2056
diff changeset
    28
All maps are automatically loaded from the [https://hedgewars.org/wiki/User_directory Hedgewars data directory].
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    29
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    30
In this directory there has to be a folder for every map, named after the desired map name.
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    31
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    32
*Examples:*
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    33
  * _Data/Maps/!MyVeryOwnMap_
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    34
  * _Data/Maps/Ropes_
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    35
  * _Data/Maps/Sheep_
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    36
  * etc.
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    37
747
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
    38
=== Mission maps ===
329
21830c0b19f3 Edited wiki page PresetMaps and added section for .hwp mission maps.
pntanasis@gmail.com
parents: 323
diff changeset
    39
21830c0b19f3 Edited wiki page PresetMaps and added section for .hwp mission maps.
pntanasis@gmail.com
parents: 323
diff changeset
    40
Missions may use preset maps that aren't located in the *Data/Maps* directory.
21830c0b19f3 Edited wiki page PresetMaps and added section for .hwp mission maps.
pntanasis@gmail.com
parents: 323
diff changeset
    41
21830c0b19f3 Edited wiki page PresetMaps and added section for .hwp mission maps.
pntanasis@gmail.com
parents: 323
diff changeset
    42
A mission may contain in the same directory with mission's lua script a .hwp file.
21830c0b19f3 Edited wiki page PresetMaps and added section for .hwp mission maps.
pntanasis@gmail.com
parents: 323
diff changeset
    43
21830c0b19f3 Edited wiki page PresetMaps and added section for .hwp mission maps.
pntanasis@gmail.com
parents: 323
diff changeset
    44
This file is a zip file with an altered extension from *.zip* to *.hwp* and it contains the directory *Maps/some_name*.
21830c0b19f3 Edited wiki page PresetMaps and added section for .hwp mission maps.
pntanasis@gmail.com
parents: 323
diff changeset
    45
21830c0b19f3 Edited wiki page PresetMaps and added section for .hwp mission maps.
pntanasis@gmail.com
parents: 323
diff changeset
    46
In the *some_name* directory the files map.cfg, map.png and mask.png are located. See the Basic Files section for more on these files.
21830c0b19f3 Edited wiki page PresetMaps and added section for .hwp mission maps.
pntanasis@gmail.com
parents: 323
diff changeset
    47
21830c0b19f3 Edited wiki page PresetMaps and added section for .hwp mission maps.
pntanasis@gmail.com
parents: 323
diff changeset
    48
The name of the *.hwp* file should be the same with the mission script.
21830c0b19f3 Edited wiki page PresetMaps and added section for .hwp mission maps.
pntanasis@gmail.com
parents: 323
diff changeset
    49
1805
d18970cf6ca2 Update other pages for new Lua documentation structure
Wuzzy <almikes@aol.com>
parents: 1664
diff changeset
    50
In the mission script’s `onGameInit`, map should be set to *some_name*. See [LuaEvents] for more about `onGameInit`.
329
21830c0b19f3 Edited wiki page PresetMaps and added section for .hwp mission maps.
pntanasis@gmail.com
parents: 323
diff changeset
    51
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    52
----
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    53
747
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
    54
== Files ==
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    55
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    56
Within the folder of every map the following files are expected to be there:
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    57
747
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
    58
=== Basic files ===
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
    59
==== `map.cfg` ====
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    60
Configuration file.
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    61
1627
78e2e7e2f17b PresetMaps: rewrite
Wuzzy
parents: 1626
diff changeset
    62
  * First line is the name of the default [Themes theme] used by the map (for background and clouds, flakes, water, etc). Select a theme that fits to your map
1626
fe408c987679 PresetMaps: theme
Wuzzy
parents: 1625
diff changeset
    63
  * Second line is max. number of hedgehogs supported. If the second line is not provided, it is assumed to be 18. Note that Hedgewars currently does not support games with more than 64 hedgehogs
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    64
747
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
    65
==== `map.png` ====
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    66
Image of visible land area.
1007
74af6339638b PresetMaps: map.png type
Wuzzy
parents: 798
diff changeset
    67
  * 32-bit PNG with alpha channel
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    68
  * Usually _width/length ratio_ of 2:1
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    69
  * Typical size: 2048 x 1024
339
1664d3e63c05 Geek out a bit on map dimension constraints.
kyberneticist@gmail.com
parents: 336
diff changeset
    70
  * Max size: no limit, 0.9.18+.  4096 x 2048 or less in 0.9.17 and earlier.  There are a few practical limits to map size that should be examined for people trying to make very large maps.
371
3f01f1fd7bb3 Edited wiki page PresetMaps through web user interface.
kyberneticist@gmail.com
parents: 370
diff changeset
    71
    * SDL 1.2 - SDL 1.2 can only load maps that are <=16,384px wide, and <=65,536px high. SDL 1.2 rect is only capable of handling a map that is <=32768 high, while behaviour in Hedgewars 0.9.20 or lower forces <=16,384 if using a mask.png without a map.png.
344
477866a345aa More being nerdy about map sizes.
kyberneticist@gmail.com
parents: 343
diff changeset
    72
    * SDL 2.0 - SDL 2.0 failed to load a 999,936x512 map. A 499,968x512 map succeeded. Those would use ~244MiB/~122MiB of your graphics card with Blurry Land enabled, and ~977MiB/~488MiB without it.
341
763c9378cb7f No. Wait # is numbers. It actually uses indentation..
kyberneticist@gmail.com
parents: 340
diff changeset
    73
    * GIMP.  GIMP 2.8 can only create PNGs that are 262,144px wide or high - is an arbitrary hardcoded sanity check.  GIMP 2.10 allows 524,288 wide or high.
343
eaa95eb40e0f Edited wiki page PresetMaps through web user interface.
kyberneticist@gmail.com
parents: 342
diff changeset
    74
    * libpng - libpng can only load maps that are < 1 million px wide or high, with default configuration.
341
763c9378cb7f No. Wait # is numbers. It actually uses indentation..
kyberneticist@gmail.com
parents: 340
diff changeset
    75
    * Graphics card. This is the big one. Your graphics card probably has anywhere from 256MiB to 2GiB of vRAM.  If blurry land is enabled and the map has a typical amount of empty space, you can make a map w/ ~2x the pixels as a card has vRAM. But. Most people don't like using Blurry Land, so best to limit to ~½ the pixels as a card has vRAM. Targetting support for people on 256MiB of vRAM, that means a 2:1 rectangular map should not be larger than 16,384x8192 which coincidentally fits in the SDL 1.2 width limit.
763c9378cb7f No. Wait # is numbers. It actually uses indentation..
kyberneticist@gmail.com
parents: 340
diff changeset
    76
    * There is also a completely arbitrary check in game for widths/height < ~billion pixels which avoids possible integer issues, and a limit on size in pixels of 6 billion or so, which was just a basic sanity limit.  However given the limitations above, these are not likely to be reached.
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    77
  * If there is no _mask.png_, this image will also be used for deciding what pixels are subject to collision: _alpha value_ not equal to 0 (so below max transparency) will be considered land
345
3027ad3155d5 Edited wiki page PresetMaps through web user interface.
kyberneticist@gmail.com
parents: 344
diff changeset
    78
  * As of 0.9.19+, map.png is optional if a mask.png is provided.  If there is no map.png, the theme will be used to decorate the map.  No objects will be added to white areas.  Use black if you want objects.
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    79
747
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
    80
==== `preview.png` ====
1628
893c8b5bf7e7 PresetMaps: preview 2
Wuzzy
parents: 1627
diff changeset
    81
Preview image of the map to show how the map would actually look like in the game, minus the background. Usually this is just a smaller version of `map.png`, so in most cases you can just downscale `map.png` to get your preview.
1624
fd7919693076 PresetMaps: preview.png rant
Wuzzy
parents: 1209
diff changeset
    82
1628
893c8b5bf7e7 PresetMaps: preview 2
Wuzzy
parents: 1627
diff changeset
    83
This should really just be a preview, and nothing else. No logos, text, theme background or other distractions that don't exist on the map.
1209
fac5831027bd PresetMaps: Request to stop abusing preview.png
Wuzzy
parents: 1161
diff changeset
    84
fac5831027bd PresetMaps: Request to stop abusing preview.png
Wuzzy
parents: 1161
diff changeset
    85
  * Size: 256 × 128
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    86
747
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
    87
=== Optional files (for advanced features and adjustments) ===
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
    88
==== `mask.png` ====
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    89
Image defining the collision areas of the map.
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    90
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    91
  * Pixels with _alpha value_ = 0 will not be subject to collision
436
0afdd1b1042c Some basic clarifications about mask, add link to nemo’s mask guide, add link to Pngcrush, some typographic improvements.
almikes@aol.com
parents: 372
diff changeset
    92
  * White (255, 255, 255) pixels will be terrain, no background texture will be shown when it is destroyed.
0afdd1b1042c Some basic clarifications about mask, add link to nemo’s mask guide, add link to Pngcrush, some typographic improvements.
almikes@aol.com
parents: 372
diff changeset
    93
  * Black (0, 0, 0) pixels will be terrain with background texture applied (Note: Adding any black pixels removes erasure protection from areas where the map.png is solid but the mask.png is transparent) - 0.9.17+
0afdd1b1042c Some basic clarifications about mask, add link to nemo’s mask guide, add link to Pngcrush, some typographic improvements.
almikes@aol.com
parents: 372
diff changeset
    94
  * Red (255, 0, 0) pixels will be indestructible terrain (regardless of game mode settings)
0afdd1b1042c Some basic clarifications about mask, add link to nemo’s mask guide, add link to Pngcrush, some typographic improvements.
almikes@aol.com
parents: 372
diff changeset
    95
  * Blue (0, 0, 255) pixels will be ice - 0.9.17+
559
43337323f97a Clarified the instructions for non-portal surfaces without bouncy
almikes@aol.com
parents: 436
diff changeset
    96
  * Green (0, 255, 0) pixels are bouncy (since 0.9.20) and block portals (since 0.9.18). This mask can be used normally for maps or theme objects. If bouncing is implemented and the green pixels should only block portals, place a dotted line of single red or black or white pixels 3 pixels above the green, spaced 3 pixels apart each. This will keep most objects from interacting with the green, but prevent portal spawning.
436
0afdd1b1042c Some basic clarifications about mask, add link to nemo’s mask guide, add link to Pngcrush, some typographic improvements.
almikes@aol.com
parents: 372
diff changeset
    97
798
30c5f1ebd552 global replace of http with https for hedgewars.org wiki links
nemo
parents: 747
diff changeset
    98
It is recommended that your file _only_ consists of pixels which have one of the values above. This ensures that the masks works properly for your map and avoids unexpected behaviour. Also, it makes your file significantly smaller. [https://www.hedgewars.org/node/3339 Here] is a simple guide describing how you can ensure that.
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
    99
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
   100
*Examples:*
798
30c5f1ebd552 global replace of http with https for hedgewars.org wiki links
nemo
parents: 747
diff changeset
   101
  * [https://hg.hedgewars.org/hedgewars/raw-file/default/share/hedgewars/Data/Maps/portal/mask.png Mask] of [https://hg.hedgewars.org/hedgewars/raw-file/default/share/hedgewars/Data/Maps/portal/map.png Portal Map]
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
   102
(Transparent areas may not be recognizeable as such in your browser/image preview program, so open e.g. in [http://www.gimp.org/ Gimp])
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
   103
97
0803dadcc229 Edited wiki page PresetMaps through web user interface.
sheepyluva
parents: 96
diff changeset
   104
747
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
   105
==== `map.lua` ====
436
0afdd1b1042c Some basic clarifications about mask, add link to nemo’s mask guide, add link to Pngcrush, some typographic improvements.
almikes@aol.com
parents: 372
diff changeset
   106
A Lua script to be used together with the map.
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
   107
436
0afdd1b1042c Some basic clarifications about mask, add link to nemo’s mask guide, add link to Pngcrush, some typographic improvements.
almikes@aol.com
parents: 372
diff changeset
   108
See the LuaGuide for more information on Hedgewars’ scripting support.
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
   109
747
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
   110
=== Image format ===
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
   111
  * PNG, 8-bit/color RGBA (so 32 bit)
436
0afdd1b1042c Some basic clarifications about mask, add link to nemo’s mask guide, add link to Pngcrush, some typographic improvements.
almikes@aol.com
parents: 372
diff changeset
   112
  * Gamma correction and colour profiles should not be applied, in order to ensure the map is loaded identically on OSX as it is on other operating systems by SDL. To ensure this happens, please run in the command-line (requires Pngcrush):
0afdd1b1042c Some basic clarifications about mask, add link to nemo’s mask guide, add link to Pngcrush, some typographic improvements.
almikes@aol.com
parents: 372
diff changeset
   113
<code language="bash">pngcrush -rem gAMA -rem cHRM -rem iCCP -rem sRGB old/map.png new/map.png</code>
0afdd1b1042c Some basic clarifications about mask, add link to nemo’s mask guide, add link to Pngcrush, some typographic improvements.
almikes@aol.com
parents: 372
diff changeset
   114
(Pngcrush is a command-line tool which can be found on [http://pmt.sourceforge.net/pngcrush/])
106
ee13fb16ebb5 Edited wiki page PresetMaps through web user interface.
kyberneticist
parents: 105
diff changeset
   115
105
5aafdbd7206f Edited wiki page PresetMaps through web user interface.
kyberneticist
parents: 97
diff changeset
   116
or be sure your image editing software has these options disabled.
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
   117
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
   118
----
747
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
   119
== Editing software recommendations ==
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
   120
=== Images ===
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
   121
A vector based drawing software is recommended for creating the maps.
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
   122
798
30c5f1ebd552 global replace of http with https for hedgewars.org wiki links
nemo
parents: 747
diff changeset
   123
(Reasons for that: Edges are usually automatically smoothed on export; Easier to meet [https://www.hedgewars.org/node/704 Hedgewars Graphics rules, style constraints, guidelines]; Images are easier to change, adjust and maintain style)
96
59ea111dd004 Created wiki page through web user interface.
sheepyluva
parents:
diff changeset
   124
667
08030f484762 Sharing
Wuzzy
parents: 592
diff changeset
   125
If you don't have one, check out the free open-source [http://inkscape.org Inkscape]: There are various [http://lmgtfy.com/?q=inkscape+tutorial Inkscape tutorials] online, so you should be able to get started easily.
08030f484762 Sharing
Wuzzy
parents: 592
diff changeset
   126
747
5b084a7e8574 PresetMaps: Add title, fix header levels
Wuzzy
parents: 667
diff changeset
   127
== Sharing image maps ==
667
08030f484762 Sharing
Wuzzy
parents: 592
diff changeset
   128
You can only play a game with a custom image map against other players online if all participating players have the image map installed under the same name.
08030f484762 Sharing
Wuzzy
parents: 592
diff changeset
   129
08030f484762 Sharing
Wuzzy
parents: 592
diff changeset
   130
If any player does not have the image map installed, the game will fail to start and an error message is displayed.
08030f484762 Sharing
Wuzzy
parents: 592
diff changeset
   131
1812
30b86a49f9a8 PresetMaps: fix bg
Wuzzy
parents: 1805
diff changeset
   132
If you wish, you can post your custom-made image map in the [https://www.hedgewars.org/forum/19 Content Creations] forum.