HWP files
Introduction
A
HWP file is an add-on for Hedgewars which adds new things to Hedgewars, like a theme, map, scripts and more. HWP files have the suffix “.hwp”. HWP files are used in the “Downloadable Content” (DLC) section, but they also can be shared online and installed manually. “HWP” stands for “Hedgewars Package”.
The file format provides an alternative to the “classical” method in which the user puts custom files directly into the user data directory.
Who uses HWP?
HWP files are used here:
- Downloadable Content (DLC) section
- hh.unit22.org, community-driven add-on server
- In the webforums by users
- Hedgewars also uses these internally for scripts and missions (see the section about sidecar HWPs)
Using HWP
If you download any add-on from DLC, you must restart Hedgewars for the change to take effect.
To install a HWP file manually, just put it in the
Data/
sub-directory of your user directory.
Creating simple HWPs
Creating a HWP is easy. 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.
Example
Suppose you have made a theme with the name “MyTheme”, version 1 (
MyTheme_v1
). If you want to package it in a HWP, you just create a Zip file (e.g. “MyTheme_v1.zip”) with the following directory structure:
Themes
MyTheme_v1
theme.cfg
BlueWater.png
SDWater.png
horizont.png
Sky.png
(many other theme files)
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.
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.
Full description of HWPs
The section above explained all the basics you need to know about HWPs to get started.
HWPs have a couple of additional features which allow you to do more sophisticated things; you do not neet to understand these for packaging basic content like themes, maps, etc. This section explains the HWP files in greater detail.
Format specification
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.
The complete Zip file format specification can be found at http://www.pkware.com/documents/casestudies/APPNOTE.TXT.
How Hedgewars uses HWPs
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.
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.
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.
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.
Custom sprites and sounds
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.
The custom sprites are named
Graphics/custom1.png
to
Graphics/custom8.png
and are accessed in Lua with
sprCustom1
to
sprCustom8
.
The custom sounds are named
Sounds/custom1.ogg
to
Sounds/custom8.ogg
and are accessed in Lua with
sndCustom1
to
sndCustom8
.
Custom ammo icons
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).
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.
Possible locations for HWPs
HWPs in
Data/
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.
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.
Sidecar HWPs
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.
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.
Example: The sidecar HWP of the Lua script in
/Data/Missions/Training/MyAwesomeMission.lua
would be
Data/Missions/Training/MyAwesomeMission.hwp
.
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.
Please remember how Hedgewars uses ammo icons in HWPs (see above).
Nested HWPs
HWPs can be nested. That is, if you put a HWP inside another HWP, the contents of the inner HWP will be loaded as well.
But there's a catch: The nesting can only go one layer deep, and only sidecar HWPs will work. HWPs that are nested deeper as well as nested HWPs that are not sidecars will be ignored.
Order of precedence
- Sidecar HWPs
- All HWPs
- Alphabetically
- User
Data/
directory
- System
Data/
directory (usually when no HWP file is found)
Best practices
This section has a couple of conventions which are considered to be best practices when creating HWP files. They are not mandatory, just recommendations.
Versioning
For maps, themes, forts and any scripted content, we suggest to use a naming convention. The convention for those is to include a simple versioning into the file name. The syntax of this convention is this:
FileName_v<number>.hwp
Where
<number>
is replaced with an integer for the version number, starting by 1. For each subsequent version, this number would be increased.
Example of three versions of a HWP file in the order they got released:
-
MyAwesomePack_v1.hwp
-
MyAwesomePack_v2.hwp
-
MyAwesomePack_v3.hwp
- and so on …
Don't worry, the appended version number is generally understood to be not part of the real name. It's just an useful convention to help resolving possible conflicts in online play.
Possible problems, conflicts and security risks
Using HWP is not without problems.
Security risks
Since HWP files can also include Lua files, there is the danger that someone may trick you into installing a HWP containing a malicious Lua script. Theoretically Lua scripts should not be able to directly write into any files, especially outside of the Hedgewars
Data/
directory. But security has not been intensively tested and there is always the risk of security vulnerabilities in Hedgewars itself.
Another potential risk are PNG files which contain a virus.
The only thing we can say now is that you should not blindly trust random users giving you HWP files. We recommend you to only use HWPs from sources you trust. When in doubt, check the contents of a HWP file by yourself by using your favourite Zip program, or don't install the HWP at all.
Conflicts
Conflicts happen if there are multiple active HWPs which provide a file with an identical name. Hedgewars will resolve those conflicts silently by using the order or precedence (see above), but this behaviour may still have unexpected effects, since the other file from the other HWP file becomes “invisible”. It is a good idea to check your installed HWP files for any “garbage” from time to time and delete those you don’t need.
Here is an incomplete list of things which you can safely replace and still play over network without problems:
- Hats
- Graves
- Death animation
- For themes:
- clouds
- chunks
- music
- waves
- water colour
- flakes
- dust
- mudball
- splashes
- landtex
- landbacktex
- sky
- horizont
- damage color
- border
There is, however, an exception to this rule: Overwritten sprites which are placed by Lua scripts as land (i.e. with
PlaceSprite
) will cause a desynchronization in online games.