physics-and-movement

Physics and Movement in FlatRedBall2

Coordinate System

Y+ is UP. This is the opposite of screen-space pixels.

• A value of Y = 100 places an entity above center.
• Gravity is a negative AccelerationY.
• The camera applies a Y-flip when converting world → screen, so everything renders correctly.

Physics Properties on Entity

entity.X           // world position (Y+ up)
entity.Y
entity.VelocityX   // units per second
entity.VelocityY
entity.AccelerationX  // units per second²
entity.AccelerationY
entity.Drag        // fraction of velocity removed per second (0 = no drag)

Gravity Pattern

Set a negative AccelerationY to simulate gravity. Spawn the entity with a positive Y so it has room to fall:

public class Ball : Entity
{
    public override void CustomInitialize()
    {
        var circle = new Circle { Radius = 8f, IsVisible = true };
        Add(circle);

        AccelerationY = -200f;   // gravity pulls downward (Y- direction)
    }
}

// At spawn time:
var ball = _ballFactory.Create();
ball.X = 0f;
ball.Y = Engine.Random.Between(50f, 150f);            // start above the floor
ball.VelocityX = Engine.Random.Between(-150f, 150f);  // random horizontal launch

Kinematic Formula (Second-Order)

Each frame, PhysicsUpdate applies:

position += velocity * dt + acceleration * (dt² / 2)
velocity += acceleration * dt
velocity -= velocity * drag * dt

This is second-order (Verlet-style), so acceleration is smoothly integrated even at low frame rates.

Drag

Drag is a multiplier applied to velocity each frame:

entity.Drag = 1f;   // removes 100% of velocity per second (stops fast)
entity.Drag = 0.5f; // removes 50% per second (gentle air resistance)
entity.Drag = 0f;   // no drag (default)

Drag does not affect acceleration — only velocity. A falling entity with drag will reach terminal velocity when gravity equals drag deceleration.

Update Order Each Frame

See engine-overview for the full 8-step frame loop. The key point: Physics → Collision → CustomActivity — game logic sees already-corrected positions.