Platform Physics: Grapple Hook

One of the best upgrades in Super Metroid is the grapple beam. It gives you the ability the explore much more of the world, and avoid dozens of annoying enemies on the way. It's even useful for shocking to death a boss. So I knew I wanted a swinging grapple hook in Platform Hack.



Not only is the grapple hook fun to use in game, its an interesting challenge to implement in code. There are essentially three main parts:

1. The "rope" needs to shoot out from the player and catch on some surface of the world. This can either be special tiles, or any sort of tile, though in some games this may lead to exploits.
2. Once attached, the player swings in motion similar to a pendulum.
3. When you release, you swing in the direction you were traveling, potentially covering gaps. The player can also re-attach the grapple, and swing horizontally ala Tarzan.

Similar to the jump logic, the first thing I did was create a data structure to hold all the variables we need to keep track of during the grapple swing:

public struct GrappleStruct
{
 public int mode;   //0=shooting, 1=attached
 public SwingCurveStruct swingCurve;
 public Vector2 position; //position of "hook"
 public TimeSpan GrappleTimer;

 public Vector2 launchVector;
 public Vector2 FireVector;
 public float RopeLength;
 public float fireSpeed;
 public Vector2 aimVector;
}
 
public struct SwingCurveStruct
{
 public Curve YCurve;
 public Curve XCurve;
}

SwingCurveStruct is also a data type that comes in handy - it holds two Curve objects. The Curve class allows you to interpolate over a curve given a set of discrete points. So instead of defining complex movement purely by physics formulas, you can numerically determine a few key points along the curve, plug them into a Curve class and then approximate the curve easily. We use a SwingCurveStruct to hold the points in the swing itself.

GrappleTimer tracks how much time the player has been "attached" to the grapple, so we can evaluate the correct position in the swing.

launchVector defines the vector when the player releases from the grapple hook, and lets the player "fling" up in the air.

FireVector is the direction the player is shooting the grapple hook. Right now the "rope" only goes in an upward 45 degrees for ease of use, however this value could be set by the player.

The RopeLength and fireSpeed define how far and how fast the rope itself can shoot out. These values are set when the grapple struct is first created. Longer and faster ropes make it much easier to attach to surfaces, and vice-versa.

The bulk of the logic for the grapple is done in the DoGrapple function:

public bool DoGrapple(bool artifactPushed, GameTime gameTime, ref Vector2 position, ref Vector2 Force1Vector, ref Vector2 velocity, Level level, SpriteEffects flip)
{
 float elapsed = (float)gameTime.ElapsedGameTime.TotalSeconds;
 bool isSwinging = false;

 if (artifactPushed)
 {
  if (playerGrappleStruct.mode == 0)
  {
   if (playerGrappleStruct.FireVector.X == 0 && playerGrappleStruct.FireVector.Y == 0)
   {
    if (playerGrappleStruct.aimVector.X == 0 && playerGrappleStruct.aimVector.Y == 0)
    {

     if (flip == SpriteEffects.FlipHorizontally)
     {
      playerGrappleStruct.FireVector = new Vector2(1f, -1f);
     }
     else
     {
      playerGrappleStruct.FireVector = new Vector2(-1f, -1f);
     }
    }
    else
    {
     playerGrappleStruct.FireVector = new Vector2(playerGrappleStruct.aimVector.X, playerGrappleStruct.aimVector.Y);
    }
   }
   playerGrappleStruct.position += (playerGrappleStruct.FireVector * elapsed * playerGrappleStruct.fireSpeed) + (velocity * elapsed);
   if (Helper.getDistance(position, playerGrappleStruct.position) > playerGrappleStruct.RopeLength)
   {
    playerGrappleStruct.position = position + new Vector2(0, -25);
   }
   GrappleCollision(level,position,velocity);

   isSwinging = false;
  }
  if (playerGrappleStruct.mode == 1)
  {
   playerGrappleStruct.GrappleTimer += gameTime.ElapsedGameTime;
   float maxTime = playerGrappleStruct.swingCurve.XCurve.Keys[playerGrappleStruct.swingCurve.XCurve.Keys.Count - 1].Position;
   float newPositionX = playerGrappleStruct.swingCurve.XCurve.Evaluate((float)playerGrappleStruct.GrappleTimer.TotalSeconds % maxTime);
   float newPositionY = playerGrappleStruct.swingCurve.YCurve.Evaluate((float)playerGrappleStruct.GrappleTimer.TotalSeconds % maxTime);
   playerGrappleStruct.launchVector = setSwingVelocity(new Vector2(newPositionX, newPositionY), position, (float)gameTime.ElapsedGameTime.TotalSeconds);

   playerGrappleStruct.LaunchTimer = TimeSpan.FromSeconds(1);
   playerGrappleStruct.launchCurve = setLaunchCurveStruct(playerGrappleStruct.launchVector);
   position.X = newPositionX;
   position.Y = newPositionY;
   isSwinging = true;
  }
 }
 else
 {
  if (playerGrappleStruct.mode == 1)
  {
   playerGrappleStruct.mode = 0;
   Force1Vector = playerGrappleStruct.launchVector;
  }

  //reset the rope;
  playerGrappleStruct.position = position + new Vector2(0, -25);
  playerGrappleStruct.FireVector = new Vector2(0f, 0f);

  isSwinging = false;
 }
 return isSwinging;
}

