docs/bevy/examples/ecs/custom_query_param.rs 7.6 K · 227 lines · raw · history

1 //! This example illustrates the usage of the [`QueryData`] derive macro, which allows
2 //! defining custom query and filter types.
3 //!
4 //! While regular tuple queries work great in most of simple scenarios, using custom queries
5 //! declared as named structs can bring the following advantages:
6 //! - They help to avoid destructuring or using `q.0, q.1, ...` access pattern.
7 //! - Adding, removing components or changing items order with structs greatly reduces maintenance
8 //! burden, as you don't need to update statements that destructure tuples, care about order
9 //! of elements, etc. Instead, you can just add or remove places where a certain element is used.
10 //! - Named structs enable the composition pattern, that makes query types easier to re-use.
11 //! - You can bypass the limit of 15 components that exists for query tuples.
12 //!
13 //! For more details on the [`QueryData`] derive macro, see the trait documentation.
14
15 use bevy::{
16 ecs::query::{QueryData, QueryFilter},
17 prelude::*,
18 };
19 use std::fmt::Debug;
20
21 fn main() {
22 App::new()
23 .add_systems(Startup, spawn)
24 .add_systems(
25 Update,
26 (
27 print_components_read_only,
28 print_components_iter_mut,
29 print_components_iter,
30 print_components_tuple,
31 print_components_contiguous_iter,
32 )
33 .chain(),
34 )
35 .run();
36 }
37
38 #[derive(Component, Debug)]
39 struct ComponentA;
40 #[derive(Component, Debug)]
41 struct ComponentB;
42 #[derive(Component, Debug)]
43 struct ComponentC;
44 #[derive(Component, Debug)]
45 struct ComponentD;
46 #[derive(Component, Debug)]
47 struct ComponentZ;
48
49 #[derive(QueryData)]
50 #[query_data(derive(Debug))]
51 struct ReadOnlyCustomQuery<T: Component + Debug, P: Component + Debug> {
52 entity: Entity,
53 a: &'static ComponentA,
54 b: Option<&'static ComponentB>,
55 nested: NestedQuery,
56 optional_nested: Option<NestedQuery>,
57 optional_tuple: Option<(&'static ComponentB, &'static ComponentZ)>,
58 generic: GenericQuery<T, P>,
59 empty: EmptyQuery,
60 }
61
62 fn print_components_read_only(
63 query: Query<
64 ReadOnlyCustomQuery<ComponentC, ComponentD>,
65 CustomQueryFilter<ComponentC, ComponentD>,
66 >,
67 ) {
68 println!("Print components (read_only):");
69 for e in &query {
70 println!("Entity: {}", e.entity);
71 println!("A: {:?}", e.a);
72 println!("B: {:?}", e.b);
73 println!("Nested: {:?}", e.nested);
74 println!("Optional nested: {:?}", e.optional_nested);
75 println!("Optional tuple: {:?}", e.optional_tuple);
76 println!("Generic: {:?}", e.generic);
77 }
78 println!();
79 }
80
81 /// If you are going to mutate the data in a query, you must mark it with the `mutable` attribute.
82 ///
83 /// The [`QueryData`] derive macro will still create a read-only version, which will be have `ReadOnly`
84 /// suffix.
85 /// Note: if you want to use derive macros with read-only query variants, you need to pass them with
86 /// using the `derive` attribute.
87 #[derive(QueryData)]
88 #[query_data(mutable, derive(Debug))]
89 struct CustomQuery<T: Component + Debug, P: Component + Debug> {
90 entity: Entity,
91 a: &'static mut ComponentA,
92 b: Option<&'static mut ComponentB>,
93 nested: NestedQuery,
94 optional_nested: Option<NestedQuery>,
95 optional_tuple: Option<(NestedQuery, &'static mut ComponentZ)>,
96 generic: GenericQuery<T, P>,
97 empty: EmptyQuery,
98 }
99
100 // This is a valid query as well, which would iterate over every entity.
101 #[derive(QueryData)]
102 #[query_data(derive(Debug))]
103 struct EmptyQuery {
104 empty: (),
105 }
106
107 #[derive(QueryData)]
108 #[query_data(derive(Debug))]
109 struct NestedQuery {
110 c: &'static ComponentC,
111 d: Option<&'static ComponentD>,
112 }
113
114 #[derive(QueryData)]
115 #[query_data(derive(Debug), contiguous(mutable))]
116 struct GenericQuery<T: Component, P: Component> {
117 generic: (&'static T, &'static P),
118 }
119
120 #[derive(QueryFilter)]
121 struct CustomQueryFilter<T: Component, P: Component> {
122 _c: With<ComponentC>,
123 _d: With<ComponentD>,
124 _or: Or<(Added<ComponentC>, Changed<ComponentD>, Without<ComponentZ>)>,
125 _generic_tuple: (With<T>, With<P>),
126 }
127
128 fn spawn(mut commands: Commands) {
129 commands.spawn((ComponentA, ComponentB, ComponentC, ComponentD));
130 }
131
132 fn print_components_iter_mut(
133 mut query: Query<
134 CustomQuery<ComponentC, ComponentD>,
135 CustomQueryFilter<ComponentC, ComponentD>,
136 >,
137 ) {
138 println!("Print components (iter_mut):");
139 for e in &mut query {
140 // Re-declaring the variable to illustrate the type of the actual iterator item.
141 let e: CustomQueryItem<'_, '_, _, _> = e;
142 println!("Entity: {}", e.entity);
143 println!("A: {:?}", e.a);
144 println!("B: {:?}", e.b);
145 println!("Optional nested: {:?}", e.optional_nested);
146 println!("Optional tuple: {:?}", e.optional_tuple);
147 println!("Nested: {:?}", e.nested);
148 println!("Generic: {:?}", e.generic);
149 }
150 println!();
151 }
152
153 fn print_components_iter(
154 query: Query<CustomQuery<ComponentC, ComponentD>, CustomQueryFilter<ComponentC, ComponentD>>,
155 ) {
156 println!("Print components (iter):");
157 for e in &query {
158 // Re-declaring the variable to illustrate the type of the actual iterator item.
159 let e: CustomQueryReadOnlyItem<'_, '_, _, _> = e;
160 println!("Entity: {}", e.entity);
161 println!("A: {:?}", e.a);
162 println!("B: {:?}", e.b);
163 println!("Nested: {:?}", e.nested);
164 println!("Generic: {:?}", e.generic);
165 }
166 println!();
167 }
168
169 type NestedTupleQuery<'w> = (&'w ComponentC, &'w ComponentD);
170 type GenericTupleQuery<'w, T, P> = (&'w T, &'w P);
171
172 fn print_components_tuple(
173 query: Query<
174 (
175 Entity,
176 &ComponentA,
177 &ComponentB,
178 NestedTupleQuery,
179 GenericTupleQuery<ComponentC, ComponentD>,
180 ),
181 (
182 With<ComponentC>,
183 With<ComponentD>,
184 Or<(Added<ComponentC>, Changed<ComponentD>, Without<ComponentZ>)>,
185 ),
186 >,
187 ) {
188 println!("Print components (tuple):");
189 for (entity, a, b, nested, (generic_c, generic_d)) in &query {
190 println!("Entity: {entity}");
191 println!("A: {a:?}");
192 println!("B: {b:?}");
193 println!("Nested: {:?} {:?}", nested.0, nested.1);
194 println!("Generic: {generic_c:?} {generic_d:?}");
195 }
196 println!();
197 }
198
199 /// If you are going to contiguously iterate the data in a query, you must mark it with the `contiguous` attribute,
200 /// which accepts one of 3 targets (`all`, `immutable` and `mutable`)
201 ///
202 /// - `all` will make read only query as well as mutable query both be able to be iterated contiguosly
203 /// - `mutable` will only make the original query (i.e., in that case [`CustomContiguousQuery`]) be able to be iterated contiguously
204 /// - `immutable` will only make the read only query (which is only useful when you mark the original query as `mutable`)
205 /// be able to be iterated contiguously
206 #[derive(QueryData)]
207 #[query_data(derive(Debug), contiguous(all))]
208 struct CustomContiguousQuery<T: Component + Debug, P: Component + Debug> {
209 entity: Entity,
210 a: Ref<'static, ComponentA>,
211 b: Option<&'static ComponentB>,
212 generic: GenericQuery<T, P>,
213 }
214
215 fn print_components_contiguous_iter(query: Query<CustomContiguousQuery<ComponentC, ComponentD>>) {
216 println!("Print components (contiguous_iter):");
217 for e in query.contiguous_iter().unwrap() {
218 let e: CustomContiguousQueryContiguousItem<'_, '_, _, _> = e;
219 println!("Entity: {:?}", e.entity);
220 println!("A: {:?}", e.a);
221 println!("B: {:?}", e.b);
222 println!(
223 "Generic: {:?} {:?}",
224 e.generic.generic.0, e.generic.generic.1
225 );
226 }
227 }