13596114390

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

Build # 13596114390

Build Type

Pull #81

github

Committed by

web-flow

Commit Message

Merge 376331b97 into 9b17c8beb

Pull Request Pull Request #81: Unsafe API

Run Details

134 of 143 new or added lines in 6 files covered. (93.71%)

12 existing lines in 1 file now uncovered.

3628 of 3750 relevant lines covered (96.75%)

49235.14 hits per line

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

85.11

/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 {
        u.world.checkHasComponent(entity, comp)
        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 {
        u.world.checkHasComponent(entity, comp)
        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 {
        u.world.checkHasComponent(entity, comp)
        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 {
        u.world.checkHasComponent(entity, comp)
        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	u.world.checkHasComponent(entity, comp)	2✔
29	return u.world.storage.get(entity, comp)	2✔
30	}	2✔
31
32	// GetUnchecked returns a pointer to the given component of an [Entity].
33	// In contrast to [Unsafe.Get], it does not check whether the entity is alive.
34	//
35	// ⚠️ Important: The obtained pointer should not be stored persistently!
36	//
37	// Panics if the entity does not have the given component.
38	func (u Unsafe) GetUnchecked(entity Entity, comp ID) unsafe.Pointer {	1✔
39	u.world.checkHasComponent(entity, comp)	1✔
40	return u.world.storage.getUnchecked(entity, comp)	1✔
41	}	1✔
42
43	// Has returns whether an [Entity] has the given component.
44	//
45	// Panics when called for a removed (and potentially recycled) entity.
46	func (u Unsafe) Has(entity Entity, comp ID) bool {	9✔
47	return u.world.storage.has(entity, comp)	9✔
48	}	9✔
49
50	// HasUnchecked returns whether an [Entity] has the given component.
51	// In contrast to [Unsafe.Has], it does not check whether the entity is alive.
52	//
53	// Panics when called for a removed (and potentially recycled) entity.
54	func (u Unsafe) HasUnchecked(entity Entity, comp ID) bool {	2✔
55	return u.world.storage.hasUnchecked(entity, comp)	2✔
56	}	2✔
57
58	// GetRelation returns the relation target for the entity and the mapped component.
59	func (u Unsafe) GetRelation(entity Entity, comp ID) Entity {	4✔
60	u.world.checkHasComponent(entity, comp)	4✔
61	return u.world.storage.getRelation(entity, comp)	4✔
62	}	4✔
63
64	// GetRelationUnchecked returns the relation target for the entity and the mapped component.
65	// In contrast to [Unsafe.GetRelation], it does not check whether the entity is alive.
66	// Can be used as an optimization when it is certain that the entity is alive.
67	func (u Unsafe) GetRelationUnchecked(entity Entity, comp ID) Entity {	2✔
68	u.world.checkHasComponent(entity, comp)	2✔
69	return u.world.storage.getRelationUnchecked(entity, comp)	2✔
70	}	2✔
71
72	// SetRelations sets relation targets for an entity.
73	func (u Unsafe) SetRelations(entity Entity, relations ...RelationID) {	1✔
74	u.world.setRelations(entity, relations)	1✔
75	}	1✔
76
77	// Add the given components to an entity.
78	func (u Unsafe) Add(entity Entity, comp ...ID) {	1✔
79	if !u.world.Alive(entity) {	1✔
NEW 80	panic("can't add components to a dead entity")	×
81	}
82	u.world.exchange(entity, comp, nil, nil, nil)	1✔
83	}
84
85	// AddRel adds the given components and relation targets to an entity.
86	func (u Unsafe) AddRel(entity Entity, comps []ID, relations ...RelationID) {	1✔
87	if !u.world.Alive(entity) {	1✔
NEW 88	panic("can't add components to a dead entity")	×
89	}
90	u.world.exchange(entity, comps, nil, nil, relations)	1✔
91	}
92
93	// Remove the given components from an entity.
NEW 94	func (u Unsafe) Remove(entity Entity, comp ...ID) {	×
NEW 95	if !u.world.Alive(entity) {	×
NEW 96	panic("can't remove components from a dead entity")	×
97	}
NEW 98	u.world.exchange(entity, nil, comp, nil, nil)	×
99	}
100
101	// Exchange the given components to on entity.
102	func (u Unsafe) Exchange(entity Entity, add []ID, remove []ID, relations ...RelationID) {	1✔
103	if !u.world.Alive(entity) {	1✔
NEW 104	panic("can't exchange components on a dead entity")	×
105	}
106	u.world.exchange(entity, add, remove, nil, relations)	1✔
107	}
108
109	// TODO: Queries

mlange-42 / ark / 13596114390

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