HWPFormat.wiki
author Wuzzy
Mon, 20 May 2019 20:47:43 +0100
changeset 1899 79a144a97a48
parent 1442 b3d6459f7343
child 2109 e433562fb881
permissions -rw-r--r--
LuaGlobals: Tweak syntax
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1435
1a8cc20ce16c HWPFormat: Add TOC
Wuzzy
parents: 1434
diff changeset
     1
#summary Description of HWP files used to package custumizations of Hedgewars
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
     2
1435
1a8cc20ce16c HWPFormat: Add TOC
Wuzzy
parents: 1434
diff changeset
     3
= HWP files =
1a8cc20ce16c HWPFormat: Add TOC
Wuzzy
parents: 1434
diff changeset
     4
<wiki:toc max_depth="2" />
1a8cc20ce16c HWPFormat: Add TOC
Wuzzy
parents: 1434
diff changeset
     5
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
     6
== Introduction ==
1442
b3d6459f7343 HWPFormat: better intro
Wuzzy
parents: 1441
diff changeset
     7
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”.
479
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
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
    10
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    11
== Who uses HWP? ==
1440
8899e3c8125f HWPFormat: shorten intro
Wuzzy
parents: 1439
diff changeset
    12
HWP files are used here:
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    13
1441
6534038aaf07 HWPFormat: fix bullets
Wuzzy
parents: 1440
diff changeset
    14
 * Downloadable Content (DLC) section
