LlPushObject/Havok4Implementation

 // This is not quite pseudo code for how the llPushObject() effect is computed.
 // Really it is simplified C++ code that doesn't quite reflect our true API
 // (for instance, the LLObject class doesn't actually exist), but it is a
 // fairly accurate outline of what is going on.  This code probably doesn't
 // compile.  Fix any syntax errors you find -- it's a wiki! -- Andrew
 //
 void llPushObject( 
 		const LLObject& pusher, 
 		const LLObject& pushee, 
 		const LLVector3& linear_impulse, 
 		const LLVector3& angular_impulse, 
 		bool use_pushee_local_frame )
 {
 	LLPhysicsBody& pushee_body = pushee.getPhysicsBody(); 
 	if (!pushee_body || pushee_body.isKeyframed() )
 	{
 		// some objects don't have collidable bodies (trees, grass)
 		// and keyframed (non-dynamic) objects can't move
 		return;
 	}
 
 	if ( pushee.isAvatar()
 		&& pushee.isGod()
 		&& pusher.getOwnerID() != pushee.getID() )
 	{
 		// avatars in admin mode cannot be pushed 
 		// unless they are the pusher's owner
 		return;
 	}
 
 	// How much effect an llPushObject() call has depends on whether
 	// the pusher had enough "script energy" to execute.  If the pusher
 	// only has half of the required energy then it will push, but the
 	// effect of the push is reduced to half of what it would be, and the
 	// pusher is left with zero energy at the end.
 	//
 	// The "script energy" system was implemented waaaaay back in the beginning
 	// and was done for a few reasons:  (1) as a pre-emptive goo and grief
 	// throttle for problems that we expected to encounter (certain operations
 	// cost energy, and hence an one object's effectiveness is throttled by its
 	// energy budget) and (2) to provide a sort of balance/tradeoff when
 	// designing in-world objects that had some sort of gaming application (big
 	// guns should have more potency than small guns, hence the larger the
 	// object the more energy).
 	//
 	// In any case, the energy bugdet is recovered at some fixed rate over time
 	// but the holding tank of each object depends on its mass, up to some
 	// maximum.
 	//
 	// Way back in in 2003 or so we added a distance^3 term to the cost of
 	// llPushObject() designed prevent huge impulses from pushing people
 	// around.  Unfortunately the original implementation was severely flawed
 	// in a particular way -- the term was additive instead multiplicative.
 	// The cube power gets big fast, but not all that big or fast.  If the
 	// original push magnitude dwarfed the cubed term then you still ended up
 	// with a giant effect.  In other words: 
 	//
 	// 10^26 * (energy_recovered_during_last_frame) = Very_Big_Number
 	//
 	F32 distance = (pushee.getPosition() - pusher.getPosition()).length();
 	F32 distance_term = distance * distance * distance * SCRIPT_ENERGY_PER_METER_AWAY;
 
 	// How to fix this?  We can't change the energy consumption since
 	// lots of Residents have tuned their pushers just right.  But we
 	// don't want arbitrarily high impulses over arbitrarily large 
 	// distances.  So here's what we'll do:
 	//
 	// (1) clamp obnoxiously large impulses (after the energy consumption)
 	// (2) actually attenuate the impulse by distances that are beyond
 	//     some threshold
 
 	F32 pusher_mass = pusher.getMass();
 
 	// (2) we compute the distance attenuation factor early since it applies to
 	// both the linear and angular cases.  This attenuates pushes that are
 	// beyond (max_distance + 1) 
 	F32 PUSH_ATTENUATION_DISTANCE = 17.f;
 	F32 PUSH_ATTENUATION_SCALE = 5.f;
 	F32 distance_attenuation = 1.f;
 	if (distance > PUSH_ATTENUATION_DISTANCE)
 	{
 		// +1 below to avoid the asymptotic part of 1/x
 		F32 normalized_units = 1.f + (distance - PUSH_ATTENUATION_DISTANCE) / PUSH_ATTENUATION_SCALE;
 		distance_attenuation = 1.f / normalized_units;
 	}
 
 	// linear
 	LLVector3 applied_linear_impulse = linear_impulse;
 	{
 		// consume energy according to the intended impulses
 		F32 impulse_length = linear_impulse.length();
 	
 		// NOTE: the pusher_mass factor in the desired_energy calculation 
 		// is just wrong, it should be the pushee_mass, but now that it
 		// has been wrong for years we can't fix it!
 		F32 desired_energy = impulse_length * SCRIPT_ENERGY_PER_MOMENTUM * pusher_mass;
 		if (desired_energy > 0.f)
 		{
 			desired_energy += distance_term;
 		}
 	
 		// LLObject::consumeEnergy() returns 1 if there is enough energy,
 		// else returns the fraction of energy available.
 		F32 scaling_factor = pusher.consumeEnergy(desired_energy);
 	
 		// (1) clamp obnoxiously large impulses
 		// the max push possible is what it would take to levitate the
 		// smallest object that has the max script energy
 		F32 max_push_impulse_length = MAX_ENERGY_MASS * fabsf(GRAVITY) * PHYSICS_TIMESTEP;
 		if (impulse_length > max_push_impulse_length)
 		{
 			// reduce the scaling factor by the ratio
 			scaling_factor *= max_push_impulse_length / impulse_length;
 		}
 	
 		// (2) attenuate pushes that are from very far away
 		scaling_factor *= distance_attenuation;
 	
 		applied_linear_impulse *= scaling_factor;
 	}
 
 	// angular
 	LLVector3 applied_angular_impulse = angular_impulse;
 	{
 		// NOTE: same comments here as to the incorrectness of the mass units
 		// with an extra problem: the angular energy consumption should be
 		// proportional to the actual change of angular momentum (i.e. should
 		// involve the inertia tensor) so the linear mass factor here is not
 		// only from the wrong object but is also the wrong property.  Oh well.
 		F32 desired_energy = angular_impulse.length() * SCRIPT_ENERGY_PER_MOMENTUM * pusher_mass;
 		if (desired_energy > 0.f)
 		{
 			desired_energy += distance_term;
 		}
 		
 		// consume energy
 		F32 scaling_factor = distance_attenuation * pusher.consumeEnergy(desired_energy);
 
 		// (1) clamp obnoxiously large impulses
 		F32 impulse_length = angular_impulse.length();
 		if (impulse_length > max_push_impulse_length)
 		{
 			scaling_factor *= max_push_impulse_length / impulse_length;
 		}
 	
 		// (2) attenuate pushes that are from very far away
 		scaling_factor *= distance_attenuation;
 
 		applied_angular_impulse *= scaling_factor;
 	}
 	
 	if ( use_pushee_local_frame )
 	{
 		// rotate the directions of the impulses into the pushee's local frame
 		LLQuaternion rotation = pushee.getRotation();
 		applied_linear_impulse *= rotation;
 		applied_angular_impulse *= rotation;
 	}
 
 	if (pushee.isAvatar())
 	{
 		// NOTE: we ignore the angular part since the avatar cannot yet be spun
 		// from external or attachment forces
 		if (pusher.isAttachment()
 			&& pusher.getAvatarID() == pushee.getID())
 		{
 			// this is an attachment pushing its avatar, so the push must go
 			// through the avatar controller which will guard against too fast
 			// velocities and do the right thing for the current movement mode
 			pushee.getAvatarController().accumulateAttachmentImpulse(applied_linear_impulse);
 		}
 		else
 		{
 			// this is an attachment pushing another avatar, so the push must
 			// go through the avatar controller which will gaurd against too
 			// fast velocities and do the right thing for current movement mode
 			pushee.getAvatarController().applyExternalImpulse(applied_linear_impulse);
 		}
 	}
 	else
 	{
 		pushee_body.applyImpulse(applied_linear_impulse);
 		pushee_body.applyAngularImpulse(applied_angular_impulse);
 	}
 }