docs.unity3d.com
Search Results for

    Show / Hide Table of Contents

    Structural changes concepts

    Operations that cause Unity to reorganize chunks of memory or the contents of chunks in memory are called structural changes. It's important to be aware of which operations are structural changes because they can be resource-intensive and you can only perform them on the main thread; not from jobs.

    The following operations are considered structural changes:

    • Creating or destroying an entity.
    • Adding or removing components.
    • Setting a shared component value.

    Create an entity

    When you create an entity, Unity either adds the entity to an existing chunk or, if no chunks are available for the entity's archetype, creates a new chunk and adds the entity to that.

    Destroy an entity

    When you destroy an entity, Unity removes the entity from its chunk. If removing the entity leaves a gap in the chunk, Unity moves the last entity in the chunk to fill the gap. If removing the entity leaves the chunk empty, Unity deallocates the chunk.

    Add or remove components

    When you add or remove components from an entity, you change the entity's archetype. Unity stores each entity in a chunk that matches the entity's archetype. This means that if you change an entity's archetype, Unity must move the entity to another chunk. If a suitable chunk doesn't exist, Unity creates a new one. If the move leaves the previous chunk with a gap or leaves it empty, Unity moves the last entity in the chunk to fill the gap or deallocates the chunk respectively.

    Set a shared component value

    When you set the value of an entity's shared component, Unity moves the entity to a chunk that matches the new shared component value. If a suitable chunk doesn't exist, Unity creates a new one. If the move leaves the previous chunk either with a gap or empty, Unity moves the last entity in the chunk to fill the gap or deallocates the chunk respectively.

    Note

    Setting a regular component value isn't a structural change because it doesn't require Unity to move the entity.

    Sync points

    You can't make structural changes directly in a job because it might invalidate other jobs that are already scheduled, and creates a sync point.

    A synchronization point (sync point) is a point in program execution that waits for the completion of all jobs that have been scheduled so far. Sync points limit your ability to use all worker threads available in the job system for a period of time. As such, you should aim to avoid sync points. Structural changes to the data in ECS are the primary cause of sync points.

    Structural changes not only require a sync point, but they also invalidate all direct references to any component data. This includes instances of DynamicBuffer and the result of methods that provide direct access to the components such as ComponentSystemBase.GetComponentDataFromEntity.

    Avoiding sync points

    You can use entity command buffers to queue up structural changes instead of performing them instantly. You can play back commands stored in an entity command buffer at a later point during the frame. This reduces multiple sync points spread across the frame to a single sync point.

    Each of the standard ComponentSystemGroup instances provide an EntityCommandBufferSystem as the first and last systems updated in the group. If you get an entity command buffer object from one of these standard systems, all structural changes happen at the same point in the frame, which results in one sync point. You can also use entity command buffers to record structural changes within a job, rather than only making structural changes on the main thread.

    If you can't use an entity command buffer for a task, group any systems that make structural changes together in the system execution order. Two systems that both make structural changes only create one sync point if they update sequentially.

    Additional resources

    • Archetype concepts
    • Entity command buffers
    • System update order
    • Shared components

    Did you find this page useful? Please give it a rating:

    Thanks for rating this page!

    Report a problem on this page

    What kind of problem would you like to report?

    • This page needs code samples
    • Code samples do not work
    • Information is missing
    • Information is incorrect
    • Information is unclear or confusing
    • There is a spelling/grammar error on this page
    • Something else

    Thanks for letting us know! This page has been marked for review based on your feedback.

    If you have time, you can provide more information to help us fix the problem faster.

    Provide more information

    You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:

    You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:

    You've told us there is information missing from this page. Please tell us more about what's missing:

    You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:

    You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:

    You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:

    You've told us this page has a problem. Please tell us more about what's wrong:

    Thank you for helping to make the Unity documentation better!

    Your feedback has been submitted as a ticket for our documentation team to review.

    We are not able to reply to every ticket submitted.

    In This Article
    • Create an entity
    • Destroy an entity
    • Add or remove components
    • Set a shared component value
    • Sync points
      • Avoiding sync points
    • Additional resources
    Back to top
    Copyright © 2025 Unity Technologies — Trademarks and terms of use
    • Legal
    • Privacy Policy
    • Cookie Policy
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)