1use std::{error::Error, fmt};
4
5use bevy_ecs::{
6 bundle::{Bundle, NoBundleEffect},
7 prelude::Resource,
8 world::World,
9};
10
11use crate::{
12 component::{ApprovedComponents, ComponentApprovalError, validate_resource},
13 identity::{ApplicationId, LogicEntity, ManagedEntity, WorldGeneration},
14};
15
16#[derive(Debug)]
18pub enum WorldBuildError {
19 Component(ComponentApprovalError),
21 EntityLimitExceeded {
23 limit: usize,
25 },
26 ForeignEntity {
28 entity: LogicEntity,
30 },
31 MissingEntity {
33 entity: LogicEntity,
35 },
36 User {
38 message: String,
40 },
41}
42
43impl WorldBuildError {
44 pub fn user(message: impl Into<String>) -> Self {
46 Self::User {
47 message: message.into(),
48 }
49 }
50}
51
52impl fmt::Display for WorldBuildError {
53 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
54 match self {
55 Self::Component(error) => write!(formatter, "candidate value was rejected: {error}"),
56 Self::EntityLimitExceeded { limit } => {
57 write!(formatter, "candidate exceeds its entity limit of {limit}")
58 }
59 Self::ForeignEntity { entity } => {
60 write!(formatter, "entity {entity:?} belongs to another candidate")
61 }
62 Self::MissingEntity { entity } => {
63 write!(
64 formatter,
65 "entity {entity:?} is not alive in this candidate"
66 )
67 }
68 Self::User { message } => formatter.write_str(message),
69 }
70 }
71}
72
73impl Error for WorldBuildError {
74 fn source(&self) -> Option<&(dyn Error + 'static)> {
75 match self {
76 Self::Component(error) => Some(error),
77 _ => None,
78 }
79 }
80}
81
82pub struct WorldBuilder {
88 world: World,
89 approved: ApprovedComponents,
90 application: ApplicationId,
91 generation: WorldGeneration,
92 entity_limit: usize,
93 managed_entities: usize,
94}
95
96impl WorldBuilder {
97 pub(crate) fn new(
98 world: World,
99 approved: ApprovedComponents,
100 application: ApplicationId,
101 generation: WorldGeneration,
102 entity_limit: usize,
103 ) -> Self {
104 Self {
105 world,
106 approved,
107 application,
108 generation,
109 entity_limit,
110 managed_entities: 0,
111 }
112 }
113
114 pub fn spawn<B>(&mut self, bundle: B) -> Result<LogicEntity, WorldBuildError>
123 where
124 B: Bundle<Effect: NoBundleEffect>,
125 {
126 self.validate_spawn_bundle::<B>()?;
127 self.ensure_spawn_capacity(1)?;
128 Ok(self.spawn_validated(bundle))
129 }
130
131 pub fn spawn_array<B, const N: usize>(
145 &mut self,
146 bundles: [B; N],
147 ) -> Result<[LogicEntity; N], WorldBuildError>
148 where
149 B: Bundle<Effect: NoBundleEffect>,
150 {
151 self.validate_spawn_bundle::<B>()?;
152 self.ensure_spawn_capacity(N)?;
153 Ok(bundles.map(|bundle| self.spawn_validated(bundle)))
154 }
155
156 fn validate_spawn_bundle<B>(&mut self) -> Result<(), WorldBuildError>
157 where
158 B: Bundle<Effect: NoBundleEffect>,
159 {
160 self.approved
161 .validate_bundle::<B>(&mut self.world)
162 .map_err(WorldBuildError::Component)
163 }
164
165 fn ensure_spawn_capacity(&self, additional: usize) -> Result<(), WorldBuildError> {
166 let Some(requested) = self.managed_entities.checked_add(additional) else {
167 return Err(WorldBuildError::EntityLimitExceeded {
168 limit: self.entity_limit,
169 });
170 };
171 if requested > self.entity_limit {
172 return Err(WorldBuildError::EntityLimitExceeded {
173 limit: self.entity_limit,
174 });
175 }
176 Ok(())
177 }
178
179 fn spawn_validated<B>(&mut self, bundle: B) -> LogicEntity
180 where
181 B: Bundle<Effect: NoBundleEffect>,
182 {
183 let managed = ManagedEntity::for_generation(self.generation);
184 let entity = self.world.spawn((bundle, managed)).id();
185 let identity = managed.handle(entity);
186 self.managed_entities += 1;
187 identity
188 }
189
190 pub fn despawn(&mut self, entity: LogicEntity) -> Result<(), WorldBuildError> {
192 if entity.application() != self.application || entity.world_generation() != self.generation
193 {
194 return Err(WorldBuildError::ForeignEntity { entity });
195 }
196 if !self
197 .world
198 .get::<ManagedEntity>(entity.entity())
199 .is_some_and(|managed| managed.handle(entity.entity()) == entity)
200 {
201 return Err(WorldBuildError::MissingEntity { entity });
202 }
203 let Some(managed_entities) = self.managed_entities.checked_sub(1) else {
204 debug_assert!(false, "candidate managed-entity count is inconsistent");
205 return Err(WorldBuildError::MissingEntity { entity });
206 };
207 let removed = self.world.despawn(entity.entity());
208 debug_assert!(removed, "validated candidate entity disappeared");
209 self.managed_entities = managed_entities;
210 Ok(())
211 }
212
213 pub fn insert_resource<R: Resource>(
219 &mut self,
220 resource: R,
221 ) -> Result<&mut Self, WorldBuildError> {
222 validate_resource::<R>(&mut self.world).map_err(WorldBuildError::Component)?;
223 self.world.insert_resource(resource);
224 Ok(self)
225 }
226
227 pub const fn generation(&self) -> WorldGeneration {
229 self.generation
230 }
231
232 pub(crate) fn finish(self) -> (World, ApprovedComponents, usize) {
233 (self.world, self.approved, self.managed_entities)
234 }
235}
236
237#[cfg(test)]
238mod tests {
239 use std::sync::{
240 Arc,
241 atomic::{AtomicUsize, Ordering},
242 };
243
244 use bevy_ecs::{
245 entity_disabling::Disabled,
246 lifecycle::HookContext,
247 prelude::{Component, Resource},
248 world::DeferredWorld,
249 };
250
251 use crate::component::{ComponentRegistry, LifecycleHook};
252
253 use super::*;
254
255 #[derive(Component)]
256 struct Marker;
257
258 #[derive(Component)]
259 struct Unapproved;
260
261 #[derive(Component)]
262 struct Indexed(u8);
263
264 #[derive(Component)]
265 #[require(RequiredValue)]
266 struct NeedsRequired;
267
268 #[derive(Component, Debug, Default, PartialEq, Eq)]
269 struct RequiredValue(u8);
270
271 #[derive(Component)]
272 struct DropProbe(Arc<AtomicUsize>);
273
274 impl Drop for DropProbe {
275 fn drop(&mut self) {
276 self.0.fetch_add(1, Ordering::SeqCst);
277 }
278 }
279
280 #[derive(Debug, Resource, PartialEq, Eq)]
281 struct Setting(u8);
282
283 fn on_resource_add(_world: DeferredWorld<'_>, _context: HookContext) {}
284
285 #[derive(Resource)]
286 #[component(on_add = on_resource_add)]
287 struct HookedSetting;
288
289 #[derive(Component, Default)]
290 struct RequiredSettingPart;
291
292 #[derive(Resource)]
293 #[require(RequiredSettingPart)]
294 struct SettingWithRequiredComponent;
295
296 fn builder_from_registry(limit: usize, registry: ComponentRegistry) -> WorldBuilder {
297 let application = ApplicationId::from_raw(1);
298 let generation = WorldGeneration::new(application, 3);
299 let mut world = World::new();
300 let approved = match registry.install(&mut world) {
301 Ok(approved) => approved,
302 Err(error) => panic!("unexpected approval error: {error}"),
303 };
304 WorldBuilder::new(world, approved, application, generation, limit)
305 }
306
307 fn builder(limit: usize) -> WorldBuilder {
308 let mut registry = ComponentRegistry::default();
309 assert!(registry.approve::<Marker>().is_ok());
310 assert!(registry.approve::<Disabled>().is_ok());
311 builder_from_registry(limit, registry)
312 }
313
314 #[test]
315 fn managed_spawn_assigns_candidate_generation() {
316 let mut builder = builder(1);
317 let entity = builder.spawn(Marker);
318 let entity = match entity {
319 Ok(entity) => entity,
320 Err(error) => panic!("unexpected spawn error: {error}"),
321 };
322
323 assert_eq!(entity.world_generation(), builder.generation());
324 assert!(matches!(
325 builder.spawn(Marker),
326 Err(WorldBuildError::EntityLimitExceeded { limit: 1 })
327 ));
328 }
329
330 #[test]
331 fn managed_spawn_creates_only_the_final_managed_archetype() {
332 let mut builder = builder(1);
333 let entity = builder.spawn(Marker).expect("managed spawn should succeed");
334 let (world, _, managed_entities) = builder.finish();
335 let marker = world
336 .component_id::<Marker>()
337 .expect("Marker should be registered");
338 let managed = world
339 .component_id::<ManagedEntity>()
340 .expect("ManagedEntity should be registered");
341
342 assert_eq!(managed_entities, 1);
343 assert_eq!(
344 world
345 .get::<ManagedEntity>(entity.entity())
346 .map(|managed| managed.handle(entity.entity())),
347 Some(entity)
348 );
349 assert!(
350 !world
351 .archetypes()
352 .iter()
353 .any(|archetype| archetype.contains(marker) && !archetype.contains(managed))
354 );
355 }
356
357 #[test]
358 fn array_spawn_returns_input_order_handles_with_candidate_generation() {
359 let mut registry = ComponentRegistry::default();
360 assert!(registry.approve::<Indexed>().is_ok());
361 let mut builder = builder_from_registry(3, registry);
362
363 let handles = builder
364 .spawn_array([Indexed(7), Indexed(3), Indexed(9)])
365 .expect("exactly fitting array should spawn");
366
367 assert_eq!(
368 handles.map(LogicEntity::world_generation),
369 [builder.generation(); 3]
370 );
371 assert_ne!(handles[0], handles[1]);
372 assert_ne!(handles[1], handles[2]);
373 for (handle, expected) in handles.into_iter().zip([7, 3, 9]) {
374 assert_eq!(
375 builder
376 .world
377 .get::<Indexed>(handle.entity())
378 .map(|value| value.0),
379 Some(expected)
380 );
381 assert_eq!(
382 builder
383 .world
384 .get::<ManagedEntity>(handle.entity())
385 .map(|managed| managed.handle(handle.entity())),
386 Some(handle)
387 );
388 }
389 assert!(matches!(
390 builder.spawn(Indexed(1)),
391 Err(WorldBuildError::EntityLimitExceeded { limit: 3 })
392 ));
393 }
394
395 #[test]
396 fn zero_and_single_element_arrays_preserve_validation_and_limit_semantics() {
397 let mut builder = builder(1);
398
399 let empty = builder
400 .spawn_array::<Marker, 0>([])
401 .expect("approved empty array should be valid");
402 assert_eq!(empty, []);
403 let [only] = builder
404 .spawn_array([Marker])
405 .expect("single-element array should match singular spawn");
406 assert_eq!(only.world_generation(), builder.generation());
407 assert!(builder.spawn_array::<Marker, 0>([]).is_ok());
408
409 assert!(matches!(
410 builder.spawn_array::<Unapproved, 0>([]),
411 Err(WorldBuildError::Component(
412 ComponentApprovalError::UnapprovedBundleComponent { .. }
413 ))
414 ));
415 }
416
417 #[test]
418 fn array_limit_failure_creates_no_prefix_and_leaves_capacity_available() {
419 let mut builder = builder(3);
420 let first = builder.spawn(Marker).expect("first entity should fit");
421
422 assert!(matches!(
423 builder.spawn_array([Marker, Marker, Marker]),
424 Err(WorldBuildError::EntityLimitExceeded { limit: 3 })
425 ));
426 assert_eq!(builder.managed_entities, 1);
427 assert_eq!(
428 builder
429 .world
430 .iter_entities()
431 .filter(|entity| entity.contains::<ManagedEntity>())
432 .count(),
433 1
434 );
435 assert!(builder.world.get::<Marker>(first.entity()).is_some());
436 assert!(builder.spawn_array([Marker, Marker]).is_ok());
437 assert_eq!(builder.managed_entities, 3);
438 }
439
440 #[test]
441 fn array_count_overflow_is_rejected_before_spawning() {
442 let mut builder = builder(usize::MAX);
443 builder.managed_entities = usize::MAX;
444
445 assert!(matches!(
446 builder.spawn_array([Marker]),
447 Err(WorldBuildError::EntityLimitExceeded { limit: usize::MAX })
448 ));
449 assert!(
450 builder
451 .world
452 .iter_entities()
453 .all(|entity| !entity.contains::<ManagedEntity>())
454 );
455 }
456
457 #[test]
458 fn bundle_validation_precedes_array_limit_validation() {
459 let mut builder = builder(1);
460 assert!(builder.spawn(Marker).is_ok());
461
462 assert!(matches!(
463 builder.spawn_array([Unapproved]),
464 Err(WorldBuildError::Component(
465 ComponentApprovalError::UnapprovedBundleComponent { .. }
466 ))
467 ));
468 assert_eq!(builder.managed_entities, 1);
469 }
470
471 #[test]
472 fn rejected_array_drops_every_input_once() {
473 let mut registry = ComponentRegistry::default();
474 assert!(registry.approve::<Marker>().is_ok());
475 assert!(registry.approve::<DropProbe>().is_ok());
476 let mut builder = builder_from_registry(1, registry);
477 assert!(builder.spawn(Marker).is_ok());
478 let drops = Arc::new(AtomicUsize::new(0));
479
480 let result = builder.spawn_array([
481 DropProbe(Arc::clone(&drops)),
482 DropProbe(Arc::clone(&drops)),
483 DropProbe(Arc::clone(&drops)),
484 ]);
485
486 assert!(matches!(
487 result,
488 Err(WorldBuildError::EntityLimitExceeded { limit: 1 })
489 ));
490 assert_eq!(drops.load(Ordering::SeqCst), 3);
491 assert_eq!(builder.managed_entities, 1);
492 }
493
494 #[test]
495 fn array_spawn_materializes_required_defaults_and_preserves_explicit_values() {
496 let mut registry = ComponentRegistry::default();
497 assert!(registry.approve::<NeedsRequired>().is_ok());
498 assert!(registry.approve::<RequiredValue>().is_ok());
499 let mut builder = builder_from_registry(4, registry);
500
501 let implicit = builder
502 .spawn_array([NeedsRequired, NeedsRequired])
503 .expect("approved requirements should materialize");
504 let explicit = builder
505 .spawn_array([
506 (NeedsRequired, RequiredValue(4)),
507 (NeedsRequired, RequiredValue(8)),
508 ])
509 .expect("explicit requirements should take precedence");
510
511 for handle in implicit {
512 assert_eq!(
513 builder.world.get::<RequiredValue>(handle.entity()),
514 Some(&RequiredValue::default())
515 );
516 }
517 for (handle, expected) in explicit.into_iter().zip([4, 8]) {
518 assert_eq!(
519 builder.world.get::<RequiredValue>(handle.entity()),
520 Some(&RequiredValue(expected))
521 );
522 }
523 }
524
525 #[test]
526 fn disabled_array_entities_consume_capacity_and_use_only_final_archetype() {
527 let mut builder = builder(2);
528 let handles = builder
529 .spawn_array([(Marker, Disabled), (Marker, Disabled)])
530 .expect("disabled entities should be accepted");
531 let marker = builder
532 .world
533 .component_id::<Marker>()
534 .expect("registered Marker");
535 let managed = builder
536 .world
537 .component_id::<ManagedEntity>()
538 .expect("registered ManagedEntity");
539
540 for handle in handles {
541 assert!(builder.world.get::<Disabled>(handle.entity()).is_some());
542 assert!(builder.world.get::<Marker>(handle.entity()).is_some());
543 }
544 assert_eq!(builder.managed_entities, 2);
545 assert!(
546 !builder
547 .world
548 .archetypes()
549 .iter()
550 .any(|archetype| archetype.contains(marker) && !archetype.contains(managed))
551 );
552 assert!(matches!(
553 builder.spawn(Marker),
554 Err(WorldBuildError::EntityLimitExceeded { limit: 2 })
555 ));
556 }
557
558 #[test]
559 fn disabled_entities_still_consume_the_hard_candidate_limit() {
560 let mut builder = builder(1);
561 assert!(builder.spawn((Marker, Disabled)).is_ok());
562
563 assert!(matches!(
564 builder.spawn(Marker),
565 Err(WorldBuildError::EntityLimitExceeded { limit: 1 })
566 ));
567 }
568
569 #[test]
570 fn despawn_releases_candidate_capacity_and_finish_reports_exact_count() {
571 let mut builder = builder(1);
572 let first = builder.spawn(Marker).expect("first entity should fit");
573 assert!(builder.despawn(first).is_ok());
574 assert!(builder.spawn((Marker, Disabled)).is_ok());
575
576 let (world, _, managed_entities) = builder.finish();
577 let actual = world
578 .iter_entities()
579 .filter(|entity| entity.contains::<ManagedEntity>())
580 .count();
581 assert_eq!(managed_entities, 1);
582 assert_eq!(managed_entities, actual);
583 }
584
585 #[test]
586 fn repeated_despawn_remains_a_missing_entity_error() {
587 let mut builder = builder(1);
588 let entity = builder.spawn(Marker).expect("first entity should fit");
589 assert!(builder.despawn(entity).is_ok());
590
591 assert!(matches!(
592 builder.despawn(entity),
593 Err(WorldBuildError::MissingEntity { .. })
594 ));
595 }
596
597 #[test]
598 fn despawn_rejects_a_row_with_mismatched_private_provenance() {
599 let mut builder = builder(1);
600 let entity = builder.spawn(Marker).expect("managed spawn should succeed");
601 let corrupted = WorldGeneration::new(ApplicationId::from_raw(1), 99);
602 builder
603 .world
604 .entity_mut(entity.entity())
605 .insert(ManagedEntity::for_generation(corrupted));
606
607 assert!(matches!(
608 builder.despawn(entity),
609 Err(WorldBuildError::MissingEntity { entity: rejected }) if rejected == entity
610 ));
611 assert_eq!(builder.managed_entities, 1);
612 }
613
614 #[test]
615 fn resources_are_inserted_without_raw_world_access() {
616 let mut builder = builder(1);
617 assert!(builder.insert_resource(Setting(7)).is_ok());
618 let (world, _, _) = builder.finish();
619
620 assert_eq!(world.get_resource::<Setting>(), Some(&Setting(7)));
621 }
622
623 #[test]
624 fn resources_with_lifecycle_hooks_are_rejected() {
625 let mut builder = builder(1);
626 let result = builder.insert_resource(HookedSetting);
627
628 assert!(matches!(
629 result,
630 Err(WorldBuildError::Component(
631 ComponentApprovalError::LifecycleHook {
632 component,
633 hook: LifecycleHook::Add,
634 }
635 )) if component == std::any::type_name::<HookedSetting>()
636 ));
637 }
638
639 #[test]
640 fn resource_required_components_are_rejected_but_is_resource_is_allowed() {
641 let mut builder = builder(1);
642 assert!(builder.insert_resource(Setting(7)).is_ok());
643
644 let result = builder.insert_resource(SettingWithRequiredComponent);
645 let (component, required) = match result {
646 Err(WorldBuildError::Component(
647 ComponentApprovalError::UnapprovedRequiredComponent {
648 component,
649 required,
650 },
651 )) => (component, required),
652 Err(error) => panic!("unexpected resource validation error: {error}"),
653 Ok(_) => panic!("resource with a user-required component was accepted"),
654 };
655
656 assert_eq!(
657 component,
658 std::any::type_name::<SettingWithRequiredComponent>()
659 );
660 assert!(!required.is_empty());
661 }
662}