Entity Variables
Entity Variables allow ECS Actions and Conditions to share values through an entity’s SharedVariableElement buffer. Use this pattern when ECS state logic needs to read or update a Shared Variable, such as storing the Entity selected as a target.
The value type must be unmanaged and no larger than 16 bytes. The example below uses SharedVariable<Entity>.
Authoring setup
These excerpts belong in an Entity Action derived from ECSAction<TSystem, FindTargetComponent, FindTargetFlag>; they are not standalone scripts. Declare the Shared Variable and a typed ECSSharedVariableIndex<Entity> in that Action. Register the Shared Variable in AddBufferElement, then retain the returned index for the runtime component:
using Opsive.GraphDesigner.Runtime.Variables;
using Unity.Entities;
using UnityEngine;
[Tooltip("The entity that should be targeted.")]
[SerializeField] SharedVariable<Entity> m_TargetEntity;
private ECSSharedVariableIndex<Entity> m_TargetEntityIndex;
/// <summary>
/// Registers the target SharedVariable and adds the buffer element to the entity.
/// </summary>
/// <param name="world">The world that the entity exists in.</param>
/// <param name="entity">The entity that the IBufferElementData should be assigned to.</param>
/// <param name="registry">The ECS variable registry for registering SharedVariable fields.</param>
/// <param name="gameObject">The GameObject that the entity is attached to.</param>
/// <param name="stateMachineID">The ID of the state machine running the state.</param>
/// <param name="index">The runtime index of the state.</param>
/// <returns>The index of the element within the buffer.</returns>
public override int AddBufferElement(World world, Entity entity, ECSVariableRegistry registry, GameObject gameObject, int stateMachineID, ushort index)
{
m_TargetEntityIndex = new ECSSharedVariableIndex<Entity>(registry.Register(m_TargetEntity));
return base.AddBufferElement(world, entity, registry, gameObject, stateMachineID, index);
}
Store the integer buffer index in the Action’s runtime component so its ECS system can locate the value for each entity:
using Unity.Entities;
using UnityEngine;
public override FindTargetComponent GetBufferElement()
{
return new FindTargetComponent {
Index = RuntimeIndex,
TargetEntityVariableIndex = m_TargetEntityIndex.Index,
};
}
Declare the runtime buffer component outside the authoring class:
using Unity.Entities;
using UnityEngine;
/// <summary>
/// The DOTS data structure for the FindTarget struct.
/// </summary>
public struct FindTargetComponent : IBufferElementData
{
[Tooltip("The index of the node.")]
public ushort Index;
[Tooltip("Buffer index into SharedVariableElement for the target entity.")]
public int TargetEntityVariableIndex;
}
How it runs
During State Machine initialization, ECSVariableRegistry.Register assigns the Shared Variable a stable buffer index. The registry then bakes its initial value into the entity’s SharedVariableElement buffer.
Inside the system’s OnUpdate, include DynamicBuffer<SharedVariableElement> in the query. FindTargetFlag is the enableable flag declared by your Entity Action. Read the value with Get<T>(index) and write it with Set(index, value):
using Opsive.GraphDesigner.Runtime.Variables;
using Opsive.StateDesigner.Runtime.Components;
using Unity.Entities;
foreach (var (stateComponents, findTargetComponents, sharedVariables) in
SystemAPI.Query<DynamicBuffer<StateComponent>, DynamicBuffer<FindTargetComponent>, DynamicBuffer<SharedVariableElement>>()
.WithAll<FindTargetFlag, EvaluateFlag>()) {
for (int i = 0; i < findTargetComponents.Length; ++i) {
var findTargetComponent = findTargetComponents[i];
var targetEntity = sharedVariables.Get<Entity>(findTargetComponent.TargetEntityVariableIndex);
// Find or update the target Entity here.
sharedVariables.Set(findTargetComponent.TargetEntityVariableIndex, targetEntity);
}
}
Other ECS Actions or Conditions that reference the same Shared Variable can use its registered buffer value without storing a managed object in their runtime component.
- Value type: Use only unmanaged values that fit within the 16-byte
SharedVariableElementlimit. - Scope: Shared Variable names and scopes still determine which value is shared. Use Graph scope for one State Machine graph, or choose a broader scope only when other graphs need the same value.
- Runtime storage: Store the registered integer index in the ECS component. Read and write the value through
DynamicBuffer<SharedVariableElement>rather than placing the managed Shared Variable in ECS data. - Access: Use
Get<T>(index)when the system only needs the current value andSet(index, value)when it changes that value for other state logic.
In Play Mode:
Run the State Machine and confirm that:
- Registration returns a valid buffer index for the Shared Variable.
- The ECS system can read the initial value from
SharedVariableElement. - A value written with
Setis returned by the nextGetusing the same index.
If registration fails, confirm that the Shared Variable is assigned and its value type is unmanaged and no larger than 16 bytes. If the system cannot access the value, confirm that its query includes DynamicBuffer<SharedVariableElement> and the expected Action or Condition flags.
Related: