Skip to content

The Entity

Jump to bottom
Connor Jakubik edited this page Aug 20, 2025 · 46 revisions
The Fundamentals → The Entity / Entity Common Parameters

Up to date for Platform 0.37.0

Written by Connor Jakubik.

Prerequisites:

The Entity

What is an Entity?

An Entity (class definition in internal SimDynamX repo: Entity_Base.h) is an object in the simulation. An Entity contains Parameters, which define everything there is to know about that Entity. Entities are either defined in the Sim Config or added during the simulation by an AddEntity function call.

Entity is a subclass of GenParamMap (described in The Parameter wiki doc). This means each entity holds Parameters and any ParamMap function can also be used on an Entity. The parameters held in an Entity's ParamMap define the entire sim representation of that Entity, such as location, mass, visual properties, etc.

Each Entity has an id in UUID format, which uniquely identifies that entity in a sim. If an entity was defined in the sim config, its id is an integer which starts at 1 and increases per each entity. If an entity is added to the sim, its id is generated randomly. UUIDs are Universally Unique because they are long (16 byte) sequences that are generated in a manner that is statistically unlikely to ever generate the same ID twice, across all computers worldwide.

Each entity has a Type, which affects how this Entity is constructed depending on the program that is loading it. The Compute_Server has almost no distinction in behavior between types, and the SpaceCRAFT application treats each type differently to set up graphics and interaction functionality. For example, a Planet-type Entity will be constructed with code that handles procedural 3D planet surface rendering.

Each entity has a Name, which is either specified in the sim config or supplied as part of the EntityConfig for the AddEntity() function call. Entity names are used for creating EntityRef values in a sim config, and show in various sim UI, so we typically like to keep them deduplicated, even though the id of each entity is enough to uniquely identify it. We may change this later to ensure no duplicate names.

Entity Parameters

A majority of the functionality in every Space Teams sim happens by any of the programs in a sim reading and modifying parameter values. For example, to change the mass of an Entity, its Mass and Inertia_BodyFixed parameters must be modified. There are many "Common" parameters which have their name (key) and type standardized to ensure a System written for one sim can easily work in another. In some cases such as dynamics-relevant parameters, there is a specific set of functions on the Entity / Entity_Base class that should be used in place of directly accessing parameter values. These functions typically are safer to use due to extra checks on invalid input, default behavior for missing params, and other reasons.

The below lists of Common parameters are not the only parameters that can be used in a simulation. As long as new Entity params don't reuse the same name (key), the user can Add/Set/Get/Delete any param for their own use case. Some general guidance on how to organize new parameters in a simulation:

  • Consider whether the param should go on an Entity, on a System Instance, or on the SimEntity. Typically, if the param describes some property that is different per Entity, put it on each Entity. If the param changes some details that should be kept consistent across the sim AND does not need to be accessible across multiple programs, put that param in the System Instance that uses it. If the param needs to be globally accessible for convenience and code design reasons, put it in the SimEntity.
  • Use nested param maps to group added params into neat sections.
  • Maintain a consistent naming pattern through the use of capitalization and underscores.

Entity Common Parameters

Basic

  • #Required/Name (string)
    • Sets the name on the Entity.
    • Functions: getName()
  • #Required/Type (string)
  • #Required/Systems (JSON array of string)
    • Not parsed as a parameter; used only in the Sim Config. Assigns Systems on this Entity.
    • Unused in an EntityConfig (as of v0.28.0)

Dynamics & Propagators

The Propagator of an entity controls how the entity 3D graphics representation moves with respect to its parameters.

  • Dynamics/Propagator (string)
    • Sets what Propagator the Entity uses.
    • Functions: getPropagator(), setPropagator()
    • Default: No_Body.
    • Propagator Choices:

Necessary for all Propagators besides No_Body

  • Dynamics/ResidentFrame (EntityRef)
    • Chooses a body-fixed frame of an Entity to be the coordinate basis to express all dynamics parameters on this Entity.
    • For example, if you set a ResidentFrame of Mars for an entity, and set its location to [1.1 * Mars Radius, 0, 0], the Entity will start at 0,0 Latitude/Longitude above the surface.
    • Functions: getResidentFrame(), setResidentFrame()
    • Default: Sim Base Frame
      • Highly recommended to always use a ResidentFrame that is not defaulted.
  • Location, Rotation, Velocity, AngVelocity, Acceleration, AngAcceleration
    • All of type doubleV3 besides Rotation which is doubleV4
    • These are the state parameters of an Entity. They are used in combination with their sim timestamp to extrapolate the state of an Entity.
    • These parameters will be added if they are missing.
    • Almost always, these are not directly get/set; use Reference Frame-aware Entity getLocation(), getRotation(), setLocation(), setRotation(), etc functions instead.
      • TODO explain lapse in functionality of setVelocity(), etc.
    • The parameter values are expressed in the Resident Frame.
    • Rotation is a x,y,z,w Hamilton quaternion, corresponding to the passive Transformation matrix (as opposed to active Rotation matrix) from the ResidentFrame to the body frame of this Entity.
    • Rotation w value is the scalar term, and our core code typically normalizes the quaternion to have a positive w term when getting/setting a quaternion in Space Teams.
    • AngVelocity is a 3-vector where the vector direction is the axis of rotation, and the magnitude of the vector is the speed of the right-handed rotation around that axis in radians per second.
    • Some dynamics math that may be encountered assumes body axes rates for angular velocity. Note that getAngVelocity() and setAngVelocity() are set up to reference an external body as the frame of reference for the angular velocity to be with respect to and/or expressed in.

