Move a capsule through solid geometry and check whether it is grounded. Move takes a displacement; you supply gravity and jumping.
dotnet add package RecursiveAI.OnePhysicsRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
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.
OnGroundUnzip 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.
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:
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.
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:
Step offset: 0.0 Z: 2.694 Blocked before step: True OnGround
Related recipes
- Configure physics simulation level of detail in C#
- Simulate a ragdoll in C#
- Simulate shallow water in C#
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.