-
Notifications
You must be signed in to change notification settings - Fork 0
The Entity
The Fundamentals → The Entity / Entity Types |
---|
Written by Connor Jakubik.
Prerequisites:
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.
-
EntityID_t id
- UUID (Universally Unique Identifier)
- constant per Entity
-
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
-
string type
- This type affects how this Entity is spawned.
- constant per Entity
- Class
Entity
is a subclass ofEntity_Base
.
- Class
EntityComp
is a subclass of bothEntity_Base
and UE classUComponent
- An
EntityComp
is applied to base EntityAActor
-subclass classes likeAEntity_Impl
andAEntity_Pawn
.
-
#Required
/Name
(string)- Sets the
name
on the Entity.
- Sets the
-
#Required
/Type
(string)- Sets the
type
on the Entity.
- Sets the
-
#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
/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.
- Also aliased as
-
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
besidesRotation
which isdoubleV4
- 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.
- All of type
-
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
/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)
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.
- Minimal, parameters only.
- No physical representation in the simulation.
- Dynamics functions like
getLocation()
,setVelocity()
, etc are invalid and will cause an error.
- Dynamics functions like
- No
#Data
parameters section. - Any unrecognized Entity type will load as a
Data
type.
- This type only exists for loading purposes; you will never encounter an actual loaded Entity with type
FromTemplate
; only maybe anEntityConfig
. - 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
: astring
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.
-
- 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
: astring
with the results of pasting after doingRight Click
->Copy Reference
on a Static Mesh asset in the Content Browser.
-
- Uses the
Graphics
/Scale
parameter to set scale.
- 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
: astring
with the filepath relative to the Platform root directory for where to look for this 3D model to load.
-
- Procedural-Mesh-Generation Planet.
-
#Planet
required parameters:- There are TONS of required parameters; I recommend using a
FromTemplate
type and pointing itsSource_Path
to a Planet Entity Config. - TODO list out the required parameters
- There are TONS of required parameters; I recommend using a
- 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 doingRight 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
.
- (NOTE): BP_Path requires you to edit this to remove the
-
- 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 doingRight 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
.
- (NOTE): BP_Path requires you to edit this to remove the
-
Role_Name
: a string, how this Pawn appears on a Role Picker. -
Is_Possessed
: a bool, set tofalse
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.
-
- This (WIP) type is similar to a
FromTemplate
type, except thisAssembly
-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
: astring
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
: adoubleV3
with the location of this subpart relative to its parent. -
Rel_Rotation
: adoubleV4
with the quaternion rotation of this subpart relative to its parent. -
Socket
: anint32
that denotes which of the parent's sockets the subpart occupies, and is -1 if the subpart does not occupy a socket. -
Attachment
: astring
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.