Recursive AI

Move a 3D physics character in C#

OnePhysics is a free, open-source physics library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

Move a capsule through solid geometry and check whether it is grounded. Move takes a displacement; you supply gravity and jumping.

Terminal
dotnet add package RecursiveAI.OnePhysics

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using RecursiveAI.OneMath;
using RecursiveAI.OnePhysics;
using RecursiveAI.OnePhysics.Physics3D;
 
var world = new PhysicsWorld3D();
world.AddBox(new Vector3F(20, 1, 20),
    new Vector3D(0, -0.5, 0),
    type: BodyType.Static);
var player = world.AddCharacter(
    new Vector3D(0, 0.9, 0));
player.Move(new Vector3F(0, -0.1f, 0.05f),
    1f / 60f);
world.Step(1f / 60f);
Console.WriteLine(player.Ground);

Moves the capsule along the floor and prints its ground state.

Text
OnGround

Unzip the example, then dotnet run.

The full program

The full program runs two separate courses: a 0.25-meter step and a ramp rising 3 meters over 6 meters. It supplies horizontal movement and gravity each step, then prints position and ground normal.

C#
using RecursiveAI.OneMath;
using RecursiveAI.OnePhysics;
using RecursiveAI.OnePhysics.Physics3D;
 
RunCourse("Step", false);
RunCourse("Slope", true);
 
static void RunCourse(string name, bool slope)
{
    var world = new PhysicsWorld3D();
    world.AddBox(new Vector3F(40, 1, 40),
        new Vector3D(0, -0.5, 0), type: BodyType.Static);
    if (slope)
    {
        Vector3F[] vertices = [new(-5, 0, 2), new(5, 0, 2),
            new(-5, 3, 8), new(5, 3, 8)];
        world.AddMesh(vertices, [0, 2, 1, 1, 2, 3]);
    }
    else
        world.AddBox(new Vector3F(10, 0.25f, 8),
            new Vector3D(0, 0.125, 7), type: BodyType.Static);
    var player = world.AddCharacter(new Vector3D(0, 0.95, 0));
    const float dt = 1f / 60f;
    float verticalSpeed = 0;
    for (int i = 0; i < 200; i++)
    {
        verticalSpeed = player.IsGrounded && verticalSpeed < 0
            ? -1 : verticalSpeed - 9.81f * dt;
        player.Move(new Vector3F(0, verticalSpeed * dt, 1.5f * dt), dt);
        world.Step(dt);
    }
    Console.WriteLine($"{name}: Z={player.Position.Z:F3}, Y={player.Position.Y:F3}, {player.Ground}");
    Console.WriteLine($"Ground normal Y: {player.GroundNormal.Y:F3}");
}

dotnet run prints:

Text
Step: Z=5.168, Y=1.151, OnGround
Ground normal Y: 1.000
Slope: Z=4.386, Y=2.128, OnGround
Ground normal Y: 0.894

Variations

Turn off step climbing. Append this to the snippet at the top. It adds a 0.25-meter step with its front face at Z = 3, then tries to walk forward with StepOffset set to zero.

C#
world.AddBox(new Vector3F(10, 0.25f, 8),
    new Vector3D(0, 0.125, 7),
    type: BodyType.Static);
player.StepOffset = 0;
const float dt = 1f / 60f;
float verticalSpeed = 0;
for (int i = 0; i < 200; i++)
{
    verticalSpeed = player.IsGrounded && verticalSpeed < 0
        ? -1 : verticalSpeed - 9.81f * dt;
    player.Move(new Vector3F(0, verticalSpeed * dt, 1.5f * dt), dt);
    world.Step(dt);
}
Console.WriteLine($"Step offset: {player.StepOffset:F1}");
Console.WriteLine($"Z: {player.Position.Z:F3}");
Console.WriteLine($"Blocked before step: {player.Position.Z < 3}");
Console.WriteLine(player.Ground);

The added lines print:

Text
Step offset: 0.0
Z: 2.694
Blocked before step: True
OnGround

The short answer

Use PhysicsWorld3D.AddCharacter to create the capsule, then call Character.Move(displacement, dt) before each world step. The default is a virtual character: a kinematic capsule moved by collision casts and sliding. Supply gravity yourself, keep a vertical velocity between steps and read IsGrounded or Ground after moving. This recipe uses OnePhysics directly without a game-framework integration.

How do I make a 3D physics character controller in C#?

The snippet at the top is a complete flat-ground move. The longer program adds two independent obstacle courses so the results are easy to read. One has a step with a top at 0.25 meters. The other is a triangle-mesh ramp rising 3 meters along 6 meters of forward travel. All vertices and indices are shown in the program; no scene file or model is hidden in the download.

Each loop calculates vertical velocity, converts horizontal speed and vertical velocity to displacement by multiplying by dt, calls Move, then advances the world. Move takes a distance for this step, not a speed. Multiplying by dt twice would nearly stop movement; omitting it would move the player an entire second’s distance on every step.

On walkable ground the loop keeps a small downward velocity rather than accumulating falling speed. When unsupported, it subtracts gravity from vertical velocity each tick. A jump would supply an upward velocity in that same host-side state. The virtual mover does not provide an automatic gravity integrator for you.

Ground distinguishes walkable ground from steep ground and air. GroundNormal gives the supporting surface direction. In the output, the step’s Y normal is 1, while the ramp’s is about 0.894. Do not use only the player’s Y position to decide whether it can jump: the same height can occur in a fall or while resting on a surface.

Where can I download a C# 3D character controller example?

The zip above runs both courses as a console application and pins the NuGet package. It has no input bindings or camera: map your own controls to horizontal speed and keep the fixed-step movement loop.

Step heights, slopes and character kinds

The variation disables automatic step climbing with StepOffset set to zero and shows the capsule blocked by the step.

Use StepOffset for the maximum climbable step and SlopeLimitRadians for the maximum walkable incline. These are different constraints. A low vertical obstacle can be climbed by a step-up probe, while a tall ramp can remain walkable over its full length. A steep ramp is not made walkable merely by increasing the step height. The 3D character specification describes the grounding and step probes.

Choose the virtual character when you want the collide-and-slide mover shown here. A rigid character instead uses a dynamic capsule and velocity targets resolved by the solver; it does not climb steps. Both are physics characters, but switching kinds changes the movement contract. Keep that choice separate from rendering and controls. On moving ground the virtual character adds the platform velocity while grounded, so adding that same velocity again in your own displacement would count the platform motion twice.

All onephysics recipes