
=================================================================

	Gyro - The QuakeC Physics Plugin

		Version 1.0
		By Quake Matt (rogermelon@yahoo.com)

=================================================================


		----- Introduction -----

	Welcome to Gyro!
	
	Packaged into a single .qc file, Gyro is designed for anybody
	wishing to add some simple physics to their mods without getting
	bogged down with code rewrites and lots of nasty maths. With just
	a couple of extra lines of code, it's easy to have your rockets
	deflected by explosions, have gibs float smoothly on the water
	surface or, if you really want to, have your grenades hover above
	the ground and repulse incoming nails!

	All of the processing is done transparently to existing code so,
	more often than not, no changes need to made - only a few physics
	initialisation routines need to be called and the rest just slots
	into place!



		----- Installation -----

	1.	Add "physics.qc" into your progs.src file, just between
		"subs.qc" and "fight.qc".

	2.	In world.qc, find the worldspawn() function. You need
		to add the line "P_StartPhysics();" somewhere in here.
		I usually put it just after "W_Precache();", but it
		shouldn't make any difference where you put it.

	3.	Before you can see any physics running, you need to run
		one or more 'activation macros' on your entities. At the
		very least, you must use "P_ActivatePhysics(targ, weight)"
		on an entity, as this will declare it to be part of the
		physics system. All the activation macros are given below.

	4.	With the P_* macros, you can get all sorts of effects,
		such as bouyancy and thrust, but you'll still be missing
		one important part of the system - the forces, such as
		the shockwave of an explosion. Forces are typically just
		a single line and integrate perfectly with physics-enabled
		objects!



		----- Physics Macros -----

	P_Deactivate(entity) =
		Deactivates all physics on an entity.


	P_ActivatePhysics(entity, float weight) =
		Activates basic physics on and binds an entity to Gyro.
		No other activations will take effect without this! The
		weight value is given in units approximating grams, so
		a grenade would weigh between about 500-1000 units. This
		macro will also set air resistance, based on weight.


	P_ActivateBouyancy(entity, float bouyancy) =
		Bouyancy is how well an object will float in water and is
		set in the same units as the weight. Basically, if the
		bouyancy is less than the weight, the object will sink
		and, if greater than the weight, the object will float.
		Water resistance is also set, plus lava and slime will
		behave differently.


	P_ActivateAerodynamics(entity, float aerodynamics) =
		An aerodynamic object will attempt to face the direction
		it's travelling, which is handy for rockets and other
		streamlined objects. A higher aerodynamics value (100+
		is good for rockets) will make the object turn faster.


	P_ActivateThrust(entity, float thrust) =
		This makes an object constantly emit a thrust out of
		it's back end, like the thrust on a rocket, for example.
		The units pretty much equate to grams again, so a thrust
		greater than the weight can keep an object airbourne.


	P_ActivateHover(entity, float power, float range) =
		Perhaps just a gimmick, a hovering object will be pushed
		up and away from the ground. The range of the hover force
		is given in standard Quake distance units while power is,
		of course, given in the same units as weight. You might
		need to experiment with this to get the results you want!


	By passing an input of zero, these macros can also be used to
	deactivate features. For added fun, you could even try passing
	some negative values. Additionally, can set parameters manually if
	you need to, say to negate air resistance on a thrust-less object.
	Take a look at the entit fields in the code below to see what you
	need!



		----- Force Macros -----

	F_Deactive(entity) =
		Removes all force effects from an object.


	F_ActivateSphere(entity, float power, float range, float lifespan) =
		A basic, yet useful, spherical force. This can be used for
		explosions, gravity wells, repulsor shields, etc. The power
		indicates the strength of the force, but doesn't (yet)
		correspond to the standard weight units. Basically,
		somewhere in the region of 200-300 is fine for an explosion.
		The range gives the radius of the force, ands should be fairly
		easy to figure out, while the lifespan determines how long
		the force lasts. During the lifespan, the power of the force
		will decay, unless the lifespan is set to zero or less, in
		which case the force will remain, at full power, until
		deactivated.


	The above macros deal with adding a force to an entity, yet this isn't
	always want you want. To create a stationary force in the air, replace
	"Activate" with "Spawn" (eg. F_SpawnSphere) and give a position vector
	rather than an entity. Be warned, though, that forces created in this
	manner cannot be removed by hand, only by setting a lifespan!



		----- Physics Feedback -----

	Occasionally, it's necessary for an object to know when physics are
	being applied to it. Perhaps a nail needs to stop flying and start
	bouncing when it gets caught in an explosion, or a rocket burns out
	when it hits water? No problem, since Gyro lets you define two extra
	entity voids: ".p_use_force" and ".p_use_water"

	These are called whenever an object is subjected to either water or
	a force (like an explosion), and can be very handy for changing how
	objects behave without needing to check for conditions yourself.



		----- Hints and Tips -----

	- Remember that you can make negative forces, to suck things in
	- Check out the modified weapons.qc to see how things work
	- Use impulse 101 and 102 in the above mod to see something special
	- Bouyancy combined with aerodynamics makes floating objects better
	- Setting a thrust can keep deflected rockets moving properly
	- New versions are on the way, with some fancy new forces
	- Gyro can be plugged into even non-FPS mods



		----- Known Bugs -----

	- Too many splashing noises on some engines
	- Flying/floating objects can sometimes get stuck to floor
	- Weight system not 100% perfect (bouyancy, etc)



		----- Next Version -----

	- F_ActivateDampen (sphere, increases air resistance)
	- F_ActivateTurbine (cyclic force, like a whirlwind)
	- Turbulence, particularly to emulate waves in water
	- More feedback control
	- More macros



		----- Copyright and Distribution -----

	Gyro is Copyright (C) 2005, Matthew Lawrence

	This program is free software; you can redistribute it and/or modify
	it under the terms of the GNU General Public License as published by
	the Free Software Foundation. Just let me know when you do!

	Thanks for reading! 
