| | | 1 | | //======================================================================= |
| | | 2 | | // PhysicsEnvironment.cs |
| | | 3 | | //======================================================================= |
| | | 4 | | // MIT License, Copyright (c) 2026-present David Oravsky (mrdav30) |
| | | 5 | | // See LICENSE file in the project root for full license information. |
| | | 6 | | //======================================================================= |
| | | 7 | | |
| | | 8 | | using FixedMathSharp; |
| | | 9 | | |
| | | 10 | | namespace Gravitas; |
| | | 11 | | |
| | | 12 | | /// <summary> |
| | | 13 | | /// Stores world-local physical environment values used by deterministic simulation. |
| | | 14 | | /// </summary> |
| | | 15 | | /// <content>Defines physical coefficients, speed limits and collision-culling defaults.</content> |
| | | 16 | | public sealed partial class PhysicsEnvironment |
| | | 17 | | { |
| | | 18 | | /// <summary> |
| | | 19 | | /// Standard gravitational acceleration in world units per second squared. |
| | | 20 | | /// </summary> |
| | 1 | 21 | | public static readonly Fixed64 DefaultGravity = (Fixed64)9.8f; |
| | | 22 | | |
| | | 23 | | /// <summary> |
| | | 24 | | /// Standard air density used by drag calculations. |
| | | 25 | | /// </summary> |
| | 1 | 26 | | public static readonly Fixed64 DefaultAirDensity = (Fixed64)1.225f; |
| | | 27 | | |
| | | 28 | | /// <summary> |
| | | 29 | | /// Minimum speed treated as meaningful motion by the standard environment. |
| | | 30 | | /// </summary> |
| | 1 | 31 | | public static readonly Fixed64 DefaultMinSpeed = (Fixed64)0.00001f; |
| | | 32 | | |
| | | 33 | | /// <summary> |
| | | 34 | | /// Maximum linear or angular speed used by the standard environment. |
| | | 35 | | /// </summary> |
| | 1 | 36 | | public static readonly Fixed64 DefaultMaxSpeed = (Fixed64)7f; |
| | | 37 | | |
| | | 38 | | /// <summary> |
| | | 39 | | /// Maximum downward fall speed used by the standard environment. |
| | | 40 | | /// </summary> |
| | 1 | 41 | | public static readonly Fixed64 DefaultMaxFallSpeed = DefaultGravity; |
| | | 42 | | |
| | | 43 | | /// <summary> |
| | | 44 | | /// Speed threshold used when transitioning friction behavior in the standard environment. |
| | | 45 | | /// </summary> |
| | 1 | 46 | | public static readonly Fixed64 DefaultFrictionTransitionSpeed = (Fixed64)0.2f; |
| | | 47 | | |
| | | 48 | | /// <summary> |
| | | 49 | | /// Motion deceleration multiplier used by the standard environment. |
| | | 50 | | /// </summary> |
| | 1 | 51 | | public static readonly Fixed64 DefaultDecelerationMultiplier = (Fixed64)10f; |
| | | 52 | | |
| | | 53 | | /// <summary> |
| | | 54 | | /// Angular damping torque coefficient used by the standard environment. |
| | | 55 | | /// </summary> |
| | 1 | 56 | | public static readonly Fixed64 DefaultDampingFactor = (Fixed64)0.95f; |
| | | 57 | | |
| | | 58 | | /// <summary> |
| | | 59 | | /// Frame-rate divisor used to derive the default maximum distance-based |
| | | 60 | | /// collision-culling score. |
| | | 61 | | /// </summary> |
| | 1 | 62 | | public static readonly int DefaultCullDistanceFrameDivisor = 3; |
| | | 63 | | |
| | | 64 | | /// <summary> |
| | | 65 | | /// Distance threshold whose square becomes the default fast-collision |
| | | 66 | | /// preservation threshold. |
| | | 67 | | /// </summary> |
| | 1 | 68 | | public static readonly int DefaultCullFastDistance = 4; |
| | | 69 | | |
| | | 70 | | /// <summary> |
| | | 71 | | /// Squared distance below which the standard environment preserves fast |
| | | 72 | | /// collision checks. |
| | | 73 | | /// </summary> |
| | 1 | 74 | | public static readonly Fixed64 DefaultCullFastDistanceMax = |
| | 1 | 75 | | Fixed64.One * DefaultCullFastDistance * (Fixed64.One * DefaultCullFastDistance); |
| | | 76 | | |
| | | 77 | | /// <summary> |
| | | 78 | | /// Velocity step used by standard collision culling. |
| | | 79 | | /// </summary> |
| | 1 | 80 | | public static readonly int DefaultCullVelocityStep = 2; |
| | | 81 | | |
| | | 82 | | /// <summary> |
| | | 83 | | /// Maximum velocity-based collision-culling score used by the standard environment. |
| | | 84 | | /// </summary> |
| | 1 | 85 | | public static readonly int DefaultCullVelocityMax = 4; |
| | | 86 | | |
| | | 87 | | /// <summary> |
| | | 88 | | /// Frame-rate multiplier used to derive the default collision-culling time step. |
| | | 89 | | /// </summary> |
| | 1 | 90 | | public static readonly int DefaultCullTimeStepFrameMultiplier = 3; |
| | | 91 | | |
| | | 92 | | /// <summary> |
| | | 93 | | /// Frame-rate divisor used to derive the default maximum time-based |
| | | 94 | | /// collision-culling score. |
| | | 95 | | /// </summary> |
| | 1 | 96 | | public static readonly int DefaultCullTimeMaxFrameDivisor = 5; |
| | | 97 | | |
| | | 98 | | /// <summary> |
| | | 99 | | /// One pound is equal to this many Newtons. |
| | | 100 | | /// </summary> |
| | 1 | 101 | | public static readonly Fixed64 PoundToNewton = (Fixed64)4.44822162f; |
| | | 102 | | |
| | | 103 | | /// <summary> |
| | | 104 | | /// One kilogram is equal to this many pounds. |
| | | 105 | | /// </summary> |
| | 1 | 106 | | public static readonly Fixed64 KilogramToPound = (Fixed64)2.20462262f; |
| | | 107 | | |
| | | 108 | | /// <summary> |
| | | 109 | | /// Gets or sets gravitational acceleration in world units per second squared. |
| | | 110 | | /// </summary> |
| | | 111 | | public Fixed64 Gravity { get; set; } |
| | | 112 | | |
| | | 113 | | /// <summary> |
| | | 114 | | /// Gets or sets air density used by drag calculations. |
| | | 115 | | /// </summary> |
| | | 116 | | public Fixed64 AirDensity { get; set; } |
| | | 117 | | |
| | | 118 | | /// <summary> |
| | | 119 | | /// Gets or sets the minimum speed treated as meaningful motion. |
| | | 120 | | /// </summary> |
| | | 121 | | public Fixed64 MinSpeed { get; set; } |
| | | 122 | | |
| | | 123 | | /// <summary> |
| | | 124 | | /// Gets or sets the maximum linear or angular speed. |
| | | 125 | | /// </summary> |
| | | 126 | | public Fixed64 MaxSpeed { get; set; } |
| | | 127 | | |
| | | 128 | | /// <summary> |
| | | 129 | | /// Gets or sets the maximum downward fall speed. |
| | | 130 | | /// </summary> |
| | | 131 | | public Fixed64 MaxFallSpeed { get; set; } |
| | | 132 | | |
| | | 133 | | /// <summary> |
| | | 134 | | /// Gets or sets the speed threshold used when transitioning friction behavior. |
| | | 135 | | /// </summary> |
| | | 136 | | public Fixed64 FrictionTransitionSpeed { get; set; } |
| | | 137 | | |
| | | 138 | | /// <summary> |
| | | 139 | | /// Gets or sets the multiplier applied when decelerating motion. |
| | | 140 | | /// </summary> |
| | | 141 | | public Fixed64 DecelerationMultiplier { get; set; } |
| | | 142 | | |
| | | 143 | | /// <summary> |
| | | 144 | | /// Gets or sets the opposing torque per unit angular velocity. This is not a |
| | | 145 | | /// per-frame retention factor: the body's inertia determines the response, |
| | | 146 | | /// bounded at the kinetic-energy minimum for nonnegative damping. |
| | | 147 | | /// </summary> |
| | | 148 | | public Fixed64 DampingFactor { get; set; } |
| | | 149 | | |
| | | 150 | | /// <summary> |
| | | 151 | | /// Gets or sets the maximum distance-based collision-culling score. |
| | | 152 | | /// </summary> |
| | | 153 | | public int CullDistanceMax { get; set; } |
| | | 154 | | |
| | | 155 | | /// <summary> |
| | | 156 | | /// Gets or sets the squared distance below which fast collision checks are preserved. |
| | | 157 | | /// </summary> |
| | | 158 | | public Fixed64 CullFastDistanceMax { get; set; } |
| | | 159 | | |
| | | 160 | | /// <summary> |
| | | 161 | | /// Gets or sets the velocity step used by collision culling. |
| | | 162 | | /// </summary> |
| | | 163 | | public int CullVelocityStep { get; set; } |
| | | 164 | | |
| | | 165 | | /// <summary> |
| | | 166 | | /// Gets or sets the maximum velocity-based collision-culling score. |
| | | 167 | | /// </summary> |
| | | 168 | | public int CullVelocityMax { get; set; } |
| | | 169 | | |
| | | 170 | | /// <summary> |
| | | 171 | | /// Gets or sets the frame-count step used by collision culling. |
| | | 172 | | /// </summary> |
| | | 173 | | public int CullTimeStep { get; set; } |
| | | 174 | | |
| | | 175 | | /// <summary> |
| | | 176 | | /// Gets or sets the maximum time-based collision-culling score. |
| | | 177 | | /// </summary> |
| | | 178 | | public int CullTimeMax { get; set; } |
| | | 179 | | |
| | | 180 | | /// <summary> |
| | | 181 | | /// Initializes a new environment with explicit physical and culling values. |
| | | 182 | | /// </summary> |
| | 10192 | 183 | | public PhysicsEnvironment( |
| | 10192 | 184 | | Fixed64 gravity, |
| | 10192 | 185 | | Fixed64 airDensity, |
| | 10192 | 186 | | Fixed64 minSpeed, |
| | 10192 | 187 | | Fixed64 maxSpeed, |
| | 10192 | 188 | | Fixed64 maxFallSpeed, |
| | 10192 | 189 | | Fixed64 frictionTransitionSpeed, |
| | 10192 | 190 | | Fixed64 decelerationMultiplier, |
| | 10192 | 191 | | Fixed64 dampingFactor, |
| | 10192 | 192 | | int cullDistanceMax, |
| | 10192 | 193 | | Fixed64 cullFastDistanceMax, |
| | 10192 | 194 | | int cullVelocityStep, |
| | 10192 | 195 | | int cullVelocityMax, |
| | 10192 | 196 | | int cullTimeStep, |
| | 10192 | 197 | | int cullTimeMax) |
| | | 198 | | { |
| | 10192 | 199 | | Gravity = gravity; |
| | 10192 | 200 | | AirDensity = airDensity; |
| | 10192 | 201 | | MinSpeed = minSpeed; |
| | 10192 | 202 | | MaxSpeed = maxSpeed; |
| | 10192 | 203 | | MaxFallSpeed = maxFallSpeed; |
| | 10192 | 204 | | FrictionTransitionSpeed = frictionTransitionSpeed; |
| | 10192 | 205 | | DecelerationMultiplier = decelerationMultiplier; |
| | 10192 | 206 | | DampingFactor = dampingFactor; |
| | 10192 | 207 | | CullDistanceMax = cullDistanceMax; |
| | 10192 | 208 | | CullFastDistanceMax = cullFastDistanceMax; |
| | 10192 | 209 | | CullVelocityStep = cullVelocityStep; |
| | 10192 | 210 | | CullVelocityMax = cullVelocityMax; |
| | 10192 | 211 | | CullTimeStep = cullTimeStep; |
| | 10192 | 212 | | CullTimeMax = cullTimeMax; |
| | 10192 | 213 | | } |
| | | 214 | | |
| | | 215 | | /// <summary> |
| | | 216 | | /// Creates environment values for the standard Gravitas runtime defaults. |
| | | 217 | | /// </summary> |
| | | 218 | | /// <param name="frameRate">Frame rate used to initialize frame-derived culling thresholds.</param> |
| | | 219 | | /// <returns>A new environment instance.</returns> |
| | | 220 | | public static PhysicsEnvironment Default(int frameRate = PhysicsSettings.DefaultFrameRate) |
| | | 221 | | { |
| | 10193 | 222 | | PhysicsSettings.ThrowIfInvalidFrameRate(frameRate); |
| | | 223 | | |
| | 10192 | 224 | | return new PhysicsEnvironment( |
| | 10192 | 225 | | gravity: DefaultGravity, |
| | 10192 | 226 | | airDensity: DefaultAirDensity, |
| | 10192 | 227 | | minSpeed: DefaultMinSpeed, |
| | 10192 | 228 | | maxSpeed: DefaultMaxSpeed, |
| | 10192 | 229 | | maxFallSpeed: DefaultMaxFallSpeed, |
| | 10192 | 230 | | frictionTransitionSpeed: DefaultFrictionTransitionSpeed, |
| | 10192 | 231 | | decelerationMultiplier: DefaultDecelerationMultiplier, |
| | 10192 | 232 | | dampingFactor: DefaultDampingFactor, |
| | 10192 | 233 | | cullDistanceMax: frameRate / DefaultCullDistanceFrameDivisor, |
| | 10192 | 234 | | cullFastDistanceMax: DefaultCullFastDistanceMax, |
| | 10192 | 235 | | cullVelocityStep: DefaultCullVelocityStep, |
| | 10192 | 236 | | cullVelocityMax: DefaultCullVelocityMax, |
| | 10192 | 237 | | cullTimeStep: frameRate * DefaultCullTimeStepFrameMultiplier, |
| | 10192 | 238 | | cullTimeMax: frameRate / DefaultCullTimeMaxFrameDivisor); |
| | | 239 | | } |
| | | 240 | | } |