6534038aaf07 HWPFormat: fix bullets
Wuzzy
parents: 1440
diff changeset
    15
 * [http://hh.unit22.org/ hh.unit22.org], community-driven add-on server
6534038aaf07 HWPFormat: fix bullets
Wuzzy
parents: 1440
diff changeset
    16
 * In the [https://hedgewars.org/forum webforums] by users
6534038aaf07 HWPFormat: fix bullets
Wuzzy
parents: 1440
diff changeset
    17
 * Hedgewars also uses these internally for scripts and missions (see the section about sidecar HWPs)
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    18
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    19
== Using HWP ==
1429
801df24921d6 HWPFormat: Add a short description for ease-of-use
Wuzzy
parents: 1140
diff changeset
    20
If you download any add-on from DLC, you must restart Hedgewars for the change to take effect.
801df24921d6 HWPFormat: Add a short description for ease-of-use
Wuzzy
parents: 1140
diff changeset
    21
1439
b01fa5ac341e HWPFormat: Explain the meaning of HWP
Wuzzy
parents: 1438
diff changeset
    22
To install a HWP file manually, just put it in the `Data/` sub-directory of your [https://www.hedgewars.org/node/6761 user directory].
1429
801df24921d6 HWPFormat: Add a short description for ease-of-use
Wuzzy
parents: 1140
diff changeset
    23
1433
19945dc3944e HWPFormat: simplify headers
Wuzzy
parents: 1432
diff changeset
    24
== Creating simple HWPs ==
1435
1a8cc20ce16c HWPFormat: Add TOC
Wuzzy
parents: 1434
diff changeset
    25
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.
1429
801df24921d6 HWPFormat: Add a short description for ease-of-use
Wuzzy
parents: 1140
diff changeset
    26
1433
19945dc3944e HWPFormat: simplify headers
Wuzzy
parents: 1432
diff changeset
    27
=== Example ===
1438
e7214d0ff6e8 HWPFormat: HWP vs ZIP
Wuzzy
parents: 1437
diff changeset
    28
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:
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    29
1432
549afbe978a8 HWPFormat: fix code section?
Wuzzy
parents: 1431
diff changeset
    30
{{{
1431
ea2c33d74c85 HWPFormat: fix indent?
Wuzzy
parents: 1430
diff changeset
    31
    Themes
ea2c33d74c85 HWPFormat: fix indent?
Wuzzy
parents: 1430
diff changeset
    32
        MyTheme_v1
ea2c33d74c85 HWPFormat: fix indent?
Wuzzy
parents: 1430
diff changeset
    33
            theme.cfg
ea2c33d74c85 HWPFormat: fix indent?
Wuzzy
parents: 1430
diff changeset
    34
            BlueWater.png
ea2c33d74c85 HWPFormat: fix indent?
Wuzzy
parents: 1430
diff changeset
    35
            SDWater.png
ea2c33d74c85 HWPFormat: fix indent?
Wuzzy
parents: 1430
diff changeset
    36
            horizont.png
ea2c33d74c85 HWPFormat: fix indent?
Wuzzy
parents: 1430
diff changeset
    37
            Sky.png
ea2c33d74c85 HWPFormat: fix indent?
Wuzzy
parents: 1430
diff changeset
    38
            (many other theme files)
1432
549afbe978a8 HWPFormat: fix code section?
Wuzzy
parents: 1431
diff changeset
    39
}}}
1429
801df24921d6 HWPFormat: Add a short description for ease-of-use
Wuzzy
parents: 1140
diff changeset
    40
801df24921d6 HWPFormat: Add a short description for ease-of-use
Wuzzy
parents: 1140
diff changeset
    41
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.
801df24921d6 HWPFormat: Add a short description for ease-of-use
Wuzzy
parents: 1140
diff changeset
    42
801df24921d6 HWPFormat: Add a short description for ease-of-use
Wuzzy
parents: 1140
diff changeset
    43
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.
801df24921d6 HWPFormat: Add a short description for ease-of-use
Wuzzy
parents: 1140
diff changeset
    44
1433
19945dc3944e HWPFormat: simplify headers
Wuzzy
parents: 1432
diff changeset
    45
== Full description of HWPs ==
1434
83da47a13028 HWPFormat: Edited via web interface
Wuzzy
parents: 1433
diff changeset
    46
The section above explained all the basics you need to know about HWPs to get started.
1429
801df24921d6 HWPFormat: Add a short description for ease-of-use
Wuzzy
parents: 1140
diff changeset
    47
1434
83da47a13028 HWPFormat: Edited via web interface
Wuzzy
parents: 1433
diff changeset
    48
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.
1433
19945dc3944e HWPFormat: simplify headers
Wuzzy
parents: 1432
diff changeset
    49
19945dc3944e HWPFormat: simplify headers
Wuzzy
parents: 1432
diff changeset
    50
=== Format specification ===
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    51
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
    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
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
    54
1433
19945dc3944e HWPFormat: simplify headers
Wuzzy
parents: 1432
diff changeset
    55
=== How Hedgewars uses HWPs ===
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    56
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
    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
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
    59
1139
8e932b5dcedd HWPFormat: Explain custom sprites and sounds
Wuzzy
parents: 995
diff changeset
    60
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.
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    61
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    62
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
    63
1433
19945dc3944e HWPFormat: simplify headers
Wuzzy
parents: 1432
diff changeset
    64
==== Custom sprites and sounds ====
1140
38d6a4e430b5 HWPFormat: dummy sprites
Wuzzy
parents: 1139
diff changeset
    65
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.
1139
8e932b5dcedd HWPFormat: Explain custom sprites and sounds
Wuzzy
parents: 995
diff changeset
    66
8e932b5dcedd HWPFormat: Explain custom sprites and sounds
Wuzzy
parents: 995
diff changeset
    67
The custom sprites are named `Graphics/custom1.png` to `Graphics/custom8.png` and are accessed in Lua with `sprCustom1` to `sprCustom8`.
8e932b5dcedd HWPFormat: Explain custom sprites and sounds
Wuzzy
parents: 995
diff changeset
    68
8e932b5dcedd HWPFormat: Explain custom sprites and sounds
Wuzzy
parents: 995
diff changeset
    69
The custom sounds are named `Sounds/custom1.ogg` to `Sounds/custom8.ogg` and are accessed in Lua with `sndCustom1` to `sndCustom8`.
8e932b5dcedd HWPFormat: Explain custom sprites and sounds
Wuzzy
parents: 995
diff changeset
    70
1433
19945dc3944e HWPFormat: simplify headers
Wuzzy
parents: 1432
diff changeset
    71
==== Custom ammo icons ====
1139
8e932b5dcedd HWPFormat: Explain custom sprites and sounds
Wuzzy
parents: 995
diff changeset
    72
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).
994
587e1b18132d HWPFormat: Explain Ammos image overwrite
Wuzzy
parents: 960
diff changeset
    73
587e1b18132d HWPFormat: Explain Ammos image overwrite
Wuzzy
parents: 960
diff changeset
    74
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.
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    75
1433
19945dc3944e HWPFormat: simplify headers
Wuzzy
parents: 1432
diff changeset
    76
== Possible locations for HWPs ==
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    77
1433
19945dc3944e HWPFormat: simplify headers
Wuzzy
parents: 1432
diff changeset
    78
=== HWPs in `Data/` ===
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    79
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
    80
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    81
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
    82
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    83
1433
19945dc3944e HWPFormat: simplify headers
Wuzzy
parents: 1432
diff changeset
    84
=== Sidecar HWPs ===
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    85
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
    86
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    87
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
    88
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
    89
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
    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
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
    92
995
84089099197f HWPFormat: Refer in sidecar section to ammo icons
Wuzzy
parents: 994
diff changeset
    93
Please remember how Hedgewars uses ammo icons in HWPs (see above).
84089099197f HWPFormat: Refer in sidecar section to ammo icons
Wuzzy
parents: 994
diff changeset
    94
1433
19945dc3944e HWPFormat: simplify headers
Wuzzy
parents: 1432
diff changeset
    95
=== Limitations ===
1429
801df24921d6 HWPFormat: Add a short description for ease-of-use
Wuzzy
parents: 1140
diff changeset
    96
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.
959
b167ea1e5563 HWPFormat: Add warning about non-recursivity
Wuzzy
parents: 798
diff changeset
    97
b167ea1e5563 HWPFormat: Add warning about non-recursivity
Wuzzy
parents: 798
diff changeset
    98
This is considered a bug, see https://issues.hedgewars.org/show_bug.cgi?id=174.
b167ea1e5563 HWPFormat: Add warning about non-recursivity
Wuzzy
parents: 798
diff changeset
    99
1433
19945dc3944e HWPFormat: simplify headers
Wuzzy
parents: 1432
diff changeset
   100
=== Order of precedence ===
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   101
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   102
  # 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
   103
  # 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
   104
  # Alphabetically
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   105
  # 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
   106
  # 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
   107
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   108
1429
801df24921d6 HWPFormat: Add a short description for ease-of-use
Wuzzy
parents: 1140
diff changeset
   109
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   110
== 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
   111
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
   112
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   113
=== Versioning ===
1436
6579d83e42c4 HWPFormat: Versioning update
Wuzzy
parents: 1435
diff changeset
   114
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:
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   115
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   116
<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
   117
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   118
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
   119
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   120
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
   121
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   122
 * `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
   123
 * `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
   124
 * `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
   125
 * 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
   126
1436
6579d83e42c4 HWPFormat: Versioning update
Wuzzy
parents: 1435
diff changeset
   127
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.
6579d83e42c4 HWPFormat: Versioning update
Wuzzy
parents: 1435
diff changeset
   128
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   129
== 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
   130
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
   131
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   132
=== Security risks ===
546
507162614281 Rewritten the security section. I hope it is slightly better now.
almikes@aol.com
parents: 545
diff changeset
   133
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.
507162614281 Rewritten the security section. I hope it is slightly better now.
almikes@aol.com
parents: 545
diff changeset
   134
507162614281 Rewritten the security section. I hope it is slightly better now.
almikes@aol.com
parents: 545
diff changeset
   135
Another potential risk are PNG files which contain a virus.
507162614281 Rewritten the security section. I hope it is slightly better now.
almikes@aol.com
parents: 545
diff changeset
   136
507162614281 Rewritten the security section. I hope it is slightly better now.
almikes@aol.com
parents: 545
diff changeset
   137
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.
479
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   138
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   139
=== Conflicts ===
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   140
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
   141
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   142
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   143
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
   144
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   145
 * Hats
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   146
 * Graves
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   147
 * 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
   148
 * 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
   149
  * clouds
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   150
  * chunks
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   151
  * music
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   152
  * waves
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   153
  * 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
   154
  * flakes
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   155
  * dust
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   156
  * mudball
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   157
  * splashes
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   158
  * landtex
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   159
  * landbacktex
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   160
  * sky
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   161
  * horizont
74942b51d806 Add description of the HWP format. Maybe not perfect or complete, but a very important start.
almikes@aol.com
parents:
diff changeset
   162
  * damage color
544
6e78f17e8328 Updated conflicts section (desync on overwritten sprites when placing them)
almikes@aol.com
parents: 492
diff changeset
   163
  * border
6e78f17e8328 Updated conflicts section (desync on overwritten sprites when placing them)
almikes@aol.com
parents: 492
diff changeset
   164
6e78f17e8328 Updated conflicts section (desync on overwritten sprites when placing them)
almikes@aol.com
parents: 492
diff changeset
   165
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.