---
title: "Apply local gravity zones in 3D physics with C#"
url: https://recursiveai.org/onephysics/cookbook/apply-local-gravity-zones/
description: "Replace world gravity inside a 3D box with OnePhysics. See how the highest priority wins and how equal-priority gravity vectors blend."
version: "1.0.0"
---

# Apply local gravity zones in 3D physics with C#

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

[NuGet](https://www.nuget.org/packages/RecursiveAI.OnePhysics) · [GitHub](https://github.com/recursive-ai-oss/onephysics-csharp) · [Docs](https://recursiveai.org/onephysics/docs/) · [Download example (.zip)](https://recursiveai.org/onephysics/cookbook/apply-local-gravity-zones/apply-local-gravity-zones.zip)

Change which way objects fall inside a 3D box without changing gravity elsewhere.

```shell
dotnet add package RecursiveAI.OnePhysics
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
using RecursiveAI.OnePhysics.Physics3D;
var world = new PhysicsWorld3D();
world.AddGravityZone(new(2, 0, 0),
    new(-2, -2, -2), new(2, 2, 2));
var ball = world.AddSphere(0.1f);
world.Step(0.1f);
var vx = ball.LinearVelocity.X;
Console.WriteLine(FormattableString.Invariant(
    $"X velocity: {vx:F2} m/s"));
```

Unzip [the example](https://recursiveai.org/onephysics/cookbook/apply-local-gravity-zones/apply-local-gravity-zones.zip), then `dotnet run`.

`AddSphere` places the sphere at the origin, inside the zone’s box. The sphere starts at rest and picks up velocity along X. The snippet prints:

```text
X velocity: 0.20 m/s
```

## The full program

The program starts a fresh sphere at the origin for each run. The first run has only world gravity `(0, -10, 0)`. The other two put the sphere in three coincident boxes. One pulls at `100` m/s² along X at priority 0, another at `2` at priority 1, and the third at `6`, with either priority 0 or 1. The program prints velocity after the same `0.1`-second step.

```csharp
using RecursiveAI.OnePhysics.Physics3D;
using RecursiveAI.OneMath;
using System.Globalization;

CultureInfo.CurrentCulture = CultureInfo.InvariantCulture;
PrintVelocity("No zones", null);
PrintVelocity("Higher priority overrides", 0);
PrintVelocity("Equal priorities blend", 1);

static void PrintVelocity(string label, int? secondPriority)
{
    var world = new PhysicsWorld3D(new() { Gravity = new(0, -10, 0) });
    var ball = world.AddSphere(0.1f);
    var min = new Vector3D(-2, -2, -2);
    var max = new Vector3D(2, 2, 2);
    if (secondPriority is int priority)
    {
        world.AddGravityZone(new(100, 0, 0), min, max);
        world.AddGravityZone(new(2, 0, 0), min, max, priority: 1, weight: 1);
        world.AddGravityZone(new(6, 0, 0), min, max, priority: priority, weight: 3);
    }
    world.Step(0.1f);
    var velocity = ball.LinearVelocity;
    Console.WriteLine($"{label}: ({velocity.X:F2}, {velocity.Y:F2}, {velocity.Z:F2}) m/s");
}
```

`dotnet run` prints:

```text
No zones: (0.00, -1.00, 0.00) m/s
Higher priority overrides: (0.20, 0.00, 0.00) m/s
Equal priorities blend: (0.50, 0.00, 0.00) m/s
```

The middle run uses just the `2` m/s² vector. The last run blends `2` and `6` in a `1:3` ratio, producing `5` m/s². Both runs have zero Y velocity: the zone replaces world gravity rather than adding to it. If an object still falls under world gravity, check that its center of mass is inside the box, not just that its collider touches the box.

## Variations

**Use a weightless room.** Replace the `AddGravityZone` call in the snippet at the top with a zero vector. World gravity stays enabled outside the room:

```csharp
world.AddGravityZone(new(0, 0, 0),
    new(-2, -2, -2), new(2, 2, 2));
```

```text
X velocity: 0.00 m/s
```

## Related recipes

- [Start a 3D physics world](https://recursiveai.org/onephysics/cookbook/3d-preview/)
- [Simulate buoyancy](https://recursiveai.org/onephysics/cookbook/simulate-buoyancy/)

## The short answer

Use `AddGravityZone` to assign a gravity vector to a box in a `PhysicsWorld3D`. `AddGravityZone` only takes axis-aligned boxes: the [region check](https://github.com/recursive-ai-oss/onephysics-csharp/blob/11dad30ed91fae25354edb55930c67cc0f71fe25/src/OnePhysics/Fields/FieldStore.cs#L124-L128) compares each coordinate to its own minimum and maximum, starting with `p.X >= d.Minimum.X && p.X <= d.Maximum.X`. The vector is an acceleration in meters per second squared, not a direction that the library normalizes. For example, `(2, 0, 0)` makes a body fall along positive X at `2` m/s² while it matches the zone.

## How do you create a local gravity area in 3D?

Leave a default gravity vector on the world and override it in the room or corridor that needs different gravity. The box is a field, not a wall: the example adds no collider for the box itself. Put the sphere’s center of mass inside the bounds for the field to apply. The [field specification](https://github.com/recursive-ai-oss/onephysics-csharp/blob/11dad30ed91fae25354edb55930c67cc0f71fe25/docs/spec/fields.md#L19-L25) says, “A region includes its minimum and maximum. Selection is by body centre of mass, not its shape bounds.” If a large object crosses the edge, judge the transition by where its center is, not when its nose touches the boundary.

A gravity zone changes acceleration, not the velocity the sphere already has. The example starts at rest to isolate what the zone does in one step. A sphere that enters the sideways zone already falling downward still has that downward velocity when the zone starts accelerating it sideways. Gravity scale on the body also still applies, so check the body setting if the effect is weaker than expected.

## What happens when gravity zones overlap?

The [3D API comment](https://github.com/recursive-ai-oss/onephysics-csharp/blob/11dad30ed91fae25354edb55930c67cc0f71fe25/src/OnePhysics/Physics3D/PhysicsWorld3D.Fields.cs#L19-L20) says, “Highest priority wins; equal highest priorities blend with normalized positive weights.” Use a higher priority when one room must override the other completely. Strength is not priority: the `100` m/s² vector in the example never enters the blend, even though it’s the largest.

To blend two zones, give them the same priority and choose their relative weights. The last run takes `(1 × 2 + 3 × 6) ÷ (1 + 3)`, giving `5` m/s². Weights control the average only where the zones both match. They don’t create a gradual fade at a box edge: if one stops matching, the other supplies its full vector. Decide whether you want a hard switch or a weighted overlap before setting up the boxes.
