Gravity Engine 12.0
Unity Asset for Gravity
Loading...
Searching...
No Matches
GravityEngine Class Reference

GravityEngine Primary controller of Nbody physics evolution with selectable integration algorithms. Singleton. More...

Inheritance diagram for GravityEngine:

Classes

class  EngineRef
 
class  FixedBody
 
class  GEStartListEntry
 

Public Types

enum  UpdateMode { FIXED_UPDATE , FIXED_INTERPOLATE , UPDATE }
 GE allows for different modes that control when and how the game object transforms are updated: FIXED_UPDATE: Run physics and updates on the FixedUpdate call. FIXED_INTERPOLATE: Run physics on FixedUpdate and update positions on Update using linear interpolation UPDATE: Run physics and positions on the Update loop. More...
 
enum  Algorithm { LEAPFROG , HERMITE8 , AZTRIPLE }
 Integrator choices: LEAPFROG - a fixed timestep, with good energy conservation HERMITE - an adaptive timestep algorithm with excellent energy conservation AZTRIPLE - For 3 bodies ONLY. Works in regularized co-ordinates that allow close encounters. ANY_FORCE_FL - Leapfrog with a force delegate.
 
enum  BodyType { MASSIVE , MASSLESS , FIXED }
 NBody type - used in integrator code.
 

Public Member Functions

delegate void GEStart ()
 
void UnitTestAwake ()
 Unit test call in to wake up GE (since Awake is not directly callable due to protection level)
 
void SetEvolve (bool evolve)
 Control evolution of masses and particles in the gravity engine.
 
bool GetEvolve ()
 
void SetAlgorithm (Algorithm algorithm)
 Sets the integration algorithm used for massive bodies.
 
IForceDelegate GetForceDelegate ()
 
double GetParticleDt ()
 Gets the particle time step size.
 
void Clear ()
 Reset the bodies/particle systems known to the Gravity Engine.
 
void Setup ()
 
void AddGEStartCallback (GEStart callback)
 Scripts may wish to do some setup in the Start() method but GE is not yet running at scene start. This is a method to register code to run once GE setup has been completed.
 
void AddGEStartCallback (GEStart callback, int priority)
 Add code to be run once GE has started with an expicit priority. Lower priority methods are run first.
 
bool IsSetup ()
 
Vector3 MapToScene (Vector3 pos)
 
Vector3 UnmapFromScene (Vector3 pos)
 
GravityState GetGravityStateCopy ()
 Return a clone of the current world state.
 
void TrajectoryRestart ()
 

Static Public Member Functions

static GravityEngine Instance ()
 Static accessor that finds Instance. Useful for Editor scripts.
 
static string GetAlgorithmName (Algorithm algorithm)
 Gets the name of the algorithm as a string.
 

Public Attributes

bool useTransform = false
 Use the transform to reposition the scene via MapToScene and the transform value. Setting this will also enable mapToScene.
 
bool mapToScene = false
 Map To Scene Commonly, GE is used as a world controller and there is simple mapping from the physics space to the scene. In this case leave MapToScene false to avoid extra calculations on each update.
 
GameObject mapToSceneGameObject
 Class to be used to delegate the final mapping to the scene. Can be used in cases when a non-linear mapping is desired and the simpler useTransformm to map is not able to give the desired result.
 
