Headcrab Canister Gun
Version 2
(c) phenex
-------------------------


This is the original headcrab canister SWEP, updated to feature multiple selectable, customizable canisters as well as bug fixes, especially for the sky_camera bug that prevents the use of this SWEP in gm_construct.

If you need help installing this SWEP, please see this thread on the GMod Lua forum:
http://forums.facepunchstudios.com/showthread.php?t=105942

If you follow those instructions you will have installed this SWEP properly.

HEADCRAB CANISTERS FOR DUMMIES
==============================

Give yourself the SWEP, following the instructions in the forum thread I mentioned above, then, press primary fire (Left Mouse) to fire a canister at the point you're aiming at, or press secondary fire (Right Mouse) to cycle through the available headcrab canisters.

CUSTOMIZING THE HEADCRAB CANISTERS
==================================

If you don't know how to program even the most basic things in Lua, this is not for you. Either learn how to program in Lua, or ask, in the headcrab canister thread (please don't make a new topic in -any- of the GMod Lua forums), and very VERY politely, for someone to make you a custom canister to your liking.

If you're still interested in knowing how to modify the canister types available to you, read on.

In order to customize the headcrab canisters, you will need to open up the weapon_canister.lua file with a text editor and locate the heading that reads:

------------------------------------------------------------------------------------------------
----------- Headcrab Canister Type List
------------------------------------------------------------------------------------------------

The table declared immediately below this heading is the headcrab canister type list. It is a simple Lua table with table elements listed below. In order to add a new canister, you need to add a new numerical index to the table. See the existing code for an example. Make certain that you do not skip any numbers in the table, because when the SWEP encounters an index that doesn't exist, it will loop back to index #1.

For all properties, there are a few suggested values with brief descriptions located directly above the canister type list.

Available Headcrab Canister Properties:
---------------------------------------

 * name - The name of this canister, displayed when the user switches to it. Something descriptive would be nicer than "Canister #1".

 * headcrabtype - The variety of headcrab that will emerge from the canister. 

	HEADCRABTYPE_NORMAL - Normal HL1-style headcrabs.
	HEADCRABTYPE_FAST - Speedy long-legged headcrabs.
	HEADCRABTYPE_POISON - Black, hissing, envenomating headcrabs.
	HEADCRABTYPE_NONE - No headcrabs will come out.

	Notes: You can't mix the types, it's all normal, or all fast, or all poison.

 * headcrabcount - The number of headcrabs that will emerge.

	Any positive integer.
	
	Notes: Be reasonable with the number you spawn, per canister. Anything more than 10 is too many.

 * impactdamage - The damage inflicted on any entities within range of the canister when it impacts the ground.

	Any positive integer.

 * impactradius - The radius about the canister in which impact damage will be inflicted.

	Any positive integer, measured in game units.

	Notes: Having high impactdamage or impactradius values will cause a server with lots of props to experience lagginess because a large number of props will be shoved around when the canister hits.

 * flighttime - The time delay after firing the canister during which the canister will be in flight and any players near the impact point will have a chance to escape.

	Any positive float, measured in seconds.

	Notes: I recommend at least a few seconds, as explained in the later section detailing the timeline of a headcrab canister.

 * flightspeed - The speed at which the canister will move through the sky, moving towards its impact point.

	Any positive float, measured in game units.

	Notes: I recommend values of at least 2-3000, or else the canister will appear to be moving too slowly.

 * opendelay - The time delay after the canister impacts, before the canister will open up.

	Any positive float, measured in seconds. 

	Notes: A value of 0 indicates that the canister is not supposed to open, ever. A delay that is too short (less than 0.5 seconds) may not allow enough time after impact for the canister to open properly.

 * spawndelay - The time delay after the canister opens, before the headcrabs will emerge.

	Any positive float, measured in seconds.

	Notes: If you don't want any headcrabs to spawn, set the headcrabtype to HEADCRABTYPE_NONE or set the headcrabcount to 0. A delay that is too short (less than 0.5 seconds) may not allow enough time after opening the canister for the headcrabs to properly spawn and emerge.

 * removedelay - The time after the headcrabs BEGIN to spawn, before the canister will be deleted from the game.

	Any positive float, measured in seconds.

	Notes: If you want the canister to stay around indefinitely afterwards, set the value to REMOVEDELAY_PERSIST. If you have headcrabs in your canister, a removedelay of at least 2 seconds, plus an additional 2 seconds for every headcrab, is HIGHLY recommended. This may need to be tweaked for larger numbers of headcrabs.

Timeline of a Headcrab Canister:
--------------------------------

The timeline of a headcrab canister is important to understand if you want to have an easier time of customizing them.

There are 5 sections to the timeline:

	Flight
	Impact
	Opening
	Spawning
	Removal

Flight
------

	This section starts when the SWEP is fired, lasts flighttime seconds, and ends when the canister impacts the ground with an explosion. The only two ways to customize this section are the flighttime and flightspeed properties. An understanding of simple physics helps here.

Impact
------

	This is not so much a section as it is an instant in the timeline. The two properties here are impactdamage and impactradius, and they affect the explosive damage inflicted when the canister impacts an area. This is simple enough to understand so I'll leave you to tweak these values and experiment.


Opening
-------

	This section starts immediately when the canister impacts the ground, and ends with the eventual opening of the top vanes of the canister. This section is optional and may be skipped by setting the only property of this section, opendelay, to OPENDELAY_DONTOPEN. If you skip this section in this manner, common sense and physics dictate that the spawn section will also be skipped.

Spawning
--------

	This section starts immediately when the canister vanes open, and ends after a delay of spawndelay seconds passes. When this delay expires, headcrabs (if any) will start to emerge from the canister. If you specify that no headcrabs will come out (either through using HEADCRABTYPE_NONE or setting headcrabcount to zero), this section will be skipped.

Removal
-------
	
	This section starts immediately when whatever previous section finishes, and either ends when a delay of removedelay seconds passes, or never, if you specify a removedelay of REMOVEDELAY_PERSIST.


Once you understand how the timeline works you'll have no problem making a canister that behaves exactly the way you want it to behave.

Finally, any questions, bugs, comments, suggestions or canister requests may be directed to the original topic where you downloaded this SWEP.

-- Phenex