Editing Map based hacks

This page is intended to be an explanation of the tricks written about on this page: http://www.celephais.net/board/view_thread.php?id=37116
and Preach's excellent blog posts on the subject:
http://tomeofpreach.wordpress.com/category/map-hacks/
----


'''Map-based hacks''' are non-standard techniques in [[Mapping | mapping]] that allow the customization of [[Entity | entities]] in a map without resorting to [[Modding | modding]]. They are made possible due to the fairly open nature of [[Quake-C]]. The so-called hacks involve the modification, replacment or addition of keys in existing entities to enhance their functionality as well as the creation of completely new ones. While they generally work reliably in [[Vanilla Quake]] ("ID1"), they can cause compatibility problems if the map is run with a [[Mod | mod]], ranging from incorrect appearance to engine crashes, which means they have to be used with caution.

==Theory behind the hacks==

All map entities have a set of core functions and default keys defined in their corresponding [[Quake-C]] file which determine their behavior. In most cases, these functions are fixed with the classname and cannot be changed. However, there are a few exceptions either due to a difference in terminology used in the map source and in the game code (for instance, the definition of sound effects), or because certain functions remain unused in some entities.

Most hacks revolve around creating new versions of existing entities by incorporating their desired functions into an [[info_notnull]] entity, which can be regarded as a blank canvas since it does not have any predefined functions or behavior. Therefore, it is possible to recreate every single map entity in the game as into_notnull.
When using this ''wildcard'' entity, it is often essential to set a corresponding field to define its spawn function, how it behaves when triggered or touched.

*'''think''' - This function determines the what the entity does automatically after the server starts, or to be more precise, after the amount of time set in its mandatory sub-function ''nextthink''. Depending on which kind of role the info_notnull is meant is fulfill, the think field must contain the spawn function, e.g. ''InitTrigger'', ''PlaceItem'', ''walkmonster_start_go''.
*'''use''' - This function determines how the entity reacts when being triggered by another entity, or in some cases when being activated or killed. It can serve as a spawn function for an initially dormant entity, e.g. ''InitTrigger'', ''classname'', or call a subroutine like e.g. ''SUB_UseTargets'', ''SUB_Remove'', ''SUB_regen''.
*'''touch''' - This function determines what happens if the entity is touched by another entity, most notably in triggers, e.g. ''multi_touch'', ''hurt_touch'',''SUB_Null''.

In addition to the spawn function, there are several other possibilities or requirements to further determine the behavior of the new entity and its appearance in the game, such as its [[Model | model]] and [[Sounds | sound effects]]. For many hacks to work, it is important that all of such resources are precached, which require the corresponding standard [[Entity_guide | entities]] to be present in the map alongside the new ones.

