Gravity Engine  1.5
Unity Asset for Gravity
GravityEngine Class Reference

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

Inheritance diagram for GravityEngine:

Classes

class  EngineRef
 

Public Types

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 More...
 
enum  BodyType { MASSIVE, MASSLESS, FIXED }
 NBody type - used in integrator code.
 

Public Member Functions

void SetEvolve (bool evolve)
 Control evolution of masses and particles in the gravity engine. More...
 
bool GetEvolve ()
 
void SetAlgorithm (Algorithm algorithm)
 Sets the integration algorithm used for massive bodies. More...
 
double GetParticleDt ()
 Gets the particle time step size. More...
 
void Clear ()
 Reset the bodies/particle systems known to the Gravity Engine. More...
 
void Setup ()
 
bool IsSetup ()
 
void TrajectoryRestart ()
 
void SetTrajectoryPrediction (bool newState)
 Sets the trajectory prediction state (enable/disable). On enable, will activate the Trajectory elements and re-run the trajectory prediction code. On disable will de-activate all trajectory elements. More...
 
float GetPhysicalScale ()
 Gets the physical scale. More...
 
float GetLengthScale ()
 Return the length scale that maps lengths in the specified unit system to Unity game length units (e.g. Unity units per meter, Unity units per AU) More...
 
void SetTimeZoom (float value)
 Changes the timescale during runtime More...
 
float GetPhysicalTime ()
 Gets the physical time. Physical time may differ from game time by the timescale factor. More...
 
void AddBody (GameObject gameObject)
 Adds the game object and it's children to GravityEngine. The engine will then handle position updates for the body based on the gravitational force of all other bodies controlled by the engine. More...
 
void RemoveBody (GameObject toRemove)
 Remove game object from the list of objects. Note: In a large-N simulation the shuffle down may cause a real-time hit. In those cases, marking the body inactive with InactivateGameObjectwill exclude it from physics caluclations without the shuffle overhead More...
 
void InactivateBody (GameObject toInactivate)
 Inactivates the body in the GravityEngine. More...
 
void ActivateBody (GameObject activate)
 Re-activates an inactive body. More...
 
void UpdatePositionAndVelocity (NBody nbody, Vector3 pos, Vector3 vel)
 Updates the position and velocity of an existing body in the engine to new values (e.g. teleport of the object) More...
 
float GetVelocityScale ()
 
void Collision (GameObject body1, GameObject body2, NBodyCollision.CollisionType collisionType, float bounce)
 Update physics based on collisionType between body1 and body2. More...
 
Vector3 GetVelocity (GameObject body)
 Gets the velocity of the body in "Physics Space". May be different from Unity co-ordinates if physToWorldFactor is not 1. This is the velocity in Unity units. For dimensionful velocity use More...
 