GameObject multiplayerInterfaceGO
 Class that implements the multiplayer abstract class. (Can't be an interface since they are not supported in the inspector).
 
GEMultiplayerInterface geMultiplayerIF
 
bool xzOrbits
 Set orbits to be in XZ plane. OrbitUniversal will use this in positioning objects and determining the orbital elements when using orbit predictors. This option is useful for aligning Unity's standard scene view in the editor with the planes of orbits (which are always in XY by default in the physics literature) /summary>
 
UpdateMode updateMode = UpdateMode.FIXED_UPDATE
 
bool setCenterOfMass = false
 On startup set the center of mass (CM) to the specified position and velocity. This is commonly used to null out residial CM velocity rates on scene startup when massive planets are being used and when anchoring the center with a FixedObject is not desired.
 
Vector3 cmPosition = Vector3.zero
 
Vector3 cmVelocity = Vector3.zero
 
int orbitPredictorInterval = 1
 Interval (in Updates) at which NBody (non-Kepler) will run their OrbitPredictors. Orbit predictors in large N scenarios can use a lot of CPU and dominate the max N when updated every frame.
 
bool orbitPredictorKeplerOpt = false
 
ForceChooser.Forces force
 The force used when one of the ANY_FORCE integrators is selected. Any force use requires that the scale be set to DIMENSIONLESS.
 
Algorithm algorithm
 Algorithm for numerical integration of massive bodies.
 
bool detectNbodies = true
 Automatically detect all objects with an NBody component and add to the engine.
 
bool trajectoryPrediction = false
 Enable trajectory prediction - TrajectoryTrails attached to NBody objects will be updated.
 
float trajectoryTime = 15f
 time to evolve forward for trajectory prediction
 
float trajectoryDataTimeDistance = 0.1f
 min distance allowed between record data points
 
GameObject trajectoryCanvas
 Used by Trajectory when text labels for time are enabled.
 
GameObject markerParent
 Optional parent object to assign trajectory markers to (so they do not clutter up the root object space)
 
float trajectoryComputeFactor = 4f
 
float physToWorldFactor = 1.0f
 physToWorldFactor: factor to allow distance measurements in NBE to be on a different scale than in the Unity world view. This is useful when taking initial conditions from literature (e.g. the three body solutions) in which the data provided are normalized to [-1..1]. Having all world objects in [-1..1] becomes awkward. Setting this scale allows the Unity positions to be expanded to a more convenient range.
 
GravityScaler.Units units
 
float massScale = 1.0f
 Mass scale applied to all NBody objects handled by the Gravity Engine. Increasing mass scale makes everything move faster for the same CPU cost.
 
GameObject[] bodies
 Array of game objects to be controlled by the engine at start (used when detectNbodies=false). During evolution use AddBody().
 
bool evolveAtStart = true
 Begin gravitational evolution when the scene starts.
 
bool editorShowAdvanced
 State of inspector Advanced foldout.
 
bool editorShowScale
 State of inspector Scale foldout.
 
bool editorShowScaleDetails
 State of scale details.
 
bool editorCMfoldout
 State of inspector Center of Mass foldout.
 
bool editorShowTrajectory
 Track state of foldout in editor.
 
bool editorShowStartTime
 
int startTimeYear = 2020
 
int startTimeMonth = 1
 
int startTimeDay = 1
 
double startTimeTimeOfDayUTC = 0.0
 
bool rewindModeEnabled = false
 flag to record events for rewind
 
int stepsPerFrame = 8
 
int particleStepsPerFrame = 2
 
double engineDt = 1.0/(PHYSICS_FPS * 8)
 

Static Public Attributes

static string TAG = "GravityEngine"
 
static GravityEngine instance
 Singleton instance handle. Initialized during Awake().
 
const bool DEBUG = true
 global flag for debug logging789
 
const byte INACTIVE = 1
 Bit flag used in integrator code.
 
const byte FIXED_MOTION = 1 << 1
 Bit flag used in integrator code.
 
const byte TRAJ_DATA = 1 << 2
 
const byte INACTIVE_OR_FIXED = GravityEngine.FIXED_MOTION | GravityEngine.INACTIVE
 

Properties

float lengthScale [get, set]
 Orbital scale in e.g. Unity unity per km.
 
float timeScale [get, set]
 Orbital scale in Unity unity per AU.
 

Detailed Description

GravityEngine Primary controller of Nbody physics evolution with selectable integration algorithms. Singleton.

Bodies The positions and masses of the N bodes are initialized here and passed by reference to the integrator. This allows high precision evolution of the bodies and a simpler integration scheme for particle systems moving in the fields of the N bodies.

Particles GE creates a ParticleEvolver and evolves particle systems once per fixed update based on new positions of the N bodies. Particles are massless and so do not interact with each other (too computationally expensive).

Member Enumeration Documentation

◆ UpdateMode

GE allows for different modes that control when and how the game object transforms are updated: FIXED_UPDATE: Run physics and updates on the FixedUpdate call. FIXED_INTERPOLATE: Run physics on FixedUpdate and update positions on Update using linear interpolation UPDATE: Run physics and positions on the Update loop.

Running physics on the fixed update ensures consistent CPU load spreading. In some cases there may be object jittering when mixing rigidbody objects and GE objects in the same scene at small scales. In this case using interpolation or moving to UPDATE mode will improve this situation.

Member Function Documentation

◆ AddGEStartCallback() [1/2]

void GravityEngine.AddGEStartCallback ( GEStart  callback)

Scripts may wish to do some setup in the Start() method but GE is not yet running at scene start. This is a method to register code to run once GE setup has been completed.

If GE is already running, just go ahead and do the callback now.

Parameters
callback

◆ AddGEStartCallback() [2/2]

void GravityEngine.AddGEStartCallback ( GEStart  callback,
int  priority 
)

Add code to be run once GE has started with an expicit priority. Lower priority methods are run first.

If GE is running run the callback immediatly.

Parameters
callback
prioritylower runs first

◆ GetAlgorithmName()

static string GravityEngine.GetAlgorithmName ( Algorithm  algorithm)
static

Gets the name of the algorithm as a string.

Returns
The algorithm name.
Parameters
algorithmAlgorithm.

◆ GetGravityStateCopy()

GravityState GravityEngine.GetGravityStateCopy ( )

Return a clone of the current world state.

This can then be independently evolved as part of e.g. course correction determination

Returns

◆ GetParticleDt()

double GravityEngine.GetParticleDt ( )

Gets the particle time step size.

Returns
The particle dt.

◆ SetAlgorithm()

void GravityEngine.SetAlgorithm ( Algorithm  algorithm)

Sets the integration algorithm used for massive bodies.

The integration algorithm cannot be changed while the engine is running.

Parameters
algorithmAlgorithm.

◆ SetEvolve()

void GravityEngine.SetEvolve ( bool  evolve)

Control evolution of masses and particles in the gravity engine.

Parameters
evolveIf set to true evolve.

Member Data Documentation

◆ mapToScene

bool GravityEngine.mapToScene = false

Map To Scene Commonly, GE is used as a world controller and there is simple mapping from the physics space to the scene. In this case leave MapToScene false to avoid extra calculations on each update.

In applications where GE is supplying information in a scene element (e.g. floating above the navigation console on the bridge of a starship) then it is useful to be able to re-locate, rotate and scale the body positions and to do this dynamically. In this case enable Map To Scene. (Note model scales will not be adjusted - that's up to game logic outside of GE)

Flag to apply GE transform to scale, rotate and re-position all objects under it's control /summary>

◆ mapToSceneGameObject

GameObject GravityEngine.mapToSceneGameObject

Class to be used to delegate the final mapping to the scene. Can be used in cases when a non-linear mapping is desired and the simpler useTransformm to map is not able to give the desired result.

Must implement a Map and Unmap function.

◆ massScale

float GravityEngine.massScale = 1.0f

Mass scale applied to all NBody objects handled by the Gravity Engine. Increasing mass scale makes everything move faster for the same CPU cost.

In dimensionless units the massScale can be set directly in the inspector. In other units, the mass scale is determined by the choice of length and time scale ans computed by UpdateTimeScale in the GravityScalar class.

◆ multiplayerInterfaceGO

GameObject GravityEngine.multiplayerInterfaceGO

Class that implements the multiplayer abstract class. (Can't be an interface since they are not supported in the inspector).

See the base class defintion for details.

◆ orbitPredictorInterval

int GravityEngine.orbitPredictorInterval = 1

Interval (in Updates) at which NBody (non-Kepler) will run their OrbitPredictors. Orbit predictors in large N scenarios can use a lot of CPU and dominate the max N when updated every frame.

Cannot be altered after GE starts (OPs generate a random seed to decide when to update to load balance).

◆ particleStepsPerFrame

int GravityEngine.particleStepsPerFrame = 2

Number of steps per frame for particle evolution. All particle evolution is via LEAPFROG, independent of the choice of algorithm for massive body evolution.

◆ physToWorldFactor

float GravityEngine.physToWorldFactor = 1.0f

physToWorldFactor: factor to allow distance measurements in NBE to be on a different scale than in the Unity world view. This is useful when taking initial conditions from literature (e.g. the three body solutions) in which the data provided are normalized to [-1..1]. Having all world objects in [-1..1] becomes awkward. Setting this scale allows the Unity positions to be expanded to a more convenient range.

If this is used for objects that are created in Unity world space it will change the distance scale used by the physics engine and consequently the time evolution will also change. Moving objects closer (physToWorldFactor > 1) will result in stronger gravity and faster interactions.

◆ setCenterOfMass

bool GravityEngine.setCenterOfMass = false

On startup set the center of mass (CM) to the specified position and velocity. This is commonly used to null out residial CM velocity rates on scene startup when massive planets are being used and when anchoring the center with a FixedObject is not desired.

After startup GE will call a routine to reset the center of mass pos/vel when massive bodies are added or removed.

◆ stepsPerFrame

int GravityEngine.stepsPerFrame = 8

Number of physics steps per frame for massive body evolution. For LEAPFROG will directly map to CPU use and accuracy. In the case of HERMITE, number of iterations per frame will vary depending on speeds of bodies.

◆ trajectoryComputeFactor

float GravityEngine.trajectoryComputeFactor = 4f

Multiplier for trajectory recompute simulations per frame. Low number spread update over more frames and have less impact on run-time performance and the cost of longer times to see new trajectory


The documentation for this class was generated from the following file: