The Entity

The Fundamentals → The Entity / Entity Types

Up to date for Platform 0.25.0

Written by Connor Jakubik.

Prerequisites:

• https://github.com/SimDynamX/SpaceTeamsPro/wiki/Sim-Structure
• https://github.com/SimDynamX/SpaceTeamsPro/wiki/The-Parameter

---

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 (explained in The Parameter wiki doc). The parameters held in an Entity's ParamMap define the entire sim representation of that Entity.

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.

---

Entity Common Parameters

Basic

• #Required/Name (string)
  • Sets the name on the Entity.
• #Required/Type (string)
  • Sets the type on the Entity.
• #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.25.0)

Dynamics

• Dynamics/PropagationType (string)
  • Sets what PropagationType the Entity uses.
  • Default is NoPropagation.
  • Typically, most entities should use ComputeAcceleration.
  • Propagation Types:
    • (Most common types have * next to them)
    • * NoPropagation: The entity does not have a meaningful location or physics state, and doesn't get moved in a 3D client program like SpaceCRAFT. Trying to set a location, for example, on an entity with this propagation type is invalid.
    • ComputePosition:
      • The entity has a meaningful location / physics state.
      • Motion of the entity is assumed to be propagated (actually updating location, etc) in the Compute_Server (in a System).
      • 3D client programs react to only Location and Rotation parameters of this Entity.
    • ComputeVelocity:
      • The entity has a meaningful location / physics state.
      • Motion of the entity is assumed to be propagated in the Compute_Server (in a System).
      • 3D client programs react to only Location, Velocity, Rotation, and AngVelocity parameters of this Entity.
    • * ComputeAcceleration:
      • The entity has a meaningful location / physics state.
      • Motion of the entity is assumed to be propagated in the Compute_Server (in a System).
      • 3D client programs react to Location, Velocity, Acceleration, Rotation, AngVelocity, and (partially) AngAcceleration parameters of this Entity.
    • ComputeJerk: (Unimplemented)
      • The entity has a meaningful location / physics state.
      • Motion of the entity is assumed to be propagated in the Compute_Server (in a System).
      • 3D client programs react to Location, Velocity, Acceleration, Rotation, AngVelocity, and (partially) AngAcceleration parameters of this Entity.
    • Clientside_FreeBody: (Unimplemented)
      • The entity has a meaningful location / physics state.
      • Motion of the entity is assumed to be propagated in a client program like SpaceCRAFT.
      • The 3D client program that "possesses" (takes responsibility for controlling) this Entity feeds its physics state back into parameters. The entity is assumed to be a free body whose dynamics react to applied forces, torques, impulses, etc from other parts of the sim.
      • All other programs in the sim receive and react to these parameters to match the motion of this Entity.
    • * Clientside_PawnControl:
      • The entity has a meaningful location / physics state.
      • Motion of the entity is assumed to be propagated in a client program like SpaceCRAFT.
      • The 3D client program that "possesses" (takes responsibility for controlling) this Entity feeds its physics state back into parameters. The entity may or may not have a specialized motion implementation that ignores physics for usability as a user-controlled "Pawn".
      • All other programs in the sim receive and react to these parameters to match the motion of this Entity.
    • PhysXInteractible: (Unimplemented)
    • CoordinateFrame_Static: (Unimplemented)
• Dynamics/IsRebaseCenter (bool)
  • Also aliased as Dynamics/ControlledObject.
  • Functionality unnecessary and removed as of v0.25.0.
  • Set one entity as true for this to have coordinate rebasing be centered around it.

Necessary for all PropagationTypes besides NoPropagation

• 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.
• 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.
  • Usually these are not directly get/set; use Reference Frame-aware Entity getLocation, getRotation, setLocation, setRotation, etc functions instead.

Necessary for RigidBodyPropagator

• Dynamics/Mass (double)
  • Body mass
  • Default: 1 kg
• Dynamics/Inertia_BodyFixed (doubleM3x3)
  • Body inertia tensor
  • Default: 1-meter homogenous sphere with Mass
• Dynamics/Force (doubleV3)

  • WIP

• Dynamics/Torque (doubleV3)

  • WIP

• Dynamics/Impulses (array, doubleV3)

  • WIP

Graphics

• Graphics/RenderFar (bool)
  • Not yet implemented.
• 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.25.0).
  • Default: 1.0
• Graphics/VisualRadius_m (double)
  • Visual radius of this object in meters.
  • Default: (no value; user-defined behavior)

---

Entity Types

Entities are spawned in different ways depending on their type. Different nodes (client & server programs) in the Platform handle Entity Types differently. The following describes the significance of each Entity Type as specified in a Sim Config or Entity Template / Entity Config. Besides FromTemplate and Assembly, these only become significant in our Unreal Engine (UE) client program.

