Iterate over data with Entities.ForEach
If you use the SystemBase
class to create your systems, you can use the Entities.ForEach
construction to define and execute algorithms over entities and their components. At compile time, Unity translates each ForEach
call into a generated job.
You pass Entities.ForEach
a lambda expression, and Unity generates an entity query based on the lambda parameter types. When the generated job runs, Unity calls the lambda expression once for each entity that matches the query. ForEachLambdaJobDescription
represents this generated job.
If you use ISystem
to create your systems, use SystemAPI.Query
to iterate over system data. Entities.ForEach
has four times slower compilation time than SystemAPI.Query
and IJobEntity
, so you should consider using those methods to iterate over data instead.
Supported features
Use Run()
to execute the lambda expression on the main thread. You can also use Schedule
to execute it as a single job, or ScheduleParallel
to execute it as a parallel job. These different execution methods have different constraints on how you access data. Also, the Burst compiler uses a restricted subset of the C# language, so you need to specify WithoutBurst
if you want to use C# features outside this subset. This includes accessing managed types.
The following table shows which features are supported in Entities.ForEach
for the different methods of scheduling available in SystemBase
:
Supported feature | Run method | Schedule method | ScheduleParallel method |
---|---|---|---|
Capture local value type | Supported | Supported | Supported |
Capture local reference type | Supported only WithoutBurst and not in ISystem |
Unsupported | Unsupported |
Writing to captured variables | Supported | Unsupported | Unsupported |
Use field on the system class | Supported only WithoutBurst |
Unsupported | Unsupported |
Methods on reference types | Supported only WithoutBurst and not in ISystem |
Unsupported | Unsupported |
Shared components | Supported only WithoutBurst and not in ISystem |
Unsupported | Unsupported |
Managed components | Supported only WithoutBurst and not in ISystem |
Unsupported | Unsupported |
Structural changes | Supported only WithStructuralChanges and not in ISystem |
Unsupported | Unsupported |
SystemBase.GetComponent |
Supported | Supported | Supported |
SystemBase.SetComponent |
Supported | Supported | Unsupported |
GetComponentDataFromEntity |
Supported | Supported | Supported only as ReadOnly |
HasComponent |
Supported | Supported | Supported |
WithDisposeOnCompletion |
Supported | Supported | Supported |
WithScheduleGranularity |
Unsupported | Unsupported | Supported |
WithDeferredPlaybackSystem |
Supported | Supported | Supported |
WithImmediatePlayback |
Supported | Unsupported | Unsupported |
HasBuffer |
Supported | Supported | Supported |
SystemBase.GetStorageInfoFromEntity |
Supported | Supported | Supported |
SystemBase.Exists |
Supported | Supported | Supported |
Important
WithStructuralChanges
disables Burst. Don't use this option if you want to achieve high levels of performance with Entities.ForEach
. If you want to use this option, use an entity command buffer instead.
An Entities.ForEach
construction uses Roslyn source generators to translate the code you write for the construction into correct ECS code. This translation means you can express the intent of your algorithm without having to include complex, boilerplate code. However, it means that some common ways of writing code aren't allowed.
The following features aren't supported:
- Dynamic code in
.With
invocations SharedComponent
parametersby ref
- Nested
Entities.ForEach
lambda expressions - Calling with a delegate stored in a variable, field, or by method
SetComponent
with lambda parameter typeGetComponent
with writable lambda parameter- Generic parameters in lambdas
- In systems with generic parameters
Dependencies
By default, a system uses its Dependency
property to manage its ECS-related dependencies. The system adds each job created with Entities.ForEach
and Job.WithCode
to the Dependency
job handle in the order that they appear in the OnUpdate
method. You can also pass a JobHandle
to your Schedule
methods to manage job dependencies manually, which then returns the resulting dependency. For more information, refer to the Dependency
documentation.
Refer to Job dependencies for more general information about job dependencies.