Necessary for SPICE propagator:

  • body (string)
    • NAIF ID number or string of the body (examples: JUPITER, CERES)
    • Required; will error if not present.
  • bodyframe (string)
    • NAIF ID number or string of the frame to use for the body-fixed frame of this body (examples: IAU_JUPITER, MOON_ME)
    • Required; will error if not present.

Necessary for ST_Rigid_Body or Unreal_Chaos

  • Dynamics/Mass (double)
    • Body mass
    • Functions: getMass(), setMass()
      • Not forcibly synchronized with Inertia.
    • Default: 1 kg
  • Dynamics/Inertia_BodyFixed (doubleM3x3)
    • Body inertia tensor
    • Functions: getInertiaTensor(), setInertiaTensor()
      • Not forcibly synchronized with Mass.
    • Default: 1-meter homogenous sphere with total mass from Mass parameter.
    • Expressed In: Body Axes, kg * m^2
    • NOTE: ST_Rigid_Body currently assumes the entity body axes origin is co-located with the center of mass.

    • TODO check on if this could be accounted for by inertia tensor changes alone or would require continuously computing parallel axis theorem.

(Deprecated) Necessary for RigidBodyPropagator

  • Dynamics/Mass (double)
    • Body mass
    • Functions: getMass(), setMass()
      • Not forcibly synchronized with Inertia.
    • Default: 1 kg
  • Dynamics/Inertia_BodyFixed (doubleM3x3)
    • Body inertia tensor
    • Functions: > (WIP)
      • Not forcibly synchronized with Mass.
    • Default: 1-meter homogenous sphere with total mass from Mass parameter.
    • Expressed In: Body Axes, kg * m^2
    • NOTE: RigidBodyPropagator currently assumes the entity body axes origin is co-located with the center of mass.

    • TODO check on if this could be accounted for by inertia tensor changes alone or would require continuously computing parallel axis theorem.

  • Dynamics/Force (doubleV3)
    • A single parameter that can be get/set using Entity functions get/setForce. This is used as an "external force" by propagators such as RigidBodyPropagator.
    • Limitation: Must sum external forces elsewhere then apply to the entity in one place, with the exception of forces included in the propagator code itself.
    • Default: Zero vector
    • Expressed In: Resident Frame, N
  • Dynamics/Torque (doubleV3)
    • A single parameter that can be get/set using Entity functions get/setTorque. This is used as an "external torque" by propagators such as RigidBodyPropagator.
    • Default: Zero vector
    • Limitation: Must sum external torques elsewhere then apply to the entity in one place, with the exception of torques included in the propagator code itself.
    • Expressed In: Resident Frame, N * m
  • Dynamics/Impulses (map, doubleV3)
    • A set of impulses that can be produced from anywhere in the sim and are consumed by a propagator such as RigidBodyPropagator.
    • Each impulse is its own object, and those objects are referenced by the name passed with the addImpulse() call. When the impulse is consumed by a getImpulse() call, the impulse object under that name in the map is set to zero.
    • Limitation: If the same impulse name is used to add another impulse before the consumer consumes the impulse, the previous impulse value will be lost and not used by the consumer (resulting in missing momentum).
    • Default: Zero vector
    • Expressed In: Resident Frame, N * s

Graphics

  • Graphics/Visible (bool)
    • Whether the entity graphics model should be visible.
    • Default: true
    • Mostly unimplemented as of v0.34.0
  • Graphics/Highlight (bool)
    • Whether to add a highlight onto this entity.
    • Implementation depends per entity type.
    • Default: false
    • Mostly unimplemented as of v0.34.0
  • Graphics/IsLightSource (bool)
    • Only should be true for the main light source entity in the sim. Usually this is the Sun.
    • Default: false
  • Graphics/Scale (double)
    • Scale multiplier from original dimensions.
    • Used only by Entity Type Object for now (v0.28.0).
    • Default: 1.0
  • Graphics/VisualRadius_m (double)
    • Visual radius of this object in meters.
    • Default: (no value; user-defined behavior)
  • Graphics/RenderFar (bool)
    • Whether the entity should render as a distant object when too small to "see" normally.
    • Default: false
    • Implemented in v0.29.0.
    • Also need the FarRender params below. Only Radius_m is mandatory.
  • Graphics/FarRender
    • Param map for Far-Render feature (pixels-wide impostor rendering to show bright objects at extreme distance).
    • FarRender/Radius_m (double)
      • Approximate visual radius which matches disk area to this entity's approximate side profile area.
    • FarRender/AlbedoRGB (doubleV3)
      • Red-Green-Blue Albedo values (fraction of incident light reflected), 0.0->1.0 for 0->100%.
      • Default: 1.0, 1.0, 1.0

Advanced

Entity Member Variables

On both Compute_Server and UE Client:

  1. EntityID_t id
    • UUID (Universally Unique Identifier)
    • constant per Entity
  2. string name
    • We do not yet know if we're going to specify this to be unique. At the moment, Entities only need to have a unique name in the Sim Config (for EntityRef assignment purposes). Internal developer discussion here: https://github.com/SimDynamX/SC_Platform/issues/660.
    • constant per Entity
  3. string type
    • This type affects how this Entity is spawned.
    • constant per Entity

On Compute_Server:

  1. Class Entity is a subclass of Entity_Base.

On UE Client:

  1. Class EntityComp is a subclass of both Entity_Base and UE class UComponent
  2. An EntityComp is applied to base Entity AActor-subclass classes like AEntity_Impl and AEntity_Pawn.

Sections

Installing Space Teams

The Fundamentals

Simulation Development Workflow

Physics and Propagation

Use Cases

Verification & Validation

Publications / Theses

Clone this wiki locally