The function has three main sections, corresponding to the three parts listed above.

1. If we're shooting the grapple hook (artifactPressed) and in mode 0, then increment the location of the "hook" and check if we've collided with any surfaces.

We use the GrappleCollide function to check:

private void GrappleCollision(Level level, Vector2 position, Vector2 velocity)
{
 Vector2 temp;

 if (Collision.getLineCollision(position + new Vector2(0, -25), playerGrappleStruct.position, level, out temp))
 {
  if ((position.Y - 25) > temp.Y && Math.Abs(position.X - temp.X) > 50) //make sure we only grappling to points above us
  {
   playerGrappleStruct.position = temp;
   playerGrappleStruct.mode = 1;
   playerGrappleStruct.swingCurve = setGrappleSwingCurve(playerGrappleStruct.position, position + new Vector2(0, -25), velocity);
   playerGrappleStruct.GrappleTimer = TimeSpan.FromSeconds(0f);
  }
 }
}

getLineCollision essentially gets a list of all tiles that are overlapped by a line connecting the player to the hook. We then traverse this list, moving outward from the player, and if we hit an Impassable or Platform tile, we return true, we're connected.

Once we're connected, we change to mode 1 and we have to calculate the swing curve:

 /*
 * given the initial force vector (x, y), and the angle of attachment, calculate the swing curve of the grapple, using pendulum physics
 * pendulum forumula
 *
 * O'' = -g/R sin O
 * angular acceleration = - gravity / length of rope * sin angle
 * angle (O=vertical)
 * */
private  SwingCurveStruct setGrappleSwingCurve(Vector2 origin, Vector2 playerPosition, Vector2 initVelocity)
{
 //length of rope
 float length = (float)Math.Sqrt(Math.Pow((origin.X - playerPosition.X), 2) + Math.Pow((origin.Y - playerPosition.Y), 2));

 Vector2 slope = (playerPosition - origin);
 slope.Normalize();
 slope = new Vector2(slope.X, slope.Y * -1);

 //get start angle
 float angleStart = (float)(Math.Atan2((double)slope.Y, (double)slope.X));

 float initVelocityRadians = getInitVelocity(length, origin, playerPosition, initVelocity);

 float time = 0f;
 float angleAcc = 0f;
 float angleVel = initVelocityRadians;
 float curAngle = angleStart;

 SwingCurveStruct retval = new SwingCurveStruct();
 retval.XCurve = new Curve();
 retval.YCurve = new Curve();
 retval = addCurvePosition(retval, time, origin, length, curAngle);

 //iterate through and set curve keys
 for (float f = time; f < 20f; f += .1f)
 {
  angleAcc = -(GravityAcceleration / length) * (float)Math.Sin(curAngle + (float)Math.PI / 2);
  angleVel += angleAcc * .1f;
  curAngle += angleVel * .1f;
  retval = addCurvePosition(retval, f, origin, length, curAngle);
 }

 return retval;
}

