Version 22 + update readmes
[Hedgewars_Game_Hacks.git] /
1 # Game Hacks
3 ## Introduction
4 Game Hacks is a Hedgewars game style which allows you to manipulate over 100 different aspects of Hedgewars using the script parameter in the game scheme. Create the craziest games you can ever imagine.
6 Game Hacks is supported for Hedgewars version 1.0.0 and later.
8 This document explains how Game Hacks works.
10 ## Description
11 Game Hacks adds additional game modifiers and settings in the following categories:
13 - Environment
14 - Information
15 - Hedgehogs
16 - Turn-based play
17 - Sudden Death events
18 - Weapon parameters (per-weapon damage, timer, etc.) 
19 - Utility parameters
20 - Eye-candy/gimmicks
22 The most important enabled modifiers will be displayed and explained briefly in the mission panel (shown at the start of the game or when you hit the mission panel key (default: [M]). As a rule of thumb, modifiers which are not obvious and have a big impact on gameplay are mentioned. Modifiers which are either obvious or only have little or no impact are usually not mentioned. Also, most modified weapons and utility effects are usually not mentioned, but their weapon description might be modified.
24 One important rule: If there is a conflict between one of Hedgewars' built-in settings and a script setting, the script setting takes precedence.
26 With an empty script parameter, there's only an cosmetic change: Generic ammo symbols for Extra Time and Extra Damage.
28 ## Basic syntax
29 This script can be configured mostly with the script parameters.
31 The script parameters are specified in a `key=value` format, and each pair is delimeted by a comma. Each value has one of multiple parameter types, which are described below. Each key can be specified in long form or in short form. The long form is descriptive. The short form is only 1 or 2 characters long.
33 Note that the entire script parameter field should not become longer than 245 characters, longer input can lead to problems in network games. This is a problem of Hedgewars. If you are using a lot of keys, you can use the short form. However, even with the short form it is possible to exhaust the character limit if you use a lot of parameters, so keep this in mind.
35 Try to use the long form when possible because it's easier to remember.
37 All values are optional.
39 See also the “Examples” section below.
41 ### Parameter types (see list of keys)
42 * num
43         * A whole number.
44         * Examples: `534`, `54`, `-13`
45 * hex
46         * A whole non-negative number in hexadecimal notation. Valid digits are 0-9 and A-F or a-f.
47         * Examples: `E`, `FF`, `84AE`, `a0a0a0`
48 * time
49         * Time. Times are interpreted as milliseconds by default, but you can append “`ms`” or “`s`” for milliseconds or seconds, respectively. Seconds can be specified as decimal numbers with “`.`” as the decimal separator and with up to 3 decimal places, but milliseconds must always be whole numbers.
50         * Examples (all mean 2.5 seconds): `2500`, `2500ms`, `2.5s`
51 * %
52         * A percentage or a plain number. If you append a percent sign to the number, it is interpreted as percentage from the default number. Only use whole numbers for percentages. Note that specifying the plain number may be much more precise, but for most of the time, specifying the percentage might be precise enough for you.
53         * Examples: `2000`, `100%`, `125%`
54 * truth
55         * Used for on/off states. Can be either “`true`” (feature is enabled) or “`false`” (feature is disabled). You can also use “`t`” or “`f`” as abbreviations.
56 * choice
57         * You can choose one of multiple values which is written in the description.
59 In the table below, some types will have an asterisk (“\*”). This means that the special value “`inf`” (or short “`i`”) is allowed here, meaning an infinite amount or time.
61 Some types will have a dash (“-”). This means that you can also specify a range of values by writing two values of this type separated by a dash (e.g. “`4-52`”). The first value must be smaller or equal than the second value, otherwise they will be ignored.
63 Some parameters permit special values, see the description.
65 Most parameters out of reasonable bounds (i.e. a barrel health of 0 or negative gravity) will be capped for technical reasons to avoid a buggy or unexpected behaviour. This is a safety feature but it can be disabled if you set `forcelimits` to `false`. **Warning**: If you use `forcelimits`, you're on your own; expect broken behaviour.
67 Two special values are available for the types “num”, “time” and “%”:
69 * `min` for the smallest possible (or technically feasible) value and
70 * `max` for the biggest one (including `inf`).
72 The boundaries are the same as for `forcelimits`.
74 ## List of keys
76 These are all the keys that Game Hacks supports:
78     Key                     Short   Type    Default Description
79     -----------------------+-------+-------+-------+-------------------------------------------------------------------------
80     <<< ENVIRONMENT >>>
81     barrelhealth            b       num-    60      Initial health of barrels.
82     healthcratehealth       eh      num-    N/A     Health in health crates will be randomly set within this range
83     sturdycrates            ec      truth   false   Crates can't be destroyed.
84     maxcratedrops           eC      num     5       Max. crates that can be in game before random crate dropping stops
85     maxwind                 w       %       100     Limit the maximum wind strength (0-100).
86     fairwind                W       truth   false   Wind stays the same within the same round.
87     gravity                 g       %       100     Base gravity (without utilities) in percent.
88     flamemode               ef      choice  normal  “off”: Disable flames and flame-based weapons.
89                                                     “sticky”: All flames keep burning through turns.
90                                                     “short”: No flames keep burning through turns.
91                                                     “normal”: No change.
92     airflameshurt           a       truth   false   Flames in mid-air can hurt hedgehogs.
93     nosnow                  Q       truth   false   Snow does not pile up in themes where it normally snows (i.e. Snow, Christmas)
94     girders                 G       num     0       Number of randomly placed girders, not all might be placed if too many. EXPERIMENTAL!
95     forcefield              ei      truth   false   Hedgehogs can not enter the opposite side of the terrain. EXPERIMENTAL!
97     <<< INFORMATION >>>
98     showminetimer           im      truth   false   Make it possible to see timer of mines and air mines with object info key if mines time is random.
100     <<< HEDGEHOGS >>>
101     nojump                  j       truth   false   Hogs can't jump.
102     noknock                 k       truth   false   “Hogs of Steel”: Hogs can't be knocked away by sliding hogs.
103     hogfriction             0       num     0       Difference from default hog friction. Sane values are from -10 to 10.
104     poisondamage            P       num     5       Damage for poisoned hogs per round.
105     poisonkills             n       truth   false   Poison reduces health down to 0 instead of 1.
106     poison                  p       truth   false   All hedgehogs start poisoned.
107     hogfreeze               hf      %       199999  Initial “freeze level” when freezing hogs with freezer. See parameter notes for details.
108     epidemic                he      truth   false   Poisoned hedgehogs infect other hedgehogs they touch.
109     teamcure                t       truth   false   Collecting a health crate will remove poison from all hogs in team.
110     sharehealth             h       truth   false   Health of crates is shared among team mates.
111     davidandgoliath         d       truth   false   The 1st hog in team removes half the health of its team mates and adds it to its own.
112     donorbox                q       truth   false   The last dying hog (or the king in King Mode) of a team leaves a box with all the hog weapons inside.
113     maxpower                hm      truth   false   Thrown/launched weapons will be thrown/launched at full power (like mortar).
115     <<< TURNS >>>
116     ready                   r       time    5s      Ready time before the turn starts.
117     strategictools          z       truth   false   Constructions, rubbers, land sprays, mud balls and resurrections end the turn.
119     <<< SUDDEN DEATH >>>
120     sdpoison                S       truth   false   Poison all hogs in Sudden Death (once).
121     sd1hp                   1       truth   false   Set the health of all hogs to 1 HP in Sudden Death (once).
123     <<< FUEL / DURATION >>>
124     saucerfuel              f       %*      2000    Fuel of a flying saucer.
125     birdyenergy             B       %*      2000    Flapping energy of Birdy.
126     landsprayfuel           L       %       1000    Fuel of land spray.
127     freezerfuel             u       %       1000    Fuel of freezer.
128     flamethrowerfuel        F       %       500     Fuel of flamethrower.
129     rcplanetimer            C       time*   15s     Time of RC plane before fuel is gone.
130     minetimer               8       time-   3s      Timer of ALL ordinary mines, with milliseconds precision. Use range for a random timer within the range.
131     stickyminetimer         s       time-   500ms   Timer of sticky mines. Use range for a random timer within the range.
132     airminetimer            Y       time-   750ms   Custom timer of air mines. Use range for a random timer within the range.
133     hellishtimer            6       time    5s      Timer of hellish hand-grenade. Use “manual” or “m” for allowing to set timer by user.
134     dynamitetimer           5       time    5s      Timer of dynamite. Use “manual” or “m” for allowing to set timer by user.
135     caketimer               c       %       2048    Walking time of cake (percentage).
136     beedelay                x       time    500ms   Delay of homing bee before it starts homing.
137     beetimer                y       time    5s      Max. flight time of homing bee after it started homing
138     drillrockettimer        3       time    5s      Detonation timer of drill rocket (not from plane). Use “manual” or “m” for allowing to set timer by user.
139     napalmbombtimer         tN      time    1s      Detonation timer of a napalm bomb.
140     kamikazerange           K       %       2048    Range of kamikaze.
141     balltimer               m       time    5s      Explosion timer of ball from ball gun. Use “manual” or “m” for allowing to manually set timer with the ball gun.
142     pickhammertimer         I       time*   4s      Active time of pick hammer.
143     blowtorchtimer          T       time*   7.5s    Active time of blowtorch.
144     poisoncloudtimer        tp      time    5s      Life timer of a poison cloud from old limburger. 5 seconds max.
145     portaldistance          tP      num*    inf     How far portal balls can fly. “inf” = no limit.
147     <<< WEAPON EFFECTS >>>
148     birdyeggs               E       num*    2       Number of eggs for Birdy
149     rcplanebombs            R       num*    3       Number of bombs of RC plane.
150     ballgunballs            U       num     51      Number of balls from ballgun.
151     pianobounces            O       num     5       Number of terrain bounces of piano before it falls into water.
152     airattackbombs          A       num     6       Bombs in an air attack.
153     minestrikemines         M       num     6       Mines in a mine strike.
154     drillstrikedrills       D       num     6       Drills in a drill strike.
155     napalmbombs             N       num     6       Bombs in a napalm attack.
156     planedrops              4       num     6       Shorthand: Set all above 4 parameters at once.
157     airattackgap            wA      %       30      Distance between 2 missile drops in air attack.
158     minestrikegap           wM      %       30      Distance between 2 mine drops in mine strike.
159     drillstrikegap          wD      %       30      Distance between 2 drill drops in drill strike.
160     napalmgap               wN      %       30      Distance between 2 napalm bomb drops in napalm attack.
161     planedropgap            2       %       30      Shorthand: Set all above 4 parameters at once.
162     dudminehealth           wu      %       36      How much “health” dud mines have before they explode.
163     airmineseekrange        wr      %*      175     Distance (in pixels) at which air mines start seeking.
164     airmineseekspeed        we      %       536871  Speed at which air mines seek hogs.
165     airminefriction         wf      %       1610613 Air friction of air mine.
166     hammerstrength          wh      %*      125     How deep a (successful) hammer hit digs into land.
167     kamikazetrigger         wk      truth   false   If true, kamikaze can be detonated early with the attack key.
168     deaglestrength          wd      %       50      How deep a desert eagle shot digs into land.
169     sniperstrength          ws      %       50      How deep a sniper rifle shot digs into land.
170     sinestrength            wS      num     1       Thickness of sine gun shot.
171     mudballstrength         wm      %       200000  Pushing strength of a mud ball.
172     seductionrange          7       %       250     Range of seduction in pixels. EXPERIMENTAL!
176     airminedamage           da      %       30      Explosion damage and range of air mine.
177     minedamage              d8      %       50      Mine damage.
178     stickyminedamage        dt      %       30      Sticky mine damage.
179     grenadedamage           dg      %       50      Grenade damage.
180     hellishdamage           dH      %       90      Hellish hand-grenade damage.
181     clusterbombdamage       dl      %       20      Cluster bomb damage (main bomb).
182     clusterdamage           dL      %       25      Damage of a cluster (from cluster bomb or mortar).
183     melondamage             dm      %       75      Melon bomb damage (main piece).
184     melonpiecedamage        dM      %       75      Melon bomb piece damage.
185     balldamage              dU      %       40      Damage of a ball from the ball gun.
186     bazookadamage           db      %       50      Bazooka shell damage.
187     mortardamage            do      %       20      Mortar damage (main projectile).
188     beedamage               dx      %       50      Bee damage.
189     dynamitedamage          d5      %       75      Dynamite damage.
190     cakedamage              dc      %       75      Cake damage.
191     batdamage               dB      %       30      Baseball bat damage.
192     shoryukendamage         dF      %       30      Shoryuken damage.
193     whipdamage              dw      %       30      Whip damage.
194     rcplanedamage           dr      %       25      RC plane damage.
195     cleaverdamage           dv      %       40000   Scaling value of the impact damage of a cleaver. The damage does not linearly increase.
196     eggdamage               dE      %       10      Damage of an egg (from Birdy).
197     pianodamage             dp      %       80      Damage of a single Piano explosion (note: each impact creates 3 explosions).
198     limburgerdamage         di      %       20      Old limburger damage.
199     deagledamage            dd      %       7       Damage of a single Desert Eagle shot.
200     minigundamage           dG      %       2       Damage of a single minigun bullet.
201     shotgundamage           dO      %       25      Damage of a single shotgun shot.
202     sniperdamage            ds      %       100000  Scaling value of the sniper rifle's damage.
203     sinedamage              dS      %       35      Damage of a sine wave from the sine gun.
204     kamikazedamage          dK      %       30      Damage of a kamikaze impact and its explosion.
205     airbombdamage           dA      %       30      Damage of a bomb from an air strike or en RC plane.
206     drillrocketdamage       d3      %       50      Damage of a launched drill rocket.
207     drillstrikedrilldamage  dD      %       30      Damage of a drill rocket from the drill strike.
208     blowtorchdamage         dT      %       2       Damage of a single hit with a blowtorch.
209     pickhammerdamage        dI      %       6       Damage of a single hit with a pickhammer.
210     flamedamage             df      %       2       Damage of a small flame (larger flames deal 3 or 4 times this damage)
211     hogdamage               dh      %       30      Damage of the explosion of a dying hedgehog.
212     cratedamage             dC      %       25      Damage of an exploding crate.
213     barreldamage            de      %       75      Damage of an exploding barrel.
214     hammerdamage            dj      num     3       Denominator of the hammer damage. Actual damage will be 1/<number>*<health>.
215     hammerextradamage       dJ      num     2       Denominator of the hammer damage while extra damage is on. Actual damage will be 1/<number>*<health>.
217     <<< UTILITY EFFECTS >>>
218     buildrange              J       %*      256     Max. building range of girder.
219     extratime               e       time    30s     Time you get with Extra Time utility.
220     lowgravity              l       %       50      Percentage of base gravity used when low gravity utility is used.
221     timeboxturns            ut      num*    N/A     Time Box will return after this many additional turns. See parameter notes for details.
222     pickhammerstraightdown  up      truth   false   If true, the pick hammer will be able to dig straight down only and it direction can not be changed.
223     buildlimit              ub      num*    inf     How many constructions, rubbers and land sprays can be used per turn (inf = no limit).
224     resurrectorrange        9       %       100     Range of resurrector in pixels. EXPERIMENTAL!
226     <<< EYE CANDY / GIMMICKS >>>
227     shoppaborder            o       truth   false   Landscape has a decorative “danger” stripe on its edges.
228     ropecolor               xr      hex     D8D8D8  Rope color (will slightly change rope style). Use value “clan” to make rope appear in clan color.
229     ropeopacity             xR      %       255     Opacity of ropes (will slighty change rope style). 255=full opacity.
232     forcelimits             Z       truth   true    Cap most number-based values at reasonable bounds. WARNING: If false, correct operation is NOT guaranteed
233     hedgepot                H       truth   false   Change 1-5 random game settings and 0-1 weapons/utilities.
235 ### Parameter notes
237 Here are some detailed notes about specific parameters.
239 - `strategictools`
240         - Disables infinite attack mode.
241 - `seductionrange`, `resurrectorrange`
242         - Two circles will be drawn.
243         - The brighter shows the actual range, the other circle is the original range
244 - `showdudminehealth`
245         - Dud mine health is shown above the object
246 - `showminetimer`
247         - Timer of mines are shown at the bottom right
248         - Remember that the timer is rounded up! This means that a “1” can mean anything between 1 millisecond and 1 second
249         - The color has a meaning:
250                 - white/yellow: Mine is inactive
251                         - white: Mine time is higher than 0.5s
252                         - yellow: Mine timer is 0.5s or lower
253                 - red: mine is active, the red tone tells you more about the timer time
254                         - brighter red: the upper half of the second (e.g. 0.5-1.0s)
255                         - darker red: the lower half of the second (e.g. 0.0-0.5s)
256 - `girders`
257         - Constructions will be placed with a small buffer zone around them to avoid girders going to close to things and each other
258         - Hedgehogs and objects will NOT spawn on the girders; girders are inserted after everything else has been generated and placed
259         - If the girders would become too crammed in the landscapes, Game Hacks decides to stop adding more girders
260         - With `forcelimits=false`, the above limit does not apply, but the loading time might increase considerably for a huge number of girders (>100000)
261         - Known quirks:
262                 - Possibly poor girder placement for custom and “unorthodox” girder shapes from a theme
263                 - Considered experimental, the behaviour of this parameter may change in future
264 - `planedrops`, `planedropgap`
265         - If you additionally explicitly specify parameters for the explicit plane drops, (`airattackbombs`, `airattackgap`, etc.) those explicit values take precedence
266 - `gravity`, `lowgravity`
267         - Low gravity utility will modify gravity based on the base gravity
268         - Disables built-in low gravity game modifier
269         - For using high gravities, the turns may take longer to finish. This is mostly a problem in Hedgewars
270 - `forcefield`
271         - The center of the map will have a barrier which prevents hedgehogs from going through
272                 - Exceptions: Kamikaze and Piano Strike (since those are attacks)
273                 - Weapons can go through
274                 - Ropes and portals can not go through
275         - This feature is a bit buggy
276         - The following things will be disabled:
277                 - Wrap world edge
278                 - Time Box
279 - `hogfriction`
280         - Frictions determines how “well” the hogs slide, low friction means more sliding power
281         - Note that this scale is not linear
282         - Use these values as guide:
283                 - `9989`: max. friction (hedgehogs don't slide at all)
284                 - `20`: very high friction
285                 - `10`: high friction
286                 - `0`: default friction
287                 - `-5`: low friction
288                 - `-8`: very low friction
289                 - `-10`: extremely low friction
290         - Use values in-between for fine-tuning
291 - `fairwind`, `maxwind`
292         - Overwrites the built-in “disable wind” game modifier
293 - `minetimer`:
294         - Will overwrite the default mine timer in the game scheme editor
295         - Air mine timers will default to 750ms if not specified with airminetimer
296         - The built-in mine timer setting will also affect the air mine timer
297         - Use this setting when you need precision of 1 millisecond
298         - Use the built-in setting when you need precision of 1 second only
299         - Only use this key when you really need it
300 - `poisoncloudtimer`
301         - Set `forcelimits` to `false` if you need to use timers longer than 5s.
302         - However: Times above 5s are glitchy, the color and transparency of the poison cloud become awkward.
303         - Use a time of 0 for a poison-free explosion of the old limburger.
304 - `barrelhealth`
305         - Barrels will start frozen if health is above 60
306 - `hogfreeze`
307         - The default value makes a hog skip 3 rounds (if it is not burned)
308         - Each round reduces freeze level by 50000
309         - Each time a flame is touched, freeze level is reduced by 1000
310         - Example values:
311                 - melt immediately:   0
312                 - melt next turn: 50000
313                 - skip 1 round:  100000
314                 - skip 2 rounds: 150000
315                 - skip 3 rounds: 200000
316                 - and so on ...
317 - `sd1hp`, `sdpoison`
318         - Be aware that the normal Sudden Death health decrease can still apply on top of these effects. It is recommended (but not mandatory) to set it to 0
319         - If both Sudden Death health decrease and water rise are set to 0, the Sudden Death effect will be faked by the script but the background won't change
320 - `sharehealth`:
321         - Health is shared as equally as possible. If the division leaves a remainder, the remainder will be split among some of the hedgehogs, beginning with the current hog and continuing with the next ones
322 - `healthcratehealth`
323         - If this is set, the health crate amount set in the game scheme will be ignored
324 - `davidandgoliath`:
325         - If the division leaves a remainder, the result is rounded down
326         - Does not work well together with Reset Health mode: (health is reset to initial health in game scheme, rather than actual initial health)
327 - `donorbox`:
328         - The donor box will replace the grave
329 - `timeboxturns`:
330         - With value 0, the Time Box returns as fast as possible which will be in the next turn, turning the Time Box basically into a random teleportation
331         - Value 1 refers to the turn after the next turn, and so on.
332         - With the value “inf”, the Time Box will return only (!) in Sudden Death or when this is the final hog in the team, not earlier
333         - Regardless of settings, the Time Box follows the standard Time Box behaviour of always returning in Sudden Death or when it is the final hog in the team
335 ## Examples
337 In this section there are some examples for valid texts to put into the script parameter.
339     saucerfuel=4000
341 --> The flying saucer has 200% fuel.
343     saucerfuel=200%
345 --> The flying saucer has 200% fuel.
347     saucerfuel=inf
349 --> The flying saucer has infinite fuel.
351     stickyminetimer=0, nojump=true
353 --> Sticky mines explode instantly and jumping is disabled.
355     minetimer=1s-2s
357 --> Mines have a random time which may be between 1 and 2 seconds long.
359     ready=10s
361 --> The ready timer is set to 10 seconds.
363     poison=true, poisondamage=10
365 --> All hedgehogs are poisoned from the beginning and take 10 poison damage per turn.
367     gravity=200
369 --> The base gravity is doubled. It will go down to 100% when low gravity utility is used in-game (50% of base gravity).
371     gravity=200%, lowgravity=25%
373 --> The base gravity is doubled. It will go down to 25% of that base gravity (!) when the low gravity utility is used, which is 50% of the default gravity.
375     g=200%,l=25%
377 --> Same as the previous example, but it uses the short form.
379     ropecolor=FF0000
381 --> All ropes are red.
384 ## Licensing
386 Game Hacks is free software.
388 It's licensed under the MIT License. The media files (images) are based on Hedgewars content and are licensed under the GNU Free Documentation License 1.2.
390 See the `Game_Hacks_LICENSE_v21.txt` file for the full license texts.