@@ -614,6 +614,110 @@ impl<'w, 's> Commands<'w, 's> {
614614 self . queue ( insert_or_spawn_batch ( bundles_iter) ) ;
615615 }
616616
617+ /// Pushes a [`Command`] to the queue for adding a [`Bundle`] type to a batch of [`Entities`](Entity).
618+ ///
619+ /// A batch can be any type that implements [`IntoIterator`] containing `(Entity, Bundle)` tuples,
620+ /// such as a [`Vec<(Entity, Bundle)>`] or an array `[(Entity, Bundle); N]`.
621+ ///
622+ /// When the command is applied, for each `(Entity, Bundle)` pair in the given batch,
623+ /// the `Bundle` is added to the `Entity`, overwriting any existing components shared by the `Bundle`.
624+ ///
625+ /// This method is equivalent to iterating the batch,
626+ /// calling [`entity`](Self::entity) for each pair,
627+ /// and passing the bundle to [`insert`](EntityCommands::insert),
628+ /// but it is faster due to memory pre-allocation.
629+ ///
630+ /// # Panics
631+ ///
632+ /// This command panics if any of the given entities do not exist.
633+ ///
634+ /// For the non-panicking version, see [`try_insert_batch`](Self::try_insert_batch).
635+ #[ track_caller]
636+ pub fn insert_batch < I , B > ( & mut self , batch : I )
637+ where
638+ I : IntoIterator < Item = ( Entity , B ) > + Send + Sync + ' static ,
639+ B : Bundle ,
640+ {
641+ self . queue ( insert_batch ( batch) ) ;
642+ }
643+
644+ /// Pushes a [`Command`] to the queue for adding a [`Bundle`] type to a batch of [`Entities`](Entity).
645+ ///
646+ /// A batch can be any type that implements [`IntoIterator`] containing `(Entity, Bundle)` tuples,
647+ /// such as a [`Vec<(Entity, Bundle)>`] or an array `[(Entity, Bundle); N]`.
648+ ///
649+ /// When the command is applied, for each `(Entity, Bundle)` pair in the given batch,
650+ /// the `Bundle` is added to the `Entity`, except for any components already present on the `Entity`.
651+ ///
652+ /// This method is equivalent to iterating the batch,
653+ /// calling [`entity`](Self::entity) for each pair,
654+ /// and passing the bundle to [`insert_if_new`](EntityCommands::insert_if_new),
655+ /// but it is faster due to memory pre-allocation.
656+ ///
657+ /// # Panics
658+ ///
659+ /// This command panics if any of the given entities do not exist.
660+ ///
661+ /// For the non-panicking version, see [`try_insert_batch_if_new`](Self::try_insert_batch_if_new).
662+ #[ track_caller]
663+ pub fn insert_batch_if_new < I , B > ( & mut self , batch : I )
664+ where
665+ I : IntoIterator < Item = ( Entity , B ) > + Send + Sync + ' static ,
666+ B : Bundle ,
667+ {
668+ self . queue ( insert_batch_if_new ( batch) ) ;
669+ }
670+
671+ /// Pushes a [`Command`] to the queue for adding a [`Bundle`] type to a batch of [`Entities`](Entity).
672+ ///
673+ /// A batch can be any type that implements [`IntoIterator`] containing `(Entity, Bundle)` tuples,
674+ /// such as a [`Vec<(Entity, Bundle)>`] or an array `[(Entity, Bundle); N]`.
675+ ///
676+ /// When the command is applied, for each `(Entity, Bundle)` pair in the given batch,
677+ /// the `Bundle` is added to the `Entity`, overwriting any existing components shared by the `Bundle`.
678+ ///
679+ /// This method is equivalent to iterating the batch,
680+ /// calling [`get_entity`](Self::get_entity) for each pair,
681+ /// and passing the bundle to [`insert`](EntityCommands::insert),
682+ /// but it is faster due to memory pre-allocation.
683+ ///
684+ /// This command silently fails by ignoring any entities that do not exist.
685+ ///
686+ /// For the panicking version, see [`insert_batch`](Self::insert_batch).
687+ #[ track_caller]
688+ pub fn try_insert_batch < I , B > ( & mut self , batch : I )
689+ where
690+ I : IntoIterator < Item = ( Entity , B ) > + Send + Sync + ' static ,
691+ B : Bundle ,
692+ {
693+ self . queue ( try_insert_batch ( batch) ) ;
694+ }
695+
696+ /// Pushes a [`Command`] to the queue for adding a [`Bundle`] type to a batch of [`Entities`](Entity).
697+ ///
698+ /// A batch can be any type that implements [`IntoIterator`] containing `(Entity, Bundle)` tuples,
699+ /// such as a [`Vec<(Entity, Bundle)>`] or an array `[(Entity, Bundle); N]`.
700+ ///
701+ /// When the command is applied, for each `(Entity, Bundle)` pair in the given batch,
702+ /// the `Bundle` is added to the `Entity`, except for any components already present on the `Entity`.
703+ ///
704+ /// This method is equivalent to iterating the batch,
705+ /// calling [`get_entity`](Self::get_entity) for each pair,
706+ /// and passing the bundle to [`insert_if_new`](EntityCommands::insert_if_new),
707+ /// but it is faster due to memory pre-allocation.
708+ ///
709+ /// This command silently fails by ignoring any entities that do not exist.
710+ ///
711+ /// For the panicking version, see [`insert_batch_if_new`](Self::insert_batch_if_new).
712+ #[ track_caller]
713+ pub fn try_insert_batch_if_new < I , B > ( & mut self , batch : I )
714+ where
715+ I : IntoIterator < Item = ( Entity , B ) > + Send + Sync + ' static ,
716+ B : Bundle ,
717+ {
718+ self . queue ( try_insert_batch_if_new ( batch) ) ;
719+ }
720+
617721 /// Pushes a [`Command`] to the queue for inserting a [`Resource`] in the [`World`] with an inferred value.
618722///
619723/// The inferred value is determined by the [`FromWorld`] trait of the resource.
@@ -1734,6 +1838,94 @@ where
17341838 }
17351839}
17361840
1841+ /// A [`Command`] that consumes an iterator to add a series of [`Bundles`](Bundle) to a set of entities.
1842+ /// If any entities do not exist in the world, this command will panic.
1843+ ///
1844+ /// This is more efficient than inserting the bundles individually.
1845+ #[ track_caller]
1846+ fn insert_batch < I , B > ( batch : I ) -> impl Command
1847+ where
1848+ I : IntoIterator < Item = ( Entity , B ) > + Send + Sync + ' static ,
1849+ B : Bundle ,
1850+ {
1851+ #[ cfg( feature = "track_change_detection" ) ]
1852+ let caller = Location :: caller ( ) ;
1853+ move |world : & mut World | {
1854+ world. insert_batch_with_caller (
1855+ batch,
1856+ InsertMode :: Replace ,
1857+ #[ cfg( feature = "track_change_detection" ) ]
1858+ caller,
1859+ ) ;
1860+ }
1861+ }
1862+
1863+ /// A [`Command`] that consumes an iterator to add a series of [`Bundles`](Bundle) to a set of entities.
1864+ /// If any entities do not exist in the world, this command will panic.
1865+ ///
1866+ /// This is more efficient than inserting the bundles individually.
1867+ #[ track_caller]
1868+ fn insert_batch_if_new < I , B > ( batch : I ) -> impl Command
1869+ where
1870+ I : IntoIterator < Item = ( Entity , B ) > + Send + Sync + ' static ,
1871+ B : Bundle ,
1872+ {
1873+ #[ cfg( feature = "track_change_detection" ) ]
1874+ let caller = Location :: caller ( ) ;
1875+ move |world : & mut World | {
1876+ world. insert_batch_with_caller (
1877+ batch,
1878+ InsertMode :: Keep ,
1879+ #[ cfg( feature = "track_change_detection" ) ]
1880+ caller,
1881+ ) ;
1882+ }
1883+ }
1884+
1885+ /// A [`Command`] that consumes an iterator to add a series of [`Bundles`](Bundle) to a set of entities.
1886+ /// If any entities do not exist in the world, this command will ignore them.
1887+ ///
1888+ /// This is more efficient than inserting the bundles individually.
1889+ #[ track_caller]
1890+ fn try_insert_batch < I , B > ( batch : I ) -> impl Command
1891+ where
1892+ I : IntoIterator < Item = ( Entity , B ) > + Send + Sync + ' static ,
1893+ B : Bundle ,
1894+ {
1895+ #[ cfg( feature = "track_change_detection" ) ]
1896+ let caller = Location :: caller ( ) ;
1897+ move |world : & mut World | {
1898+ world. try_insert_batch_with_caller (
1899+ batch,
1900+ InsertMode :: Replace ,
1901+ #[ cfg( feature = "track_change_detection" ) ]
1902+ caller,
1903+ ) ;
1904+ }
1905+ }
1906+
1907+ /// A [`Command`] that consumes an iterator to add a series of [`Bundles`](Bundle) to a set of entities.
1908+ /// If any entities do not exist in the world, this command will ignore them.
1909+ ///
1910+ /// This is more efficient than inserting the bundles individually.
1911+ #[ track_caller]
1912+ fn try_insert_batch_if_new < I , B > ( batch : I ) -> impl Command
1913+ where
1914+ I : IntoIterator < Item = ( Entity , B ) > + Send + Sync + ' static ,
1915+ B : Bundle ,
1916+ {
1917+ #[ cfg( feature = "track_change_detection" ) ]
1918+ let caller = Location :: caller ( ) ;
1919+ move |world : & mut World | {
1920+ world. try_insert_batch_with_caller (
1921+ batch,
1922+ InsertMode :: Keep ,
1923+ #[ cfg( feature = "track_change_detection" ) ]
1924+ caller,
1925+ ) ;
1926+ }
1927+ }
1928+
17371929/// A [`Command`] that despawns a specific entity.
17381930/// This will emit a warning if the entity does not exist.
17391931///
0 commit comments