Singleton components
A singleton component is a component that has only one instance in a given world. For example, if only one entity in a world has a component of type T
, then T
is a singleton component.
If a singleton component is added to another entity, then it's no longer a singleton component. Additionally, a singleton component can exist in another world, without affecting its singleton state.
Singleton component APIs
The Entities package contains several APIs you can use to work with singleton components:
It's useful to use the singleton component APIs in situations where you know that there's only one instance of a component. For example, if you have a single-player application and only need one instance of a PlayerController
component, you can use the singleton APIs to simplify your code. Additionally, in server-based architecture, client-side implementations typically track timestamps for their instance only, so the singleton APIs are convenient and simplify a lot of hand written code.
Dependency completion
Singleton components have special-case behavior in dependency completion in systems code. With normal component access, APIs such as EntityManager.GetComponentData or SystemAPI.GetComponent ensure that any running jobs that might write to the same component data on a worker thread are completed before returning the requested data.
However, singleton API calls don't ensure that running jobs are completed first. The Jobs Debugger logs an error on invalid access, and you either need to manually complete dependencies with EntityManager.CompleteDependencyBeforeRO or EntityManager.CompleteDependencyBeforeRW, or you need to restructure the data dependencies.
You should also be careful if you use GetSingletonRW to get read/write access to components. Because a reference to component data is returned, it's possible to modify data while jobs are also reading or writing it. The best practices for GetSingletonRW are:
- Only use to access a
NativeContainer
in a component. This is because native containers have their own safety mechanisms compatible with Jobs Debugger, separate from ECS component safety mechanisms.
- Check the Jobs Debugger for errors. Any errors indicate a dependency issue that you need to either restructure or manually complete.
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
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.