HWPFormat.wiki
author almikes@aol.com
Fri, 19 Dec 2014 23:42:18 +0000
changeset 522 2b6da59e5489
parent 492 25011ebab5ec
child 544 6e78f17e8328
permissions -rw-r--r--
Add SVG template.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
     1
#summary Description of the HWP format, used to package custumizations of Hedgewars
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
     2
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
     3
= HWP format =
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
     4
== Introduction ==
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
     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.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
     6
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
     7
The file format provides an alternative to the “classical” method in which the user puts custom files directly into the user data directory.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
     8
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
     9
== Who uses HWP? ==
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    10
Chances are good that you already have used HWP files without knowing it.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    11
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    12
HWP files used in the “Downloadable Content” section which can be accessed in the main-menu of Hedgewars or with your brower via [http://hedgewars.org/content.html]. Only HWP files are distributed there.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    13
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    14
The community-driven Hedgewars addon server [http://hh.unit22.org/ hh.unit22.org] only accepts HWP files.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    15
492
25011ebab5ec Fix forum link
almikes@aol.com
parents: 480
diff changeset
    16
HWP files are also commonly used to distribute custom files in the [http://hedgewars.org/forum webforums].
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    17
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    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).
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    19
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    20
== Using HWP ==
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    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.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    22
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    23
== Format specification ==
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    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.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    25
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    26
The complete Zip file format specification can be found at [http://www.pkware.com/documents/casestudies/APPNOTE.TXT].
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    27
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    28
== How Hedgewars uses HWPs ==
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    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.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    30
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    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.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    32
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    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.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    34
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    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.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    36
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    37
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    38
== Possible locations for HWPs ==
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    39
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    40
=== HWPs in `Data/` ===
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    41
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.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    42
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    43
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.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    44
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    45
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    46
=== Sidecar HWPs ===
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    47
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.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    48
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    49
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.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    50
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    51
Example: The sidecar HWP of the Lua script in `/Data/Missions/Training/MyAwesomeMission.lua` would be `Data/Missions/Training/MyAwesomeMission.hwp`.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    52
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    53
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.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    54
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    55
=== Order of precedence ===
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    56
_Note: This section is unfinished and may be inaccurate!_
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    57
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    58
  # Sidecar HWPs
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    59
  # All HWPs
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    60
  # Alphabetically
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    61
  # User `Data/` directory
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    62
  # System `Data/` directory (usually when no HWP file is found)
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    63
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    64
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    65
== Best practices ==
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    66
This section has a couple of conventions which are considered to be best practices when creating HWP files. They are not mandatory, just recommendations.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    67
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    68
=== Versioning ===
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    69
A naming convention is suggested to include a simple versioning into the file name. The syntax of this convention is this:
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    70
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    71
<code>FileName_v<number>.hwp</code>
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    72
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    73
Where `<number>` is replaced with an integer for the version number, starting by 1. For each subsequent version, this number would be increased.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    74
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    75
Example of three versions of a HWP file in the order they got released:
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    76
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    77
 * `MyAwesomePack_v1.hwp`
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    78
 * `MyAwesomePack_v2.hwp`
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    79
 * `MyAwesomePack_v3.hwp`
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    80
 * and so on …
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    81
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    82
== Possible problems, conflicts and security risks ==
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    83
Using HWP is not without problems.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    84
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    85
=== Security risks ===
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    86
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. Hedgewars does not really have many protections against this. The only thing we can say now is that you should not blindly trust random users giving you HWP files. When in doubt, check the contents of a HWP file by yourself by using your favourite Zip program. HWP files without any Lua scripts should be safe.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    87
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    88
=== Conflicts ===
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    89
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.
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    90
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    91
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    92
Here is an incomplete list of things which you can safely replace and still play over network without problems:
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    93
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    94
 * Hats
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    95
 * Graves
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    96
 * Death animation
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    97
 * For themes:
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    98
  * clouds
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    99
  * chunks
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   100
  * music
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   101
  * waves
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   102
  * water colour
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   103
  * flakes
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   104
  * dust
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   105
  * mudball
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   106
  * splashes
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   107
  * landtex
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   108
  * landbacktex
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   109
  * sky
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   110
  * horizont
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   111
  * damage color
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   112
  * border