1 #summary Description of the HWP format, used to package custumizations of Hedgewars |
1 #summary Description of the HWP format, used to package custumizations of Hedgewars |
2 |
2 |
3 = HWP format = |
3 = HWP format = |
4 == Introduction == |
4 == Introduction == |
5 The HWP format provides a simple mechanism to package customizations of Hedgewars (maps, themes, sounds) in a single file. They are especially intended to be used to be shared online and to be installed without much hassle. |
5 The HWP format provides a simple mechanism to package customizations of Hedgewars (maps, themes, sounds) in a single file. HWP files have the suffix “.hwp”. They are especially intended to be used to be shared online and to be installed rapidliy. |
6 |
6 |
7 The file format provides an alternative to the “classical” method in which the user puts custom files directly into the user data directory. |
7 The file format provides an alternative to the “classical” method in which the user puts custom files directly into the user data directory. |
8 |
8 |
9 == Who uses HWP? == |
9 == Who uses HWP? == |
10 Chances are good that you already have used HWP files without knowing it. |
10 HWP files used in the “Downloadable Content” (DLC) section which can be accessed in the main-menu of Hedgewars or with your brower via [https://hedgewars.org/content.html]. Only HWP files are distributed there. |
11 |
|
12 HWP files used in the “Downloadable Content” section which can be accessed in the main-menu of Hedgewars or with your brower via [https://hedgewars.org/content.html]. Only HWP files are distributed there. |
|
13 |
11 |
14 The community-driven Hedgewars addon server [http://hh.unit22.org/ hh.unit22.org] only accepts HWP files. |
12 The community-driven Hedgewars addon server [http://hh.unit22.org/ hh.unit22.org] only accepts HWP files. |
15 |
13 |
16 HWP files are also commonly used to distribute custom files in the [https://hedgewars.org/forum webforums]. |
14 HWP files are also commonly used to distribute custom files in the [https://hedgewars.org/forum webforums]. |
17 |
15 |
18 HWP files are also used by a few scripts and missions, some of them even in the official game (see the section about sidecar HWPs). |
16 HWP files are also used by a few scripts and missions, some of them even in the official game (see the section about sidecar HWPs). |
19 |
17 |
20 == Using HWP == |
18 == Using HWP == |
21 If you have installed a new HWP anywhere, it will not be activated if Hedgewars is still running. New HWPs will only become active after you restarted Hedgewars. This is also true if you installed a HWP by downloading it via the Downloadable Content section. |
19 If you download any add-on from DLC, you must restart Hedgewars for the change to take effect. |
22 |
20 |
23 == Format specification == |
21 To install a HWP file manually, just put it in the `Data/` subdirectory of your [https://www.hedgewars.org/node/6761 user directory]. |
|
22 |
|
23 == Creating HWPs == |
|
24 === The short description === |
|
25 Creating a HWP is easy. |
|
26 |
|
27 A HWP file is just a Zip file, but with the file name suffix “.hwp” instead of “.zip”. They reflect the content of the `Data/` directory of Hedgewars. Any file in a HWP will be treated as if it were in the `Data` directory. |
|
28 |
|
29 ==== Example ==== |
|
30 Suppose you have made a theme with the name “!MyTheme_v1” (!MyTheme, version 1). If you want to package it in a HWP, you just create a Zip file (e.g. “MyTheme.zip”) with the following directory structure: |
|
31 |
|
32 ``` |
|
33 Themes |
|
34 MyTheme_v1 |
|
35 theme.cfg |
|
36 BlueWater.png |
|
37 SDWater.png |
|
38 horizont.png |
|
39 Sky.png |
|
40 (many other theme files) |
|
41 |
|
42 Then the only thing you need to do is to rename the Zip file to have the correct suffix, i.e. “MyTheme_v1.hwp”. Note only the suffix is important. The name before that can be whatever you like. |
|
43 |
|
44 If you're done, you probably want to test it as well. Just put your fresh HWP into the `Data/` directory, restart Hedgewars and check if the theme shows up. |
|
45 |
|
46 === The long description === |
|
47 HWPs have a couple additional features which allow you to do more sophisticated things. This section explains the HWP files in greater detail. |
|
48 |
|
49 ==== Format specification ==== |
24 Technically, a HWP file is actually just a Zip file with an unusual file name suffix. The specification of HWP files itself is thus identical to the specification of Zip files. |
50 Technically, a HWP file is actually just a Zip file with an unusual file name suffix. The specification of HWP files itself is thus identical to the specification of Zip files. |
25 |
51 |
26 The complete Zip file format specification can be found at [http://www.pkware.com/documents/casestudies/APPNOTE.TXT]. |
52 The complete Zip file format specification can be found at [http://www.pkware.com/documents/casestudies/APPNOTE.TXT]. |
27 |
53 |
28 == How Hedgewars uses HWPs == |
54 ==== How Hedgewars uses HWPs ==== |
29 All HWPs must have the file name suffix “.hwp” for Hedgewars to recognize it as such. This is a bit unusual, since the usual file name suffix for .ZIP files (which HWP files actually are) is “.zip”. Don’t worry about that, Hedgewars can cope with that. |
55 All HWPs must have the file name suffix “.hwp” for Hedgewars to recognize it as such. This is a bit unusual, since the usual file name suffix for .ZIP files (which HWP files actually are) is “.zip”. Don’t worry about that, Hedgewars can cope with that. |
30 |
56 |
31 HWP files reflect the content of the `Data/` directory of Hedgewars. Therefore, the structure of the HWP file must be as if it were inside the `Data/` directory of Hedgewars and using the same directory tree. |
57 HWP files reflect the content of the `Data/` directory of Hedgewars. Therefore, the structure of the HWP file must be as if it were inside the `Data/` directory of Hedgewars and using the same directory tree. |
32 |
58 |
33 HWP files will either add or replace a file. If there is no file with a identical name at the same sub-directory of `Data/`, then Hedgewars will simply add that file, making it available for Hedgewars. This is the most commonly used form of HWPs, used to create add-ons, like new missions, flag packs, themes, etc. If there is already a file with such a name there, Hedgewars will prefer the file in the HWP and ignore the other one. This has to be done with care, some files are safe to replace while other files cannot be simply replaced, as this will cause network games to fail. For example, if you have a HWP which replaces an object of a theme and you play that theme online, the online game will fail, unless your fellow players have the same HWP installed. |
59 HWP files will either add or replace a file. If there is no file with a identical name at the same sub-directory of `Data/`, then Hedgewars will simply add that file, making it available for Hedgewars. This is the most commonly used form of HWPs, used to create add-ons, like new missions, flag packs, themes, etc. If there is already a file with such a name there, Hedgewars will prefer the file in the HWP and ignore the other one. This has to be done with care, some files are safe to replace while other files cannot be simply replaced, as this will cause network games to fail. For example, if you have a HWP which replaces an object of a theme and you play that theme online, the online game will fail, unless your fellow players have the same HWP installed. |
34 |
60 |
35 It is a special case when you have multiple HWPs activated, when some of them try to include a file with identical name. This is a conflict, see the conflict section for more information about this. |
61 It is a special case when you have multiple HWPs activated, when some of them try to include a file with identical name. This is a conflict, see the conflict section for more information about this. |
36 |
62 |
37 ==== Custom sprites and sounds ==== |
63 ===== Custom sprites and sounds ===== |
38 For Lua scripts you can add a few custom sounds and sprites without actually replacing any useful resources. For this, Hedgewars offers a 8 dummy sprites and 8 dummy sounds which only exist so they can be added in a HWP. |
64 For Lua scripts you can add a few custom sounds and sprites without actually replacing any useful resources. For this, Hedgewars offers a 8 dummy sprites and 8 dummy sounds which only exist so they can be added in a HWP. |
39 |
65 |
40 The custom sprites are named `Graphics/custom1.png` to `Graphics/custom8.png` and are accessed in Lua with `sprCustom1` to `sprCustom8`. |
66 The custom sprites are named `Graphics/custom1.png` to `Graphics/custom8.png` and are accessed in Lua with `sprCustom1` to `sprCustom8`. |
41 |
67 |
42 The custom sounds are named `Sounds/custom1.ogg` to `Sounds/custom8.ogg` and are accessed in Lua with `sndCustom1` to `sndCustom8`. |
68 The custom sounds are named `Sounds/custom1.ogg` to `Sounds/custom8.ogg` and are accessed in Lua with `sndCustom1` to `sndCustom8`. |
43 |
69 |
44 ==== Custom ammo icons ==== |
70 ===== Custom ammo icons ===== |
45 Overwriting ammo icons is a special case. If `Graphics/AmmoMenu/Ammos.png` or `Graphics/AmmoMenu/Ammos_bw.png` is found in the HWP, it will be overlayed over the original images `Graphics/AmmoMenu/Ammos_base.png` and `Graphics/AmmoMenu/Ammos_bw_base.png`, respectively. This is useful if you only need to replace a few certain ammo icons, and not the entire set of ammo icons. This is especially important to ensure forwards-compability of your sidecar HWPs for your scripts (see below). |
71 Overwriting ammo icons is a special case. If `Graphics/AmmoMenu/Ammos.png` or `Graphics/AmmoMenu/Ammos_bw.png` is found in the HWP, it will be overlayed over the original images `Graphics/AmmoMenu/Ammos_base.png` and `Graphics/AmmoMenu/Ammos_bw_base.png`, respectively. This is useful if you only need to replace a few certain ammo icons, and not the entire set of ammo icons. This is especially important to ensure forwards-compability of your sidecar HWPs for your scripts (see below). |
46 |
72 |
47 For example, if you want to replace the “Air Attack” icon with a crosshair icon, but leave everything else alone, just draw the cross hair icon on the correct position and make all other frames fully transparent. |
73 For example, if you want to replace the “Air Attack” icon with a crosshair icon, but leave everything else alone, just draw the cross hair icon on the correct position and make all other frames fully transparent. |
48 |
74 |
49 == Possible locations for HWPs == |
75 === Possible locations for HWPs === |
50 |
76 |
51 === HWPs in `Data/` === |
77 ==== HWPs in `Data/` ==== |
52 The most common HWPs will be stored in the `Data/` directory of Hedgewars. Note that there are two `Data/` directories for Hedgewars, one is system-wide and one is intended for the current user. In case of conflicts between both, the user directory will take precendence. |
78 The most common HWPs will be stored in the `Data/` directory of Hedgewars. Note that there are two `Data/` directories for Hedgewars, one is system-wide and one is intended for the current user. In case of conflicts between both, the user directory will take precendence. |
53 |
79 |
54 Storing HWPs in the user `Data/` directory is the most common form of installing a HWP to Hedgewars. This is what happens when you use DLCs. HWPs distributed in webforums are usually intended to be installed into the user `Data/` directory. |
80 Storing HWPs in the user `Data/` directory is the most common form of installing a HWP to Hedgewars. This is what happens when you use DLCs. HWPs distributed in webforums are usually intended to be installed into the user `Data/` directory. |
55 |
81 |
56 |
82 |
57 === Sidecar HWPs === |
83 ==== Sidecar HWPs ==== |
58 Sidecar HWPs are HWPs installed in the same directory as a Lua script. Sidecar HWPs always serve as a companion for one single Lua script. Sidecar HWPs will be activated only if the script in question is run by Hedgewars. Otherwise, the HWP remains inactive and its resources are unavailable. |
84 Sidecar HWPs are HWPs installed in the same directory as a Lua script. Sidecar HWPs always serve as a companion for one single Lua script. Sidecar HWPs will be activated only if the script in question is run by Hedgewars. Otherwise, the HWP remains inactive and its resources are unavailable. |
59 |
85 |
60 The name of a sidecar HWP equals the name of the Lua script it serves as a “sidecar”, with the file name suffix replaced by “.hwp”. Sidecar HWPs must be in the same directory as the script. |
86 The name of a sidecar HWP equals the name of the Lua script it serves as a “sidecar”, with the file name suffix replaced by “.hwp”. Sidecar HWPs must be in the same directory as the script. |
61 |
87 |
62 Example: The sidecar HWP of the Lua script in `/Data/Missions/Training/MyAwesomeMission.lua` would be `Data/Missions/Training/MyAwesomeMission.hwp`. |
88 Example: The sidecar HWP of the Lua script in `/Data/Missions/Training/MyAwesomeMission.lua` would be `Data/Missions/Training/MyAwesomeMission.hwp`. |
63 |
89 |
64 Using sidecar HWPs is useful for Lua scripters who want to provide a few resources for your script but don’t want to force users to install them globally or to fiddle around with their user data directory. Especially if using the resources only really makes sense together with the script. |
90 Using sidecar HWPs is useful for Lua scripters who want to provide a few resources for your script but don’t want to force users to install them globally or to fiddle around with their user data directory. Especially if using the resources only really makes sense together with the script. |
65 |
91 |
66 Please remember how Hedgewars uses ammo icons in HWPs (see above). |
92 Please remember how Hedgewars uses ammo icons in HWPs (see above). |
67 |
93 |
68 === Limitations === |
94 ==== Limitations ==== |
69 Important HWPs are not recursive! This means if you put a HWP inside another HWP, Hedgewars will only load the actual contents of the outermost HWP. The contents of the inner HWP are not loaded. This implies that there is currently no way (via HWP) to distribute a script with custom data. You have to ask users to just extract a normal Zip file with your script data instead. |
95 Important: HWPs are not recursive! This means if you put a HWP inside another HWP, Hedgewars will only load the actual contents of the outermost HWP. The contents of the inner HWP are not loaded. This implies that there is currently no way (via HWP) to distribute a script with custom data. You have to ask users to just extract a normal Zip file with your script data instead. |
70 |
96 |
71 This is considered a bug, see https://issues.hedgewars.org/show_bug.cgi?id=174. |
97 This is considered a bug, see https://issues.hedgewars.org/show_bug.cgi?id=174. |
72 |
98 |
73 === Order of precedence === |
99 ==== Order of precedence ==== |
74 |
100 |
75 # Sidecar HWPs |
101 # Sidecar HWPs |
76 # All HWPs |
102 # All HWPs |
77 # Alphabetically |
103 # Alphabetically |
78 # User `Data/` directory |
104 # User `Data/` directory |
79 # System `Data/` directory (usually when no HWP file is found) |
105 # System `Data/` directory (usually when no HWP file is found) |
|
106 |
80 |
107 |
81 |
108 |
82 == Best practices == |
109 == Best practices == |
83 This section has a couple of conventions which are considered to be best practices when creating HWP files. They are not mandatory, just recommendations. |
110 This section has a couple of conventions which are considered to be best practices when creating HWP files. They are not mandatory, just recommendations. |
84 |
111 |