This function uses the formula for a pendulum to create Curve objects that the player will move on while attached. Here's a great site that walked me through pendulum physics: http://www.myphysicslab.com/pendulum1.html
First, we have to determine the initial angle the player is attached:

float angleStart = (float)(Math.Atan2((double)slope.Y, (double)slope.X));

Next, we set an initial velocity. This basically gives the player a little more momentum in the swing if they are moving when they attach, and makes "Tarzan" swings a little more powerful.

 private float getInitVelocity(float length, Vector2 origin, Vector2 playerPosition, Vector2 initVelocity)
{
 //pythagorean?
 float velocityDist = (float)Math.Sqrt((initVelocity.X * initVelocity.X) + (initVelocity.Y * initVelocity.Y));
 float cosx = Math.Abs((length * length + length * length - velocityDist * velocityDist) / (2 * length * length));
 float initVelocityRadians = (float)Math.Acos(cosx);
 if (float.IsNaN(initVelocityRadians))
  initVelocityRadians = 0f;

 //unit circle goes counter clockwise, so if we are swinging the otherway, then multiple by -1
 if (initVelocity.X < 0)
  initVelocityRadians *= -1;

 return initVelocityRadians;
}

Last, we just need to iterate the points of a pendulum into the Curve structs, The pendulum takes the following forumla:

angleAcc = -(GravityAcceleration / length) * (float)Math.Sin(curAngle + (float)Math.PI / 2);

Once we have the angular acceleration, we can determine the angular velocity, and thus the current position in radians. From there, we can easily calculate the current position along the circumference of a circle (the "hook" being the origin).

//gets the x,y vector at the end of the pendulum, given origin, length and radians
private Vector2 getCurvePosition(Vector2 origin, float length, float radians)
{

 return new Vector2((float)(origin.X + length * Math.Cos(radians)), (float)(origin.Y + length * (float)Math.Sin(radians) * -1));
}

Note: the swing algorithm breaks down if the player attaches to a surface at less than the horizontal plane. This is because the swing follows the path of a pendulum, and if the angle is greater than the horizontal, the rope will be "stiff", and the player could even use it as a sort of stilt. If you want full elastic grapple hooks, some different physics logic is needed
2. Once we are attached, we just need to determine our current position on the swing curve.

float newPositionX = playerGrappleStruct.swingCurve.XCurve.Evaluate((float)playerGrappleStruct.GrappleTimer.TotalSeconds % maxTime);
float newPositionY = playerGrappleStruct.swingCurve.YCurve.Evaluate((float)playerGrappleStruct.GrappleTimer.TotalSeconds % maxTime);

Note: We're also doing a special collision check at this point to make sure the player can't swing through walls. Because we aren't adjusting the player velocity, and instead directly updating the player position, there is the chance that the player could move so fast they could warp through walls (given a long enough rope, or a strong enough GravityAcceleration). So lots of tweaking/testing is needed to find the right balance.
3. Once the player lets go (artifactPushed == false), we need to apply the launch velocity. We actually set the launch velocity while we are connected with the following function:

private Vector2 setSwingVelocity(Vector2 position1, Vector2 position2, float timeDiff)
{
 return (position1 - position2) * (float)(1.0 / timeDiff) * 20;
}

We find the difference in position during the swing, then multiply by 20. The 20 is an arbitrary value, and can be adjusted to set how much the player "flings" after they release the grapple hook. This is another case where if you use realistic physics, the gameplay isn't as fun as using exaggerated calculations.

Last, we apply gravity as normal. The launch vector is saved in Force1Vector, and is applied along with the other vectors.

So that's the basic grapple hook, probably the most difficult "movement tool" being implement in Platform Hack. Next time, it's onto something completely different - procedural maze generation!

Platform Physics: Jumping

Ever since Super Mario Brothers (and perhaps Donkey Kong before that), the jump has been iconic of Platform games. At first glance, it seems like it would be pretty easy to implement a jump using classic physics - apply an upward force to the player and then have gravity act as a constant downward acceleration. This can be done, however, it leads to pretty punishing gameplay.

