Access data on the main thread
How you access data in a system depends on whether you’ve used a managed SystemBase system, or an unmanaged ISystem system. The following are ways of accessing the data in a system:
- SystemAPI: Calls the data you can get from
SystemState, but caches and updates the data for you, meaning that you can useSystemAPImethods directly in anUpdateloop. Because you can directly use these methods inUpdate, there's no runtime overhead of usingSystemAPI. However,SystemAPIworks via codegen, so if you want to avoid some of the iteration time penalty associated with codegen,SystemStatemight be preferable. - SystemState: Use the properties and methods in
SystemStateto access raw entity state data inISystemsystems.SystemBaseandSystemAPInatively use the data inSystemState. - SystemBase: Contains the same methods as
SystemState, but you can call them from aSystemBasesystem.
SystemAPI
SystemAPI is a class that provides caching and utility methods for accessing data in an entity's world. It works in non-static methods in SystemBase and non-static methods in ISystem that take ref SystemState as a parameter. Because you can directly use these methods in Update, there's no runtime cost to using SystemAPI, so use SystemAPI to access data, wherever possible, unless you are concerned with codegen. Because SystemAPI works via codegen it has some associated iteration time penalties, so you can use SystemState instead to avoid this.
For more information, refer to the SystemAPI overview documentation.
SystemState
You can use SystemState to get data in the following ways:
- Find out information about worlds
- Query a system to get information about it
- Get data which to add as a dependency of the system. This is similar to the way you get data with EntityManager, but with added dependencies.
For more information, refer to the SystemState API documentation.
SystemBase
All the methods in SystemState are available in SystemBase, and they're prefixed with this. rather than state.