void GetPositionVelocityScaled (NBody nbody, ref double[] p, ref double[] v)
 Gets the position and velocity in double precision in scaled units. (Note that the scale factors used to create these are floats - More...
 
Vector3 GetScaledVelocity (GameObject body)
 Gets the velocity of the body in selected unit system. e.g. for SOLAR get value in km/sec More...
 
Vector3 GetAcceleration (GameObject body)
 Gets the acceleration of the body in "Physics Space". May be different from world co-ordinates if physToWorldFactor is not 1. More...
 
void ApplyImpulse (NBody nbody, Vector3 impulse)
 Applies an impulse to an evolving body. The impulse is a change in momentum. The resulting velocity change will be impulse/mass. In the case of a massless body the velocity will be changed by the impulse value directly. More...
 
Vector3 VelocityForImpulse (NBody nbody, Vector3 impulse)
 Determine the velocity that will result if the impulse is applied BUT do not apply the impulse More...
 
void UpdateMass (NBody nbody)
 Update the mass of a NBody in the integration while evolving. More...
 
Vector3 GetWorldCenterOfMass ()
 Gets the world center of mass in world space co-ordinates. More...
 
Vector3 GetWorldCenterOfMassVelocity ()
 Gets the world center of mass velocity. More...
 
float GetInitialEnergy ()
 Gets the initial energy. More...
 
float GetEnergy ()
 Gets the current energy. More...
 
void RegisterParticles (GravityParticles nbp)
 Register a particle system (with GravityParticles component) to be evolved via the GravityEngine. More...
 
void DeregisterParticles (GravityParticles particles)
 Remove a particle system from the Gravity Engine. More...
 

Static Public Member Functions

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

Public Attributes

const bool DEBUG = false
 global flag for debugging
 
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. More...
 
const int NDIM = 3
 
Algorithm algorithm
 Algorithm for numerical integration of massive bodies.
 
bool optimizeMassless = true
 Use masslessEngine to reduce computations when many massless 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
 
GameObject trajectoryCanvas
 Used by Trajectory when text labels for time are enabled.
 
int trajResetLockout = 0
 Once a trajectory has been computed, lockout trajectory recomputations for this number of fixed update frames.
 
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. More...
 
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 editorCMfoldout
 State of inspector Center of Mass foldout.
 
bool editorShowTrajectory
 Track state of foldout in editor.
 
int stepsPerFrame = 8
 
int particleStepsPerFrame = 2
 
const byte INACTIVE = 1
 Bit flag used in integrator code.
 
const byte FIXED_MOTION = 1 << 1
 Bit flag used in integrator code.
 

Static Public Attributes

static string TAG = "GravityEngine"
 
static GravityEngine instance
 Singleton instance handle. Initialized during Awake().
 

Properties

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

Detailed Description

GravityEngine (NBE) 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 NBE 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).

Body initialization: TODO

Member Enumeration Documentation

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

Member Function Documentation

void GravityEngine.ActivateBody ( GameObject  activate)

Re-activates an inactive body.

Parameters
toInactivateTo inactivate.

Code from John Burns

void GravityEngine.AddBody ( GameObject  gameObject)

Adds the game object and it's children to GravityEngine. The engine will then handle position updates for the body based on the gravitational force of all other bodies controlled by the engine.

If the GravityEngine is set to auto-detect bodies, all game objects present in the scene with a NBody component will be added once the GravityEngine is set to evolve. If auto-detect is not enabled bodies are added by calling this method.

A gameObject added to the engine must have an NBody script attached. The NBody script specifies the mass and initial velocity of the object.

The add method will traverse the children of the added gameObject and add any that have NBody components.

Optionally, a body may also have a fixed motion script (e.g. FixedEllipticalOrbit) or a script that set the initial position and velocity based on orbit parameters (e.g. EllipticalStart)

Parameters
gameObjectGame object.
void GravityEngine.ApplyImpulse ( NBody  nbody,
Vector3  impulse 
)

Applies an impulse to an evolving body. The impulse is a change in momentum. The resulting velocity change will be impulse/mass. In the case of a massless body the velocity will be changed by the impulse value directly.

Parameters
nbodyNbody.
impulseImpulse.
void GravityEngine.Clear ( )

Reset the bodies/particle systems known to the Gravity Engine.

void GravityEngine.Collision ( GameObject  body1,
GameObject  body2,
NBodyCollision.CollisionType  collisionType,
float  bounce 
)

Update physics based on collisionType between body1 and body2.

In all cases except bounce, the handling is a "hit and stick" and body2 is assumed to be removed. It's momtm is not updated. body1 velocity is adjusted based on conservation of momtm.

Parameters
body1Body1.
body2Body2.
collisionTypeCollision type.
void GravityEngine.DeregisterParticles ( GravityParticles  particles)

Remove a particle system from the Gravity Engine.

Parameters
particlesParticles.
Vector3 GravityEngine.GetAcceleration ( GameObject  body)

Gets the acceleration of the body in "Physics Space". May be different from world co-ordinates if physToWorldFactor is not 1.

Returns
The acceleration.
Parameters
bodyBody.
static string GravityEngine.GetAlgorithmName ( Algorithm  algorithm)
static

Gets the name of the algorithm as a string.

Returns
The algorithm name.
Parameters
algorithmAlgorithm.
float GravityEngine.GetEnergy ( )

Gets the current energy.

Returns
The energy.
float GravityEngine.GetInitialEnergy ( )

Gets the initial energy.

Returns
The initial energy.
float GravityEngine.GetLengthScale ( )