Platform games don't follow the laws of physics. Here's a few reasons.

1. We want the player to be able to move horizontally in the air. This lets the player tweak movement and land much more difficult jumps. This breaks the 1st law of Thermodynamics.
2. We want the jump (and the pull of gravity) to be limited by a max velocity. There are a few reasons for this. One, it makes the gameplay a bit more manageable to not be flying all over the place. Second, the algorithms of collision detection start to break down if the player (or any other object) moves faster than the height of a tile in a single update of the game loop.
3. We want the jump to have a constant upward motion, instead of a large initial velocity immediately starting to taper off by gravity. As long as a player presses the jump key (within limits), we want the player to jump upwards.



So let's look at the pieces needed to implement a jump:

For Platform Hack, I wanted jumps to be pretty versatile. Which means there will be double (and even triple) jumps, wall jumps and upgrades to jump power. So I needed a data type that could store and abstract away the details of the jump:

  
    public struct JumpStruct
    {
        public int curNumJump;
        public int totalNumJump;

        public bool isJumping;
        public bool wasJumping;

        public float jumpTime;
        public TimeSpan jumpTimer;
    }

In the struct we have curNumJump and totalNumJump. This is used to keep track of double and triple jumps.

isJumping is a boolean thats mapped to the player jump key. wasJumping is a boolean that specifies whether the player was pressing jump *the previous update*. This is important for making sure the player presses the jump key for each jump instead of just holding it down.

jumpTime is the total amount of time the player can jump. Increasing this number allows the player to press down the jump key longer, and have larger jumps. jumpTimer is the actual timer that counts down as soon as the jump starts.

During each game loop, we must run the update on the player physics:

   
GravityVector.Y = MathHelper.Clamp(velocity.Y + GravityAcceleration * elapsed, -MaxFallSpeed, MaxFallSpeed);
PlayerVector.Y = DoJump(PlayerVector.Y, gameTime);
PlayerVector.X += MathHelper.Clamp(movement * MoveAcceleration * elapsed, -MaxMoveSpeed, MaxMoveSpeed);
velocity = GravityVector + PlayerVector + Force1Vector + Force2Vector;
velocity.X = MathHelper.Clamp(velocity.X, -MaxMoveSpeed, MaxMoveSpeed);
velocity.Y = MathHelper.Clamp(velocity.Y, -MaxMoveSpeed, MaxMoveSpeed);
Position += velocity * elapsed;
Position = new Vector2((float)Math.Round(Position.X), (float)Math.Round(Position.Y));

One thing I've done is kept the various velocities (GravityVector, PlayerVector) seperate, and then combined them before applying to the player movement. However, when I update gravity, it draws from the full velocity. This little tweak helps smooth out the upward curve of the player jump, or if they fall off a ledge. Gravity is also "clamped" at MaxFallSpeed, which acts as a sort of terminal velocity. Clamp is important for reason #2 above.

The Player.X velocity (horizontal movement) is updated by player control - the movement variable is set with the left and right buttons. This allows the player to move horizontally even if they are in the air.

The Player.X veloctiy is set with the DoJump function:

  
private float DoJump(float VelocityY, GameTime gametime)
{
 VelocityY = 0;
 if (JumpCheck(gametime, IsOnGround))
 {
  if ((IsOnGround) || playerJumpStruct.jumpTimer > TimeSpan.Zero)
  {
   if (playerJumpStruct.jumpTimer.TotalSeconds == playerJumpStruct.jumpTime)
   {
    level.thisPlatformerGame.gameAudio.playSound("PlayerJump");
   }
  }

  // if we are in the ascent of the jump
  if (TimeSpan.Zero < playerJumpStruct.jumpTimer && playerJumpStruct.jumpTimer <= TimeSpan.FromSeconds(playerJumpStruct.jumpTime))
  {

   GravityVector.Y = 0;
   // fully override the vertical velocity with a power curve that gives players more control over the top of the jump
   VelocityY = JumpLaunchVelocity * (1.0f - (float)Math.Pow((playerJumpStruct.jumpTime-playerJumpStruct.jumpTimer.TotalSeconds) / playerJumpStruct.jumpTime, JumpControlPower));
  }
 }
 return VelocityY;
}

