13080464065

Committed 31 Jan 2025 08:41PM CUT coverage: 100.0%. Remained the same

Build # 13080464065

Build Type

push

github

Committed by

web-flow

Commit Message

Fix typo in user guide (#484)

Run Details

6549 of 6549 relevant lines covered (100.0%)

113821.56 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

100.0

/ecs/batch.go

package ecs

// Batch is a helper to perform batched operations on the world.
//
// Create using [World.Batch].
type Batch struct {
        world *World
}

// New creates many entities with the given components.
//
// See also [Builder] for more flexible batch-creation of entities.
func (b *Batch) New(count int, comps ...ID) {
        b.world.newEntities(count, ID{}, false, Entity{}, comps...)
}

// NewQ creates many entities with the given components, and returns a query over them.
//
// See also [Builder] for more flexible batch-creation of entities.
func (b *Batch) NewQ(count int, comps ...ID) Query {
        return b.world.newEntitiesQuery(count, ID{}, false, Entity{}, comps...)
}

// Add adds components to many entities, matching a filter.
// Returns the number of affected entities.
//
// Panics:
//   - when called with components that can't be added because they are already present.
//   - when called on a locked world. Do not use during [Query] iteration!
//
// See also [Batch.AddQ] and [World.Add].
func (b *Batch) Add(filter Filter, comps ...ID) int {
        return b.world.exchangeBatch(filter, comps, nil, ID{}, false, Entity{})
}

// AddQ adds components to many entities, matching a filter.
// It returns a query over the affected entities.
//
// Panics:
//   - when called with components that can't be added because they are already present.
//   - when called on a locked world. Do not use during [Query] iteration!
//
// See also [Batch.Add] and [World.Add].
func (b *Batch) AddQ(filter Filter, comps ...ID) Query {
        return b.world.exchangeBatchQuery(filter, comps, nil, ID{}, false, Entity{})
}

// Remove removes components from many entities, matching a filter.
// Returns the number of affected entities.
//
// Panics:
//   - when called with components that can't be removed because they are not present.
//   - when called on a locked world. Do not use during [Query] iteration!
//
// See also [Batch.RemoveQ] and [World.Remove].
func (b *Batch) Remove(filter Filter, comps ...ID) int {
        return b.world.exchangeBatch(filter, nil, comps, ID{}, false, Entity{})
}

// RemoveQ removes components from many entities, matching a filter.
// It returns a query over the affected entities.
//
// Panics:
//   - when called with components that can't be removed because they are not present.
//   - when called on a locked world. Do not use during [Query] iteration!
//
// See also [Batch.Remove] and [World.Remove].
func (b *Batch) RemoveQ(filter Filter, comps ...ID) Query {
        return b.world.exchangeBatchQuery(filter, nil, comps, ID{}, false, Entity{})
}

// SetRelation sets the [Relation] target for many entities, matching a filter.
// Returns the number of affected entities.
//
// Entities that match the filter but already have the desired target entity are not processed,
// and no events are emitted for them.
//
// Panics:
//   - when called for a missing component.
//   - when called for a component that is not a relation.
//   - when called on a locked world. Do not use during [Query] iteration!
//
// See also [Relations.Set] and [Relations.SetBatch].
func (b *Batch) SetRelation(filter Filter, comp ID, target Entity) int {
        return b.world.setRelationBatch(filter, comp, target)
}

// SetRelationQ sets the [Relation] target for many entities, matching a filter.
// It returns a query over the affected entities.
//
// Entities that match the filter but already have the desired target entity are not processed,
// not included in the query, and no events are emitted for them.
//
// Panics:
//   - when called for a missing component.
//   - when called for a component that is not a relation.
//   - when called on a locked world. Do not use during [Query] iteration!
//
// See also [Relations.Set] and [Relations.SetBatch].
func (b *Batch) SetRelationQ(filter Filter, comp ID, target Entity) Query {
        return b.world.setRelationBatchQuery(filter, comp, target)
}

// Exchange exchanges components for many entities, matching a filter.
// Returns the number of affected entities.
//
// When a [Relation] component is removed and another one is added,
// the target entity of the relation is reset to zero.
//
// Panics:
//   - when called with components that can't be added or removed because they are already present/not present, respectively.
//   - when called on a locked world. Do not use during [Query] iteration!
//
// See also [Batch.ExchangeQ] and [World.Exchange].
// For batch-exchange with a relation target, see [Relations.ExchangeBatch].
func (b *Batch) Exchange(filter Filter, add []ID, rem []ID) int {
        return b.world.exchangeBatch(filter, add, rem, ID{}, false, Entity{})
}

// ExchangeQ exchanges components for many entities, matching a filter.
// It returns a query over the affected entities.
//
// When a [Relation] component is removed and another one is added,
// the target entity of the relation is reset to zero.
//
// Panics:
//   - when called with components that can't be added or removed because they are already present/not present, respectively.
//   - when called on a locked world. Do not use during [Query] iteration!
//
// See also [Batch.Exchange] and [World.Exchange].
// For batch-exchange with a relation target, see [Relations.ExchangeBatchQ].
func (b *Batch) ExchangeQ(filter Filter, add []ID, rem []ID) Query {
        return b.world.exchangeBatchQuery(filter, add, rem, ID{}, false, Entity{})
}

// RemoveEntities removes and recycles all entities matching a filter.
// Returns the number of removed entities.
//
// Panics when called on a locked world.
// Do not use during [Query] iteration!
//
// Unlike with the other batch operations, it is not easily possible to provide a query version RemoveEntitiesQ.
// However, one can simply query with the same filter before calling RemoveEntities.
//
// See also [World.RemoveEntity]
func (b *Batch) RemoveEntities(filter Filter) int {
        return b.world.removeEntities(filter)
}

1	package ecs
2
3	// Batch is a helper to perform batched operations on the world.
4	//
5	// Create using [World.Batch].
6	type Batch struct {
7	world *World
8	}
9
10	// New creates many entities with the given components.
11	//
12	// See also [Builder] for more flexible batch-creation of entities.
13	func (b *Batch) New(count int, comps ...ID) {	12✔
14	b.world.newEntities(count, ID{}, false, Entity{}, comps...)	12✔
15	}	12✔
16
17	// NewQ creates many entities with the given components, and returns a query over them.
18	//
19	// See also [Builder] for more flexible batch-creation of entities.
20	func (b *Batch) NewQ(count int, comps ...ID) Query {	3✔
21	return b.world.newEntitiesQuery(count, ID{}, false, Entity{}, comps...)	3✔
22	}	3✔
23
24	// Add adds components to many entities, matching a filter.
25	// Returns the number of affected entities.
26	//
27	// Panics:
28	// - when called with components that can't be added because they are already present.
29	// - when called on a locked world. Do not use during [Query] iteration!
30	//
31	// See also [Batch.AddQ] and [World.Add].
32	func (b *Batch) Add(filter Filter, comps ...ID) int {	3✔
33	return b.world.exchangeBatch(filter, comps, nil, ID{}, false, Entity{})	3✔
34	}	3✔
35
36	// AddQ adds components to many entities, matching a filter.
37	// It returns a query over the affected entities.
38	//
39	// Panics:
40	// - when called with components that can't be added because they are already present.
41	// - when called on a locked world. Do not use during [Query] iteration!
42	//
43	// See also [Batch.Add] and [World.Add].
44	func (b *Batch) AddQ(filter Filter, comps ...ID) Query {	2✔
45	return b.world.exchangeBatchQuery(filter, comps, nil, ID{}, false, Entity{})	2✔
46	}	2✔
47
48	// Remove removes components from many entities, matching a filter.
49	// Returns the number of affected entities.
50	//
51	// Panics:
52	// - when called with components that can't be removed because they are not present.
53	// - when called on a locked world. Do not use during [Query] iteration!
54	//
55	// See also [Batch.RemoveQ] and [World.Remove].
56	func (b *Batch) Remove(filter Filter, comps ...ID) int {	3✔
57	return b.world.exchangeBatch(filter, nil, comps, ID{}, false, Entity{})	3✔
58	}	3✔
59
60	// RemoveQ removes components from many entities, matching a filter.
61	// It returns a query over the affected entities.
62	//
63	// Panics:
64	// - when called with components that can't be removed because they are not present.
65	// - when called on a locked world. Do not use during [Query] iteration!
66	//
67	// See also [Batch.Remove] and [World.Remove].
68	func (b *Batch) RemoveQ(filter Filter, comps ...ID) Query {	2✔
69	return b.world.exchangeBatchQuery(filter, nil, comps, ID{}, false, Entity{})	2✔
70	}	2✔
71
72	// SetRelation sets the [Relation] target for many entities, matching a filter.
73	// Returns the number of affected entities.
74	//
75	// Entities that match the filter but already have the desired target entity are not processed,
76	// and no events are emitted for them.
77	//
78	// Panics:
79	// - when called for a missing component.
80	// - when called for a component that is not a relation.
81	// - when called on a locked world. Do not use during [Query] iteration!
82	//
83	// See also [Relations.Set] and [Relations.SetBatch].
84	func (b *Batch) SetRelation(filter Filter, comp ID, target Entity) int {	3✔
85	return b.world.setRelationBatch(filter, comp, target)	3✔
86	}	3✔
87
88	// SetRelationQ sets the [Relation] target for many entities, matching a filter.
89	// It returns a query over the affected entities.
90	//
91	// Entities that match the filter but already have the desired target entity are not processed,
92	// not included in the query, and no events are emitted for them.
93	//
94	// Panics:
95	// - when called for a missing component.
96	// - when called for a component that is not a relation.
97	// - when called on a locked world. Do not use during [Query] iteration!
98	//
99	// See also [Relations.Set] and [Relations.SetBatch].
100	func (b *Batch) SetRelationQ(filter Filter, comp ID, target Entity) Query {	4✔
101	return b.world.setRelationBatchQuery(filter, comp, target)	4✔
102	}	4✔
103
104	// Exchange exchanges components for many entities, matching a filter.
105	// Returns the number of affected entities.
106	//
107	// When a [Relation] component is removed and another one is added,
108	// the target entity of the relation is reset to zero.
109	//
110	// Panics:
111	// - when called with components that can't be added or removed because they are already present/not present, respectively.
112	// - when called on a locked world. Do not use during [Query] iteration!
113	//
114	// See also [Batch.ExchangeQ] and [World.Exchange].
115	// For batch-exchange with a relation target, see [Relations.ExchangeBatch].
116	func (b *Batch) Exchange(filter Filter, add []ID, rem []ID) int {	7✔
117	return b.world.exchangeBatch(filter, add, rem, ID{}, false, Entity{})	7✔
118	}	7✔
119
120	// ExchangeQ exchanges components for many entities, matching a filter.
121	// It returns a query over the affected entities.
122	//
123	// When a [Relation] component is removed and another one is added,
124	// the target entity of the relation is reset to zero.
125	//
126	// Panics:
127	// - when called with components that can't be added or removed because they are already present/not present, respectively.
128	// - when called on a locked world. Do not use during [Query] iteration!
129	//
130	// See also [Batch.Exchange] and [World.Exchange].
131	// For batch-exchange with a relation target, see [Relations.ExchangeBatchQ].
132	func (b *Batch) ExchangeQ(filter Filter, add []ID, rem []ID) Query {	4✔
133	return b.world.exchangeBatchQuery(filter, add, rem, ID{}, false, Entity{})	4✔
134	}	4✔
135
136	// RemoveEntities removes and recycles all entities matching a filter.
137	// Returns the number of removed entities.
138	//
139	// Panics when called on a locked world.
140	// Do not use during [Query] iteration!
141	//
142	// Unlike with the other batch operations, it is not easily possible to provide a query version RemoveEntitiesQ.
143	// However, one can simply query with the same filter before calling RemoveEntities.
144	//
145	// See also [World.RemoveEntity]
146	func (b *Batch) RemoveEntities(filter Filter) int {	25,014✔
147	return b.world.removeEntities(filter)	25,014✔
148	}	25,014✔

mlange-42 / arche / 13080464065

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous