Bevy Version:0.9(outdated!)

Direct World Access

The World is where Bevy ECS stores all data and associated metadata. It keeps track of resources, entities and components.

Typically, the App's schedule runner will run all stages (which, in turn, run their systems) on the main world. Regular systems are limited in what data they can access from the world, by their system parameter types. Operations that manipulate the world itself are only done indirectly using Commands. This is how most typical Bevy user code behaves.

However, there are also ways you can get full direct access to the world, which gives you full control and freedom to do anything with any data stored in the Bevy ECS:

Direct world access lets you do things like:

  • Freely spawn/despawn entities, insert/remove resources, etc., taking effect immediately (no delay like when using Commands from a regular system)
  • Access any component, entities, and resources you want
  • Manually run arbitrary systems or stages

This is especially useful if you want to do things that do not fit within Bevy's typical execution model/flow of just running systems once every frame (organized with stages and labels).

With direct world access, you can implement custom control flow, like looping some systems multiple times, selecting different systems to run in different circumstances, exporting/importing data from files like scenes or game saves, …

Working with the World

Here are some ways that you can make use of the direct world access APIs.

SystemState

The easiest way to do things is using a SystemState.

This is a type that "imitates a system", behaving the same way as a system with various parameters would. All the same behaviors like queries, change detection, and even Commands are available. You can use any system params.

It also tracks any persistent state, used for things like change detection or caching to improve performance. Therefore, if you plan on reusing the same SystemState multiple times, you should store it somewhere, rather than creating a new one every time. Every time you call .get(world), it behaves like another "run" of a system.

If you are using Commands, you can choose when you want to apply them to the world. You need to manually call .apply(world) on the SystemState, to apply them.

// TODO: write code example

Running a Stage

If you want to run some systems (a common use-case is testing), the easiest way is to construct an impromptu SystemStage (stages). This way you reuse all the scheduling logic that Bevy normally does when running systems.

// TODO: write code example

The world contains a lot of metadata that allows navigating all the data efficiently, such as information about all the stored components, entities, archeypes.

// TODO: write code example