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

enum GravityEngine.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
priority	lower runs first

GetAlgorithmName()

static string GravityEngine.GetAlgorithmName ( Algorithm  algorithm )

static

Gets the name of the algorithm as a string.

Returns

The algorithm name.

Parameters

algorithm

Algorithm.

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

algorithm

Algorithm.

SetEvolve()

void GravityEngine.SetEvolve

(

bool

evolve

)

Control evolution of masses and particles in the gravity engine.

Parameters

evolve

If 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:

• C:/Users/musgr/Documents/Unity/gravityengine/Assets/GravityEngine/Scripts/Engine/GravityEngine.cs