Return the length scale that maps lengths in the specified unit system to Unity game length units (e.g. Unity units per meter, Unity units per AU)

Returns
The length scale.
double GravityEngine.GetParticleDt ( )

Gets the particle time step size.

Returns
The particle dt.
float GravityEngine.GetPhysicalScale ( )

Gets the physical scale.

Returns
The physical scale.
float GravityEngine.GetPhysicalTime ( )

Gets the physical time. Physical time may differ from game time by the timescale factor.

Returns
The physical time.
void GravityEngine.GetPositionVelocityScaled ( NBody  nbody,
ref double[]  p,
ref double[]  v 
)

Gets the position and velocity in double precision in scaled units. (Note that the scale factors used to create these are floats -

Parameters
nbodyNbody.
pP.
vV.
Vector3 GravityEngine.GetScaledVelocity ( GameObject  body)

Gets the velocity of the body in selected unit system. e.g. for SOLAR get value in km/sec

Returns
The velocity.
Parameters
bodyBody
Vector3 GravityEngine.GetVelocity ( GameObject  body)

Gets the velocity of the body in "Physics Space". May be different from Unity co-ordinates if physToWorldFactor is not 1. This is the velocity in Unity units. For dimensionful velocity use

Returns
The velocity.
Parameters
bodyBody
Vector3 GravityEngine.GetWorldCenterOfMass ( )

Gets the world center of mass in world space co-ordinates.

Returns
The world center of mass.
Vector3 GravityEngine.GetWorldCenterOfMassVelocity ( )

Gets the world center of mass velocity.

Returns
The world center of mass velocity.
void GravityEngine.InactivateBody ( GameObject  toInactivate)

Inactivates the body in the GravityEngine.

Mark the object as inactive. It will not affect other bodies/particles in the simulation.

This can be a better choice than removing since a removal may impact real-time performance.

This does not affect the activity state of the GameObject, only it's involvement in the GravityEngine

Returns
The game object.
Parameters
toInactivateGame object to inactivate.
static GravityEngine GravityEngine.Instance ( )
static

Static accessor that finds Instance. Useful for Editor scripts.

void GravityEngine.RegisterParticles ( GravityParticles  nbp)

Register a particle system (with GravityParticles component) to be evolved via the GravityEngine.

Parameters
nbpNbp.
void GravityEngine.RemoveBody ( GameObject  toRemove)

Remove game object from the list of objects. Note: In a large-N simulation the shuffle down may cause a real-time hit. In those cases, marking the body inactive with InactivateGameObjectwill exclude it from physics caluclations without the shuffle overhead

Parameters
toRemoveGame object to remove (must have a NBody component)
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.
void GravityEngine.SetEvolve ( bool  evolve)

Control evolution of masses and particles in the gravity engine.

Parameters
evolveIf set to true evolve.
void GravityEngine.SetTimeZoom ( float  value)

Changes the timescale during runtime

Parameters
valueValue.
void GravityEngine.SetTrajectoryPrediction ( bool  newState)

Sets the trajectory prediction state (enable/disable). On enable, will activate the Trajectory elements and re-run the trajectory prediction code. On disable will de-activate all trajectory elements.

Parameters
newStateIf set to true new state.
void GravityEngine.UpdateMass ( NBody  nbody)

Update the mass of a NBody in the integration while evolving.

Parameters
nbodyNbody.
void GravityEngine.UpdatePositionAndVelocity ( NBody  nbody,
Vector3  pos,
Vector3  vel 
)

Updates the position and velocity of an existing body in the engine to new values (e.g. teleport of the object)

Parameters
nbodyNbody.
posPosition.
velVel.
Vector3 GravityEngine.VelocityForImpulse ( NBody  nbody,
Vector3  impulse 
)

Determine the velocity that will result if the impulse is applied BUT do not apply the impulse

Returns
The for impulse.
Parameters
nbodyNbody.
impulseImpulse.

Member Data Documentation

ForceChooser.Forces GravityEngine.force

The force used when one of the ANY_FORCE integrators is selected. Any force use requires that the scale be set to DIMENSIONLESS.

int GravityEngine.particleStepsPerFrame = 2

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

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.

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.


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