Essentially, this function first checks if we can jump. JumpCheck returns true if the player is on the ground, or the curNumJumps is less than totalNumJumps.

If we're on the ground, or the jump timer is less than the total jump time, then set the Player.Y velocity. We're using a power function to give the player a sort of exponential curve to upward velocity, starting with the most power and decreasing as we reach the top. We also are setting Gravity to 0 to give the jump a bit more "floatiness".

Once the DoJump returns, we have to calculate the player's new position. Velocity (and acceleration values - JumpAcceleration, GravityAcceleration) is stored in terms of seconds (500 pixels / second). Each update function only takes a fraction of a second, so we need to multiple the velocity by elapsed, which will give the appropriate amount to move the player.

Lastly, we round the player position to the nearest round number, so the sprite is positioned cleanly on the pixels. This is essential for player collision - otherwise the player can get stuck in floors and walls due to a fraction of a pixel overlapping.

The *feel* of the jump is essential to how the game plays. Stronger gravity and less precision of player movement can make the game much more difficult. Conversely, if gravity is too weak and the player is too floaty, the game can feel slow, frustrating or boring. Tweaking the GravityAcceleration, JumpAcceleration and Clamp values can drastically change the feel of the jump.

Next: I'll go into the details of the infamous grappling hook!

Note on Code samples: I'm more interested exploring algorithms and general concepts on this blog rather than complete code samples. The codebase I'm working with is a bit messy to upload for each example. If you want to follow along, start with the Platformer Starter Kit for XNA and go from there.

Where I'm At Now

Right now I have a pretty good idea of what I want Platform Hack to be in regards to gameplay. The original inspiration was actually Super Metroid, one of the best platformers of all time.



Super Metroid has all the standard action-platformer elements of jumping and attacking enemies, but what really set the game apart were the RPG elements, weapons and boss fights. As you make your way through the maze-world, you unlock upgrades to health and weapons. There are also tools you acquire that allow you to traverse the world more easily, including the the grapple beam and the space jump. The boss fights were also extremely polished, with animations to match, finding that great balance between challenge and cakewalk.



I'd like Platform Hack to borrow a lot of those elements, including the "movement" upgrades like the double jump and the grapple hook. Because the world in Platform Hack will be procedurally generated, there's the possibility of having super high vertical walls and cliffs, which could potentially post a problem for the standard jump. Of course, I'll have to tweak those maze-generation algorithms to limit the cliffs on the easier levels. But one of the goals of the game will be to acquire these "movement tools" in addition to more powerful weapons.

As far as development, I see the project in three stages:

1. Core Engine Development. This includes algorithms for collision detection, physics, player control, HUD, enemy movement and attacks, and boss scripting.

2. Game World Development. This is the world generation using procedural maze algorithms, different "features" like elevators, springs, doors, traps, as well as the more specific enemy and boss instances.

3. Asset Creation. This is where the game finally gets it's look - includes drawing and importing all the player, enemy and boss sprites, particle effects, tile and background images, HUD font and icons, sounds and music. Hopefully I have some help on board for this stage. But it's still a ways off.

Right now I'm still deep in stage 1, trying to work out the tweaks in collision detection for various movement tools, including the Grapple Hook and Jump Jets. But that's for another post -

Fire it up

So I've started this blog to track progress and explore ideas for the game I'm building: Platform Hack.

Platform Hack is a combination platform-jumper / rogue-like (NetHack)

The game is being built in XNA 4.0 using a heavily modified Platformer starter kit. I'll also be using some open source maze generation algorithms that come from Angband and other rougelikes.

The "engine" was already used for a simple game I released called Zombie Bash, which was basically an experiment to figure out the collision detection and intricacies of drawing / displaying assets in XNA.

There's still a lot to go, and the next few blogs will go over the goals I have for the game, as well as some challenges of building it -