EntityComponents
Entity components are the way for flexible compartmentalization, however it is not as flexible as it could be in this game as it was added somewhat late in the game's life.
A lot of newer features use this system instead of integrating the feature inside a block type.
How does it all work
First the files involved (vanilla names for reference, but remember that file names don't actually matter):
- EntityContainers.sbc is where entities (blocks, characters, etc) are paired with components. Definition docs: Container Definition
- EntityComponents.sbc is where components are configured. These have a lot of definitions and are listed in this page below, but not all components can have a definition and that is fine, the component itself can still be used though.
As with all definitions, if you copy either of the mentioned vanilla files to your mod, do not keep all the entries there because you will overwrite them and cause all sorts of problems!
Components will save data to the entity and some will save configurable things too (usually the Inventory component), for that reason it's recommended to place a new block/spawn a new character/etc every time you add or remove components.
How the entity container works
When an entity (block, character, etc) spawns, it will go through these until it finds one and stops:
- Looks for an entity container that has the entity's TypeId and SubtypeId exactly.
- Otherwise, if entity's SubtypeId is not null nor empty, then it looks for an entity container with
EntityBaseTypeId and the entity's SubtypeId. - Otherwise, it looks for an entity container with entity's TypeId and a null or empty subtypeId.
If a container is found, then the entity will get the container's <DefaultComponents> spawned and added.
This means you can declare an entity container for an entire type by ommitting the SubtypeId, but that also means it won't affect entities that have an entity container for their exact ID. In other words, an entity will only get components from one entity container.
When adding a new container, look in the game's EntityContainers.sbc for type-wide entity containers to copy any important components. One example is TextPanel gains LcdSurfaceComponent through a type-wide entity container and you must copy it (as it is required for TextPanel's function) to your entity container if you declare one for your TextPanel.
Careful with blocks that have a blank SubtypeId because you cannot target them individually with an entity container, as you will instead define the container for the entire type.
Container SBC documentation & examples: Container Definition. The game's EntityContainers.sbc also contains documentation on how it works, as well as the content itself being examples.
How the entity components work
As mentioned before, an entity component definition is just to configure a component, for it to do anything it must be referenced by an entity container. One exception is ModStorageComponent definition which works as a global definition and mod scripts usually add the required component to the entity.
Some components are inherently required, like the aformenteioned case for TextPanel with the LcdSurfaceComponent.
Other components only function on specific types (like how the LcdSurfaceComponent is also exclusive to TextPanel type), if this is known it will be mentioned in the comment for the component in the list below.
Component SBC documentation for each component is found in the list below. The game's EntityComponents.sbc also contains documentation on how it works, as well as the content itself being examples.
Both in the same file
It might be easier to declare both the container and the components in the same file, you can even thrown in the CubeBlock definition too.
This example can be dropped in a mod to see the vanilla largegrid battery bleed from one of its terminals.
<?xml version="1.0" encoding="utf-8" ?>
<Definitions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CubeBlocks>
<!-- your custom block would go here, but this example acts on a vanilla block. -->
</CubeBlocks>
<EntityContainers>
<Container>
<Id>
<TypeId>BatteryBlock</TypeId>
<SubtypeId>LargeBlockBatteryBlock</SubtypeId>
</Id>
<DefaultComponents>
<Component BuilderType="MyObjectBuilder_Inventory" ForceCreate="true"/>
<Component BuilderType="MyObjectBuilder_ParticleEntityComponent" ForceCreate="true"/>
<!-- ... -->
</DefaultComponents>
</Container>
<!-- ... -->
</EntityContainers>
<EntityComponents>
<EntityComponent xsi:type="MyObjectBuilder_InventoryComponentDefinition">
<Id>
<TypeId>Inventory</TypeId>
<SubtypeId>LargeBlockBatteryBlock</SubtypeId>
</Id>
<Size x="1" y="1" z="0.333"/>
</EntityComponent>
<EntityComponent xsi:type="MyObjectBuilder_ParticleEntityComponentDefinition">
<Id>
<TypeId>ParticleEntityComponent</TypeId>
<SubtypeId>LargeBlockBatteryBlock</SubtypeId>
</Id>
<ParticleEffectName>Grinder_Character</ParticleEffectName>
<DummyName>detector_terminal_1</DummyName>
<RemoveExistingComponentOnNewInsert>false</RemoveExistingComponentOnNewInsert>
</EntityComponent>
<!-- ... -->
</EntityComponents>
</Definitions>
List of Entity Components
Similar to blocks, these have a component TypeId which is the component itself (for EntityContainers.sbc), and a definition which has elements to configure (for EntityComponents.sbc).
Generally if the definition exists then it is required, it might crash otherwise or have strange behavior. It will not create a definition with the defaults from the wiki page, those defaults are only applicable if the definition is defined but the element is missing.
The xsi:type is mentioned inside the definition page. If the page doesn't exist, you can generate the name from the page title by removing the space and prefix it with "MyObjectBuilder_".
For example: "AiBlockPowerComponent Definition" -> "MyObjectBuilder_AiBlockPowerComponentDefinition".
The types here do not include the MyObjectBuilder_ prefix for the sake of having the page narrow, but that prefix is required when writing the type in the container's <DefaultComponents>!
For everything
| TypeId | SBC definition | Comment |
|---|---|---|
| Inventory | InventoryComponent Definition | Adds/overrides inventory (conveyor network support is separate, ConveyorEndpointComponent) |
| UseObjectsComponent | UseObjectsComponent Definition | Provides the capability to host useobjects. |
| PhysicsBodyComponent | PhysicsBodyComponent Definition | Physics properties for special entities |
| ModelComponent | ModelComponent Definition | Model for special entities |
| TimerComponent | TimerComponent Definition | Lifespan for special entities |
| InventorySpawnComponent | InventorySpawnComponent Definition | Mentioned in Characters.sbc, but can be used on blocks as well |
For characters
For all blocks
| TypeId | SBC definition | Comment |
|---|---|---|
| ConveyorEndpointComponent | ConveyorEndpointComponent Definition | Can give conveyor network access and configure pull/push constraints |
| ParticleEntityComponent | ParticleEntityComponent Definition | Spawns an attached particle effect |
| LightingComponent | LightingComponent Definition | Requires a block with on/off (FunctionalBlock or higher) |
| MaintenancePanelComponent | MaintenancePanelComponent Definition | Interactive non-physical door |
| RotatingSubpartComponent | RotatingSubpartComponent Definition | Spins a subpart |
| RandomMovementSubpartComponent | RandomMovementSubpartComponent Definition | Moves subparts randomly in a volume (used for fish) |
| RandomCargoEntityComponent | RandomCargoEntityComponent Definition | |
| RadiationSourceEntityComponent | RadiationSourceEntityComponent Definition | Constant radiation hazard |
| ModStorageComponent | ModStorageComponent Definition | Mod scripts use this to save data |
For various specific blocks
For Action Relay blocks
| TypeId | SBC definition | Comment |
|---|---|---|
| SignalChannelEntityComponent | SignalChannelEntityComponent Definition | |
| SignalConnectivityCheckerEntityComponent | No definition | |
| SignalReceiverEntityComponent | No definition | |
| SignalSenderEntityComponent | No definition |
For Event Controller blocks
The definitions without a page only have the <UniqueSelectionId> element, see any other event's definition for docs on that.
Misc/Unknown
| TypeId | SBC definition | Comment |
|---|---|---|
| GlobalEncounterComponent | No definition | Automatically added to global encounters' grids |
| EntityStorageComponent | No definition | Probably used by VisualScriptingTool |
| EntityOwnershipComponent | No definition | Alternative to ownership provided by Computer component, but not fully implemented |
| AreaTrigger | No definition | Used in some prefabs and probably by VisualScriptingTool |
| UpdateTrigger | No definition | Used in pirate base prefabs |
| TriggerAggregate | No definition | |
| InventoryAggregate | No definition |