Data

• Minimal, parameters only.
• No physical representation in the simulation.
  • Dynamics functions like getLocation(), setVelocity(), etc are invalid and will cause an error.
• No #Data parameters section.
• Any unrecognized Entity type will load as a Data type.

FromTemplate

• This type only exists for loading purposes; you will never encounter an actual loaded Entity with type FromTemplate; only maybe an EntityConfig.
• The name (#Required/Name) of this FromTemplate Entity will be used in place of the name on the Entity Template that is loaded.
• #FromTemplate required parameters:
  • Source_Path: a string with the filepath (relative to the Platform root directory) to an Entity Config to load.
    • (TODO): documentation on Entity Template files.
  • (Optional) ParamOverrides: a param map that you can put parameters in to either overwrite or add onto the loaded template's parameters, including special parameters such as type.

Object

• Uses a UStaticMesh (Unreal Engine static mesh - 3D model with a default material applied) as its physical representation.
• These static mesh assets are included by SimDynamX into Platform releases.
• #Object required parameters:
  • Mesh_Path: a string with the results of pasting after doing Right Click->Copy Reference on a Static Mesh asset in the Content Browser.
• Uses the Graphics/Scale parameter to set scale.

Object_Loaded

• TEMPORARILY DISABLED AS OF 0.8.2-0.14.0+.
  • In 0.14.0 we implemented a Blueprint quick version of this type. A C++ version that reuses this designation is forthcoming.
• Uses a runtime-loaded 3D model as its physical representation.
• #Object_Loaded required parameters:
  • Mesh_Path: a string with the filepath relative to the Platform root directory for where to look for this 3D model to load.

Planet

• Procedural-Mesh-Generation Planet.
• #Planet required parameters:
  • There are TONS of required parameters; I recommend using a FromTemplate type and pointing its Source_Path to a Planet Entity Config.
  • TODO list out the required parameters

BP

• Uses a Blueprint subclass of Entity_Impl (C++ AEntity_Impl) (or subclasses thereof) as its physical representation.
• Type name can also be UI, for backwards compatibility
• #BP required parameters:
  • BP_Path: a string with the results of pasting after doing Right Click->Copy Reference on a Blueprint asset in the Content Browser.
    • (NOTE): BP_Path requires you to edit this to remove the Blueprint' prefix, and replace the end ' with _C.

Pawn

• Uses a Blueprint subclass of Entity_Pawn (C++ AEntity_Pawn) (or subclasses thereof) as its physical representation.
• This entity can be possessed by a user, and assuming things are set up correctly (usually by a PreSimConfigurator), this Entity will work properly in a multiuser simulation.
• #Pawn required parameters:
  • BP_Path: a string with the results of pasting after doing Right Click->Copy Reference on a Blueprint asset in the Content Browser.
    • (NOTE): BP_Path requires you to edit this to remove the Blueprint' prefix, and replace the end ' with _C.
  • Role_Name: a string, how this Pawn appears on a Role Picker.
  • Is_Possessed: a bool, set to false initially, that tracks whether any of the clients in a multiuser sim have taken ownership of this pawn.
  • Username: a string, set to "(No User)" initially, that indicates the username of the client that takes ownership of this pawn.
  • GraphicsFrame: an EntityRef to the Entity which this Pawn uses the body-fixed frame of as a Graphics Frame. If you possess (switch control to) this pawn, the Graphics Frame will be changed to match this Entity. More details in reference frames docs.

Assembly

• This (WIP) type is similar to a FromTemplate type, except this Assembly-type Entity will be kept during the simulation.
• Upon spawning its subparts, this Assembly will hold EntityRef parameters to them in each of the #Assembly/Subparts/<subpart name>/Ref locations.
• #Assembly required parameters:
  • Subparts: a param map with a nested param map for each Subpart of this Assembly
  • Required parameters for each Subpart:
    • Source_Path: a string with the filepath (relative to the Platform root directory) to this Entity Template to load.
    • (Optional) ParamOverrides: a param map that you can put parameters in to either overwrite or add onto the loaded template's parameters, including special parameters such as type.
    • Rel_Location: a doubleV3 with the location of this subpart relative to its parent.
    • Rel_Rotation: a doubleV4 with the quaternion rotation of this subpart relative to its parent.
    • Socket: an int32 that denotes which of the parent's sockets the subpart occupies, and is -1 if the subpart does not occupy a socket.
    • Attachment: a string that matches one of a set of possible ways this subpart is attached to its parent: (TODO).

We may add more Entity types in the future. The variable type for the type field is a string, so unfamiliar entity types on a certain client program can still be parsed without error.