Adding and removing components during runtime
During runtime, a worker instance can request SpatialOS to:
- add a component to an entity using
Connection::SendAddComponent
- remove a component from an entity using
Connection::SendRemoveComponent
In order to use these functions, you must set ConnectionParameters.EnableDynamicComponents
to true
.
Non-existent components
This feature introduces the concept of non-existent components. A non-existent component is a component which can be added to an entity but is not currently on the entity. In other words, a worker instance has write access authority over the component, but the component is not currently on the entity in the game world.
Write access authority over non-existent components works the same as write access authority over existing components. If you are unsure of how to change write access authority, see the example of changing authority.
Authority change and component state synchronization
When you set ConnectionParameters.EnableDynamicComponents
to true
, worker instances will receive an AddComponentOp
or RemoveComponentOp
(instead of a ComponentUpdateOp
) when the worker instance gains or loses write access authority over a component.
This is to synchronize the worker instance’s local view with that of the Runtime.
Immediately before a worker instance gains write access authority over a component, the worker instance receives either:
- an
AddComponentOp
(if the component exists) - a
RemoveComponentOp
(if the component is non-existent)
Likewise, after losing write access authority over a component, the worker instance receives either:
- an
AddComponentOp
(if the component exists) - a
RemoveComponentOp
(if the component is non-existent)
AddComponentOp
and RemoveComponentOp
must be treated in an idempotent way. In other words, if the worker instance receives:
- an
AddComponentOp
, you should replace any existing state for the component in the worker instance’s local view withAddComponentOp.Data
- a
RemoveComponentOp
, you must remove any existing state for the component in the worker instance’s local view
The following table summarizes the ops and the order in which the worker instance receives them:
Existing component | Non-existent component | |
---|---|---|
Gaining write access authority | 1. AddComponentOp 2. AuthorityChangeOp ( kAuthoritative ) |
1. RemoveComponentOp 2. AuthorityChangeOp ( kAuthoritative ) |
Losing write access authority | 1. AuthorityChangeOp (kNotAuthoritative ) 2. AddComponentOp |
1. AuthorityChangeOp (kNotAuthoritative ) 2. RemoveComponentOp |
Example
Imagine you have a component which is used to temporarily give super strength to a player:
component SuperStrength {
id = 2345;
int32 power_level = 1;
}
The worker instance which has write access authority over the write ACL of a given entity can give a worker instance write access authority over the SuperStrength
component,
as described in the example of changing authority.
Example of adding a component
The worker instance which has write access authority over the SuperStrength
component can add it to the entity:
public static void AddSuperStrengthComponentToEntity(Connection connection, Improbable.EntityId entityId) {
var componentData = new SuperStrength.Data(SuperStrengthData.Create());
componentData.Value.powerLevel = 100;
connection.SendAddComponent(entityId, componentData, new UpdateParameters{ Loopback = ComponentUpdateLoopback.ShortCircuited });
}
Example of removing a component
The worker instance which has write access authority over the SuperStrength
component can remove it from the entity:
public static void RemoveSuperStrengthComponentFromEntity(Connection connection, Improbable.EntityId entityId) {
connection.SendRemoveComponent<SuperStrength>(entityId, new UpdateParameters{ Loopback = ComponentUpdateLoopback.ShortCircuited });
}