Entity Types

Pulsar has several different entity types, and a number of subtypes.
entities are defined by what datablobs they have. (all entities are `Type` `Entity`, there is no differentiation code typewise, the only differentiation is the types of datablobs they contain.

In ECS, entities are just a list of datablobs(ecs components), so a ship might have a movement datablob and a planet might have an orbit datablob. the processors(ecs systems) then work on each entity that has the datablob for it’s type, i.e. the shipmove processor works on any entity that has a movement datablob, and the orbit processor works on any entity that has an orbit datablob.

Pulsar4x has the added complexity that ships are made up of components which are player defined (you design the components in game) the component types are defined in the json mod files, ie an engine has move, fuel use, and how the player can manipulate those during component design. etc. etc.
so we’ve got ship entities which has ship component entities, almost a two tiered ECS type thing going on, this is made even more complex by changes to the component entities affecting the parent entity during gameplay, ie cargo added and removed from the cargostorage component entity will add or remove mass to the parent ship entity.
In the code this is handled by having a datablob which lists the component entities, then having a procesor which updates/adds/removes the parent ship entity’s datablobs depending on what datablobs the component entities have.
see also:
Component Definitions and the JsonParser

SystemBody Entities:
These are Stars, Planets, Asteroids, etc etc.

Colony and Ship Entities:
These are High level “Parent” entities which have a ComponentInstancesDB which is a dictionary of lower order Component entities.
Colonies are tied to a planet entity and cannot move.
They have a ColonyInfoDB.
Ships are sometimes tied to a planet and sometimes not. (TODO find a more generic way to define how entities are tied or linked to a planet, currently this is defined in the colonyInfoDB. maybe check for an orbitDB, then check the distance to the parent?)
Ships are very similar to colony entities and have a ShipInfoDB.
Ships may or may not have a PropulsionDB (might rename this DB in the future to MovementAbilityDB or something)
Both have a number of XxxAbilityDB types which give the entity it’s functions, these abilityDB are typicaly added to the entity by installing a Component Entity via a factory.
I’m attempting to make these entities even more similar than they currently are, and get away from the Ability

Components
Components and installations are nearly exactly the same thing, and there is very little to differentiate them from each other bar the ComponentMountType enum in the ComponentInfoDB
One key thing to be aware of however is that components are made up of two entity types.

ComponentInstanceEntity:
This a MidLevel Entity that gets installed on a ship or a colony entity via a factory (or processor?)
it contains a ComponentInstanceInfoDB which holds data such as hitpoints remaining, whether it’s enabled or disabled, and holds a reference to its ComponentDesignEntity.
it can also hold AbilityDB.
this is the actively changing part of a component.
it is created from a Component Design Entity.
When it is created it may give AbilityDB to the parent ship or colony, or the AbilityDB may be added to itself, depending on the related AtbDb.

Component Design Entity
This is a lower level entity which typically does not change after it’s been created ingame.
it has a ComponentInfoDB which holds data that is simular across all Component Designs, such as Size, initial HTK, Crew or Population requirements, MountType etc.
It contains a number of XxxAtbDB or ComponentAttributeDB.
it is created by the user when designed in the UI.
its type is defined via a ComponentTemplateSD. see Component Definitions.

Adding a Component to a Parent Entity:
Components can be added to ships or colonies by using the EntityManipulation.AddComponentToEntity(parentEntity, componentEntity) function.
the function will check to see if the parentEntity and componentEntities are valid:
parentEntity must have a ComponentInstancesDB
componentEntity must have a ComponentInfoDB if it’s a design or a ComponentInstanceInfoDB if it’s an instance.
note
check the AttributeToAbilityMap to see if the component’s attributes are listed.
check the ReCalcProcessor to see if the parents abilities are listed.
some abilities are still sitting in ShipInfoDB or ColonyInfoDB, these need to be moved into the ReCalcProcessor and changes made to make them more generic.

Here’s a picture of how a Parent entity looks like:
(it’s not showing all the datablobs, but shows the componentInstance datablob.)