13596195716

Committed 28 Feb 2025 08:43PM CUT coverage: 96.745% (-0.1%) from 96.882%

Build # 13596195716

Build Type

Pull #81

github

Committed by

web-flow

Commit Message

Merge bc97e23ac into 9b17c8beb

Pull Request Pull Request #81: Unsafe API

Run Details

132 of 141 new or added lines in 6 files covered. (93.62%)

13 existing lines in 1 file now uncovered.

3626 of 3748 relevant lines covered (96.74%)

50383.37 hits per line

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

83.72

/ecs/unsafe.go

package ecs

import "unsafe"

// Unsafe provides access to Ark's unsafe ID-based API.
// Get an instance via [World.Unsafe].
type Unsafe struct {
        world *World
}

// NewEntity creates a new entity with the given components.
func (u Unsafe) NewEntity(ids ...ID) Entity {
        return u.world.newEntityWith(ids, nil, nil)
}

// NewEntityRel creates a new entity with the given components and relation targets.
func (u Unsafe) NewEntityRel(ids []ID, relations ...RelationID) Entity {
        return u.world.newEntityWith(ids, nil, relations)
}

// Get returns a pointer to the given component of an [Entity].
//
// ⚠️ Important: The obtained pointer should not be stored persistently!
//
// Panics if the entity does not have the given component.
// Panics when called for a removed (and potentially recycled) entity.
func (u Unsafe) Get(entity Entity, comp ID) unsafe.Pointer {
        return u.world.storage.get(entity, comp)
}

// GetUnchecked returns a pointer to the given component of an [Entity].
// In contrast to [Unsafe.Get], it does not check whether the entity is alive.
//
// ⚠️ Important: The obtained pointer should not be stored persistently!
//
// Panics if the entity does not have the given component.
func (u Unsafe) GetUnchecked(entity Entity, comp ID) unsafe.Pointer {
        return u.world.storage.getUnchecked(entity, comp)
}

// Has returns whether an [Entity] has the given component.
//
// Panics when called for a removed (and potentially recycled) entity.
func (u Unsafe) Has(entity Entity, comp ID) bool {
        return u.world.storage.has(entity, comp)
}

// HasUnchecked returns whether an [Entity] has the given component.
// In contrast to [Unsafe.Has], it does not check whether the entity is alive.
//
// Panics when called for a removed (and potentially recycled) entity.
func (u Unsafe) HasUnchecked(entity Entity, comp ID) bool {
        return u.world.storage.hasUnchecked(entity, comp)
}

// GetRelation returns the relation target for the entity and the mapped component.
func (u Unsafe) GetRelation(entity Entity, comp ID) Entity {
        return u.world.storage.getRelation(entity, comp)
}

// GetRelationUnchecked returns the relation target for the entity and the mapped component.
// In contrast to [Unsafe.GetRelation], it does not check whether the entity is alive.
// Can be used as an optimization when it is certain that the entity is alive.
func (u Unsafe) GetRelationUnchecked(entity Entity, comp ID) Entity {
        return u.world.storage.getRelationUnchecked(entity, comp)
}

// SetRelations sets relation targets for an entity.
func (u Unsafe) SetRelations(entity Entity, relations ...RelationID) {
        u.world.setRelations(entity, relations)
}

// Add the given components to an entity.
func (u Unsafe) Add(entity Entity, comp ...ID) {
        if !u.world.Alive(entity) {
                panic("can't add components to a dead entity")
        }
        u.world.exchange(entity, comp, nil, nil, nil)
}

// AddRel adds the given components and relation targets to an entity.
func (u Unsafe) AddRel(entity Entity, comps []ID, relations ...RelationID) {
        if !u.world.Alive(entity) {
                panic("can't add components to a dead entity")
        }
        u.world.exchange(entity, comps, nil, nil, relations)
}

// Remove the given components from an entity.
func (u Unsafe) Remove(entity Entity, comp ...ID) {
        if !u.world.Alive(entity) {
                panic("can't remove components from a dead entity")
        }
        u.world.exchange(entity, nil, comp, nil, nil)
}

// Exchange the given components to on entity.
func (u Unsafe) Exchange(entity Entity, add []ID, remove []ID, relations ...RelationID) {
        if !u.world.Alive(entity) {
                panic("can't exchange components on a dead entity")
        }
        u.world.exchange(entity, add, remove, nil, relations)
}

// TODO: Queries

