OpenFairway Physics

Realistic golf ball physics engine for Godot 4.5+ (.NET/C#). Provides force, torque, bounce, and surface interaction calculations usable from both C# and GDScript.

Github

• Do not ever commit code.

Features

• Aerodynamic drag and Magnus lift from wind-tunnel polynomial fits
• Bounce model with spin-dependent COR and tangential retention (Penner)
• Surface presets for fairway, rough, soft, and firm conditions
• Spin-based ground friction with "check up" behavior for high-spin shots
• Launch monitor spin parsing (BackSpin/SideSpin or TotalSpin/SpinAxis)
• Headless shot simulation via PhysicsAdapter — no scene tree required

Requirements

• Godot 4.5+ with .NET support
• .NET 8.0 SDK (or later)

GDScript projects can use this addon — Godot's cross-language scripting handles the interop automatically, but the .NET editor build is required.

Installation

1. Copy addons/openfairway/ into your project's addons/ directory.
2. Ensure your project has a C# solution. If you don't have a .csproj/.sln yet, generate them via Project > Tools > C# > Create C# Solution in the Godot editor. Alternatively, create any temporary C# script (Node > Attach Script > Language: C#) and Godot will generate both files automatically.
3. Build your project: Build > Build Project in the editor (Alt+B), or dotnet build YourProject.csproj from the command line.
4. Enable the plugin: Project > Project Settings > Plugins > OpenFairway Physics.

Quick Start

C#

var bp = new BallPhysics();
var aero = new Aerodynamics();

var p = new PhysicsParams(
    airDensity: aero.GetAirDensity(0f, 75f, PhysicsEnums.Units.Imperial),
    airViscosity: aero.GetDynamicViscosity(75f, PhysicsEnums.Units.Imperial),
    dragScale: 1f, liftScale: 1f,
    kineticFriction: 0.30f, rollingFriction: 0.030f,
    grassViscosity: 0.001f, criticalAngle: 0.25f,
    floorNormal: Vector3.Up);

Vector3 force = bp.CalculateForces(velocity, omega, onGround, p);
Vector3 torque = bp.CalculateTorques(velocity, omega, onGround, p);

GDScript

var physics = BallPhysics.new()
var aero = Aerodynamics.new()

var params = PhysicsParams.new()
params.air_density = aero.get_air_density(0.0, 75.0, PhysicsEnums.Units.Imperial)
params.air_viscosity = aero.get_dynamic_viscosity(75.0, PhysicsEnums.Units.Imperial)
params.drag_scale = 1.0
params.lift_scale = 1.0
params.floor_normal = Vector3.UP

var force = physics.calculate_forces(velocity, omega, false, params)

Headless Simulation

Run a full shot with no scene tree:

var adapter = new PhysicsAdapter();
var result = adapter.SimulateShotFromJson(new Godot.Collections.Dictionary
{
    ["BallData"] = new Godot.Collections.Dictionary
    {
        ["Speed"] = 150.0,       // mph
        ["VLA"] = 12.5,          // degrees
        ["HLA"] = 0.0,           // degrees
        ["TotalSpin"] = 2800,    // RPM
        ["SpinAxis"] = 0.0       // degrees
    }
});
// result["carry_yd"], result["total_yd"]

Distance Benchmarks

Run all 9 test shots headlessly and produce a carry/total/rollout distance table:

godot --headless --script run_benchmarks.gd

This is the standard way to validate physics changes. See tests/PhysicsTests/README.md for baseline distances and the full testing workflow.

Addon Classes

All C# classes use [GlobalClass] for GDScript visibility. Enums are provided via physics_enums.gd (GDScript mirror of the C# PhysicsEnums definitions).

Addon Structure

addons/openfairway/
├── plugin.cfg            Godot plugin metadata
├── plugin.gd             Plugin entry point
├── physics_enums.gd      GDScript enum mirror (BallState, Units, SurfaceType)
├── LICENSE               MIT license
├── README.md             Full GDScript API reference and examples
└── physics/
    ├── BallPhysics.cs    Force/torque/bounce calculations
    ├── PhysicsParams.cs  Physics parameters (Resource, exported)
    ├── BounceResult.cs   Bounce result data
    ├── Aerodynamics.cs   Cd/Cl coefficients, air properties
    ├── Surface.cs        Surface parameter presets
    ├── ShotSetup.cs      Spin parsing & launch vector utilities
    ├── PhysicsAdapter.cs Headless shot simulator
    ├── PhysicsEnums.cs   C# enum definitions (static class)
    └── README.md         Physics formulas and tuning guide

Documentation

• Addon README — full GDScript API reference, installation details, complete physics loop and headless simulation examples
• Physics README — force/torque formulas, bounce model, aerodynamic coefficients, unit conversions, tuning guide, and references

Units Convention

The physics engine always uses SI internally (meters, m/s, rad/s). Launch monitor input uses Imperial (mph, degrees, RPM). Display conversion is the consumer's responsibility. See ShotSetup.BuildLaunchVectors() for the standard conversion path.

License

MIT — see LICENSE.