Error adding function as system
You can sometimes get confusing arcane compiler errors when you try to add systems to your Bevy app.
The errors can look like this:
the trait bound `for<'r, 's, 't0> fn(bevy::prelude::Query<'r, 's, (&'t0 Param)) {my_system}: IntoSystem<(), (), _>` is not satisfied
This is caused by your function having incompatible parameters. Bevy can only accept special types as system parameters.
You might also errors that look like this:
the trait bound `Component: WorldQuery` is not satisfied
the trait `WorldQuery` is not implemented for `Component`
this struct takes at most 2 type arguments but 3 type arguments were supplied
These errors are caused by a malformed query.
Common beginner mistakes
- Using
&mut Commands
(bevy 0.4 syntax) instead ofCommands
. - Using
Query<MyStuff>
instead ofQuery<&MyStuff>
orQuery<&mut MyStuff>
. - Using
Query<&ComponentA, &ComponentB>
instead ofQuery<(&ComponentA, &ComponentB)>
(forgetting the tuple) - Using your resource types directly without
Res
orResMut
. - Using your component types directly without putting them in a
Query
. - Using other arbitrary types in your function.
Note that Query<Entity>
is correct, because the Entity ID is special;
it is not a component.
Supported types
Only the following types are supported as system parameters:
In regular systems:
Commands
: Manipulate the ECS using commandsRes<T>
: Shared access to a resourceResMut<T>
: Exclusive (mutable) access to a resourceOption<Res<T>>
: Shared access to a resource that may not existOption<ResMut<T>>
: Exclusive (mutable) access to a resource that may not existQuery<T, F = ()>
(can contain tuples of up to 15 types): Access to entities and componentsParamSet
(with up to 8 params): Resolve conflicts between incompatible system parametersLocal<T>
: Data local to the systemEventReader<T>
: Receive eventsEventWriter<T>
: Send eventsRemovedComponents<T>
: Removal detectionNonSend<T>
: Shared access to Non-Send
(main thread only) dataNonSendMut<T>
: Mut access to Non-Send
(main thread only) dataParallelCommands
: Abstraction to help useCommands
when you will do your own parallelismSystemName
: The name (string) of the system, may be useful for debugging&World
: Read-only direct access to the ECS WorldEntities
: Low-level ECS metadata: All entitiesComponents
: Low-level ECS metadata: All componentsBundles
: Low-level ECS metadata: All bundlesArchetypes
: Low-level ECS metadata: All archetypesSystemChangeTick
: Low-level ECS metadata: Tick used for change detectionStaticSystemParam
: Helper for generic system abstractions, to avoid lifetime annotations- tuples containing any of these types, with up to 16 members
&mut World
: Full direct access to the ECS WorldLocal<T>
: Data local to the systemSystemState<P>
: Emulates a regular system, allowing you to easily access data from the World.P
are the system parameters.QueryState<Q, F = ()>
: Allows you to perform queries on the World, similar to aQuery
in regular systems.
Your function can have a maximum of 16 total parameters. If you need more, group them into tuples to work around the limit. Tuples can contain up to 16 members, but can be nested indefinitely.
Systems running during the Extract stage can also use
Extract<T>
, to access data from the Main World instead of the
Render World. T
can be any other system parameter type.