1	package ecs
2
3	import "unsafe"
4
5	// Unsafe provides access to Ark's unsafe ID-based API.
6	// Get an instance via [World.Unsafe].
7	type Unsafe struct {
8	world *World
9	}
10
11	// NewEntity creates a new entity with the given components.
12	func (u Unsafe) NewEntity(ids ...ID) Entity {	4✔
13	return u.world.newEntityWith(ids, nil, nil)	4✔
14	}	4✔
15
16	// NewEntityRel creates a new entity with the given components and relation targets.
17	func (u Unsafe) NewEntityRel(ids []ID, relations ...RelationID) Entity {	1✔
18	return u.world.newEntityWith(ids, nil, relations)	1✔
19	}	1✔
20
21	// Get returns a pointer to the given component of an [Entity].
22	//
23	// ⚠️ Important: The obtained pointer should not be stored persistently!
24	//
25	// Panics if the entity does not have the given component.
26	// Panics when called for a removed (and potentially recycled) entity.
27	func (u Unsafe) Get(entity Entity, comp ID) unsafe.Pointer {	2✔
28	return u.world.storage.get(entity, comp)	2✔
29	}	2✔
30
31	// GetUnchecked returns a pointer to the given component of an [Entity].
32	// In contrast to [Unsafe.Get], it does not check whether the entity is alive.
33	//
34	// ⚠️ Important: The obtained pointer should not be stored persistently!
35	//
36	// Panics if the entity does not have the given component.
37	func (u Unsafe) GetUnchecked(entity Entity, comp ID) unsafe.Pointer {	1✔
38	return u.world.storage.getUnchecked(entity, comp)	1✔
39	}	1✔
40
41	// Has returns whether an [Entity] has the given component.
42	//
43	// Panics when called for a removed (and potentially recycled) entity.
44	func (u Unsafe) Has(entity Entity, comp ID) bool {	9✔
45	return u.world.storage.has(entity, comp)	9✔
46	}	9✔
47
48	// HasUnchecked returns whether an [Entity] has the given component.
49	// In contrast to [Unsafe.Has], it does not check whether the entity is alive.
50	//
51	// Panics when called for a removed (and potentially recycled) entity.
52	func (u Unsafe) HasUnchecked(entity Entity, comp ID) bool {	2✔
53	return u.world.storage.hasUnchecked(entity, comp)	2✔
54	}	2✔
55
56	// GetRelation returns the relation target for the entity and the mapped component.
57	func (u Unsafe) GetRelation(entity Entity, comp ID) Entity {	4✔
58	return u.world.storage.getRelation(entity, comp)	4✔
59	}	4✔
60
61	// GetRelationUnchecked returns the relation target for the entity and the mapped component.
62	// In contrast to [Unsafe.GetRelation], it does not check whether the entity is alive.
63	// Can be used as an optimization when it is certain that the entity is alive.
64	func (u Unsafe) GetRelationUnchecked(entity Entity, comp ID) Entity {	2✔
65	return u.world.storage.getRelationUnchecked(entity, comp)	2✔
66	}	2✔
67
68	// SetRelations sets relation targets for an entity.
69	func (u Unsafe) SetRelations(entity Entity, relations ...RelationID) {	1✔
70	u.world.setRelations(entity, relations)	1✔
71	}	1✔
72
73	// Add the given components to an entity.
74	func (u Unsafe) Add(entity Entity, comp ...ID) {	1✔
75	if !u.world.Alive(entity) {	1✔
NEW 76	panic("can't add components to a dead entity")	×
77	}
78	u.world.exchange(entity, comp, nil, nil, nil)	1✔
79	}
80
81	// AddRel adds the given components and relation targets to an entity.
82	func (u Unsafe) AddRel(entity Entity, comps []ID, relations ...RelationID) {	1✔
83	if !u.world.Alive(entity) {	1✔
NEW 84	panic("can't add components to a dead entity")	×
85	}
86	u.world.exchange(entity, comps, nil, nil, relations)	1✔
87	}
88
89	// Remove the given components from an entity.
NEW 90	func (u Unsafe) Remove(entity Entity, comp ...ID) {	×
NEW 91	if !u.world.Alive(entity) {	×
NEW 92	panic("can't remove components from a dead entity")	×
93	}
NEW 94	u.world.exchange(entity, nil, comp, nil, nil)	×
95	}
96
97	// Exchange the given components to on entity.
98	func (u Unsafe) Exchange(entity Entity, add []ID, remove []ID, relations ...RelationID) {	1✔
99	if !u.world.Alive(entity) {	1✔
NEW 100	panic("can't exchange components on a dead entity")	×
101	}
102	u.world.exchange(entity, add, remove, nil, relations)	1✔
103	}
104
105	// TODO: Queries

mlange-42 / ark / 13596195716

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