==Triggers==
===Point-based triggers with custom bounding box===
While most of the standard [[Entity_guide | triggers]] are by default defined as [[Entity#Overview | brush entities]], it is possible to for them to be used as [[Entity#Overview | point entities]] as well. The difference is that they only work at a single point instead of a larger volume that would otherwise be determined by the [[Brush | brush]]. They also do not count towards the [[Engine_Limits | model limit]]. Among other fields of use, this makes them a good alternative for monster teleporters (the ''silent'' spawnflag must be set), for example.
There are two downsides, however. If set to be shootable, point triggers can only be activated by splash damage. Furthermore, in a normal map environment, touchable point triggers are easy to miss for the player. The latter can be worked around as it is possible to assign any precached model to serve as the bounding box of the point trigger. This is achieved by adding a '''model''' field to the trigger which points the corresponding entity, such as an item, a monster, or a brush entity.

For instance, ''"model" "maps/b_bh100.bsp"'' will make the bounding box the size of a [[Megahealth]] (32*32*32 units), ''"model" "progs/shambler.mdl"'' will make it the size of a [[Shambler]] (64*64*96 units). Using any kind of .bsp and .mdl model is the easiest way, but it bears the risk of producing incompatibility to mods that lack the referenced objects or treat them differently, and will likely result in a crash. A safe, but also more complicated way is to reference existing brush models from within the map, e.g. ''"model" "*10"''. This makes placing the such a trigger very tricky, however, because its location has to be determined by the location of the original brush entity in its relation to the world [[Origin|origin]] (0 0 0).

Example:
<pre>"classname" "trigger_once"
"origin" "1 2 3"
"target" "t1"
"model" "progs/player.mdl"</pre>

===Dormant triggers===
Like any other entities, triggers spawn immediately upon map start. In some occasions, however, it is desirable for triggers to remain initially dormant and only be activated after a certain event or if the player passes through an area for the second time. The trick to create such a trigger is to use a brush-based [[info_notnull]] entity that has its '''use''' field set to ''InitTrigger'', so it will spawn a trigger entity when being triggered itself, and a '''touch''' field that calls the appropriate [[triggers.qc|function]] for interaction. Additional keys required for proper functionality are the same as for the standard entity. This works with all standard trigger varieties and can also be used in conjunction with the [[Map_based_hacks#Point-based triggers with custom bounding box|point trigger]] hack.

Example: <pre>"classname" "info_notnull"
"targetname" "t1"
"use" "InitTrigger"
"touch" "changelevel_touch"
"map" "start"
// brush</pre>

It can also be done by simply inserting the classname of the desired trigger into the '''use''' field of the [[info_notnull]]. This does not require setting the corresponding '''touch''' function as it is called automatically.

Example:
<pre>"classname" "info_notnull"
"targetname" "t1"
"use" "trigger_changelevel"
"map" "start"
// brush</pre>


==Miscellaneous hacks==
===Triggerable explosion===
One of the most well known tricks allows the creation of a triggerable explosion using the '''info_notnull''' entity. It is created as follows:

* Create an info_notnull entity.
* Add the key "use" "barrel_explode".
* Give it a targetname and create some kind of trigger that targets it.

When the trigger is fired, an explosion will occur where the info_notnull is. Be careful, since the explosion is more than just an effect and will injure the player if they are near enough. This is especially true of barrel_explode, as it is one of the most powerful explosions in the game. Fortunately, there are two other explosions that can be used instead by setting the value of the 'use' key to one of the following:

* ''barrel_explode'' - Barrel explosion
* ''OgreGrenadeExplode'' - Ogre grenade explosion (low damage and fairly safe)
* ''tbaby_die2'' - Spawn death explosion

Note that these explosion functions remove the info_notnull entity from the level when the explosion animation has played, so it is not possible to use them multiple times unless the trigger is fired repeatedly at intervals of less than 0.5 seconds. For larger explosion effects, it is possible to set up multiple small explosions in the same way and trigger them in a sequence using [[trigger_relay|trigger_relays]].

===Triggered sounds===
You can play most any sound you wish by triggering it! This requires the sound to be precached, so an entity which uses it must be present in the map beforehand (for example, place an Ogre if you want to use it's chainsaw sounds). It's a pretty simple setup too:

* Create an info_notnull entity.
* Add the key "use" "train_wait" or "use" "plat_hit_bottom".
* Add the key "noise" "<sound you wish to play>". (example:"weapon/lhit.wav" lightning gun zap)
* Give it a targetname and create some kind of trigger that targets it.

===Shoot Monster Projectiles===
This can be a fun one to fool around with. Many of the monsters in Quake have projectile attacks, and we can make an entity that can shoot them on command! Note that these do also play the sounds of the monster shooting them. 

There are also a few caveats: First, in general, you need the monster already present in the map so that the precaching of sounds and sprites and such will work. Second, you need to target them at an entity that will be the 'enemy', which means knowing it's index in the edict list.  If you want to shoot at Player1, this is simple, as Player1 is always index 1. Some of these also require the targeted enemy to be alive, which means they need "health" "1".

* Create an info_notnull entity.
* Add the key "use" "OgreFireGrenade". (Or any other function listed below)
* Add the key "health" "1". (Being 'alive' is required by some enemy attacks)
* Add the key "enemy" "<index of enemy to target>".
* Give it a targetname and create some kind of trigger that targets it.

When triggered, the info_notnull above will fire a grenade toward it's enemy (remember, Ogres are not Z-Aware, so will not angle the shot up or down). You can find the index of entities via the console command ''edictlist'' in most modern engines. Note that the index of an entity is not always guaranteed to be the same on all difficulties or after adding or removing entities from a map. Here are some other projectiles you can use:

* "OgreFireGrenade" - [[Ogre]]'s Grenade.
* "CastLightning" - [[Shambler]] Lightning (you may want to trigger this multiple times)
* "hknight_shot" - [[Death_Knight|Hell Knight]] magic attack. This is just 1 missile.
* "Wiz_StartFast" - [[Scrag]] slime bolt. 2 are fired.
* "enforcer_fire" - [[Enforcer]] laser.
* "ZombieFireGrenade" - [[Zombie]] gib toss.
* "boss_missile" - [[Chthon]]'s homing lava balls.
* "ShalMissile" - [[Vore]]'s homing voreball.

===Increment the Monsters Killed===
This is a useful one if you have placed monsters in a map that the player will not ever be able to kill, such as in combination with another hack which requires a precache. It is also quite simple!

* Create an info_notnull entity.
* Add the key (use : boss_death10).
* Give it a targetname and create some kind of trigger that targets it.

How does this work? boss_death10 is a function used by Chthon that is triggered at the end of his death animation which increments the counter that tracks the monsters you have killed. This also removes the entity that calls it, so you must have one of these info_notnull entities set up for each increment you want to do. Misuse of this hack also lead to situations where you have 'killed' more monsters than exist in the map, such as a counter showing the player has killed 11/10 monsters.