Skip to main content

sim_logic/ecs/
world.rs

1//! Isolated managed World construction.
2
3use 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/// Failure while constructing an isolated World candidate.
17#[derive(Debug)]
18pub enum WorldBuildError {
19    /// A bundle or Resource violates the managed component rules.
20    Component(ComponentApprovalError),
21    /// Candidate construction would exceed the configured entity limit.
22    EntityLimitExceeded {
23        /// Frozen maximum managed entity count.
24        limit: usize,
25    },
26    /// A candidate attempted to despawn an entity outside itself.
27    ForeignEntity {
28        /// Rejected opaque entity handle.
29        entity: LogicEntity,
30    },
31    /// A candidate attempted to despawn a handle that is no longer live.
32    MissingEntity {
33        /// Rejected opaque entity handle.
34        entity: LogicEntity,
35    },
36    /// Application-specific candidate validation failed.
37    User {
38        /// Human-readable failure supplied by the factory.
39        message: String,
40    },
41}
42
43impl WorldBuildError {
44    /// Creates an application-specific candidate construction failure.
45    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
82/// Restricted builder for one isolated World candidate.
83///
84/// It deliberately provides no raw mutable Bevy `World`, observer registration,
85/// or direct structural escape hatch. Every entity receives a generation-aware
86/// [`LogicEntity`] identity.
87pub 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    /// Spawns one approved, side-effect-free bundle immediately in the isolated
115    /// candidate.
116    ///
117    /// Approved required components are materialized during the spawn. An
118    /// explicit value in `bundle` takes precedence over its required default.
119    ///
120    /// The returned identity already carries the candidate's reserved
121    /// generation. It cannot address the active World before candidate commit.
122    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    /// Spawns one fixed-size array of approved, side-effect-free bundles
132    /// immediately in the isolated candidate.
133    ///
134    /// Bundle approval and capacity for the complete array are checked before
135    /// the first entity is created. A typed validation or entity-limit error
136    /// therefore leaves no spawned prefix from this call. A zero-length array
137    /// still validates its bundle type, then succeeds without spawning an
138    /// entity or changing the managed-entity count.
139    ///
140    /// Required components, explicit-value precedence, and candidate identity
141    /// are identical to repeated successful [`Self::spawn`] calls. Returned
142    /// handles follow input order. This fixed-array helper does not perform a
143    /// dynamic Bevy batch insertion and makes no bulk-performance guarantee.
144    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    /// Despawns one entity from the isolated candidate.
191    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    /// Inserts or replaces one typed World Resource in the isolated candidate.
214    ///
215    /// Resources with user lifecycle hooks or user-declared required
216    /// components are rejected because they can create structural work outside
217    /// the managed candidate path.
218    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    /// Returns the candidate's reserved generation.
228    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}