ECS Framework API v2.1.50

---

ECS Framework API / SparseSet

Class: SparseSet<T>

Defined in: ECS/Utils/SparseSet.ts:25

稀疏集合实现

提供O(1)的插入、删除、查找操作，同时保持数据的紧凑存储。 使用密集数组存储实际数据，稀疏映射提供快速访问

Example

const sparseSet = new SparseSet<Entity>();

sparseSet.add(entity1);
sparseSet.add(entity2);

if (sparseSet.has(entity1)) {
    sparseSet.remove(entity1);
}

sparseSet.forEach((entity, index) => {
    console.log(`Entity at index ${index}: ${entity.name}`);
});

Type Parameters

T

T

存储的数据类型

Constructors

Constructor

new SparseSet<T>(): SparseSet<T>

Returns

SparseSet<T>

Accessors

size

Get Signature

get size(): number

Defined in: ECS/Utils/SparseSet.ts:122

获取集合大小

Returns

number

---

isEmpty

Get Signature

get isEmpty(): boolean

Defined in: ECS/Utils/SparseSet.ts:129

检查集合是否为空

Returns

boolean

Methods

add()

add(item): boolean

Defined in: ECS/Utils/SparseSet.ts:46

添加元素到集合

Parameters

item

T

要添加的元素

Returns

boolean

是否成功添加（false表示元素已存在）

---

remove()

remove(item): boolean

Defined in: ECS/Utils/SparseSet.ts:68

从集合中移除元素

使用swap-and-pop技术保持数组紧凑性：

1. 将要删除的元素与最后一个元素交换
2. 删除最后一个元素
3. 更新映射表

Parameters

item

T

要移除的元素

Returns

boolean

是否成功移除（false表示元素不存在）

---

has()

has(item): boolean

Defined in: ECS/Utils/SparseSet.ts:95

检查元素是否存在于集合中

Parameters

item

T

要检查的元素

Returns

boolean

元素是否存在

---

getIndex()

getIndex(item): undefined | number

Defined in: ECS/Utils/SparseSet.ts:105

获取元素在密集数组中的索引

Parameters

item

T

要查询的元素

Returns

undefined | number

索引，如果元素不存在则返回undefined

---

getByIndex()

getByIndex(index): undefined | T

Defined in: ECS/Utils/SparseSet.ts:115

根据索引获取元素

Parameters

index

number

索引

Returns

undefined | T

元素，如果索引无效则返回undefined

---

forEach()

forEach(callback): void

Defined in: ECS/Utils/SparseSet.ts:141

遍历集合中的所有元素

保证遍历顺序与添加顺序一致（除非中间有删除操作）。 遍历性能优秀，因为数据在内存中连续存储。

Parameters

callback

(item, index) => void

遍历回调函数

Returns

void

---

map()

map<U>(callback): U[]

Defined in: ECS/Utils/SparseSet.ts:153

映射集合中的所有元素

Type Parameters

U

U

Parameters

callback

(item, index) => U

映射回调函数

Returns

U[]

映射后的新数组

---

filter()

filter(predicate): T[]

Defined in: ECS/Utils/SparseSet.ts:167

过滤集合中的元素

Parameters

predicate

(item, index) => boolean

过滤条件

Returns

T[]

满足条件的元素数组

---

find()

find(predicate): undefined | T

Defined in: ECS/Utils/SparseSet.ts:183

查找第一个满足条件的元素

Parameters

predicate

(item, index) => boolean

查找条件

Returns

undefined | T

找到的元素，如果没有则返回undefined

---

some()

some(predicate): boolean

Defined in: ECS/Utils/SparseSet.ts:198

检查是否存在满足条件的元素

Parameters

predicate

(item, index) => boolean

检查条件

Returns

boolean

是否存在满足条件的元素

---

every()

every(predicate): boolean

Defined in: ECS/Utils/SparseSet.ts:213

检查是否所有元素都满足条件

Parameters

predicate

(item, index) => boolean

检查条件

Returns

boolean

是否所有元素都满足条件

---

getDenseArray()

getDenseArray(): readonly T[]

Defined in: ECS/Utils/SparseSet.ts:227

获取密集数组的只读副本

返回数组的浅拷贝，确保外部无法直接修改内部数据。

Returns

readonly T[]

---

getDenseArrayUnsafe()

getDenseArrayUnsafe(): readonly T[]

Defined in: ECS/Utils/SparseSet.ts:237

获取密集数组的直接引用（内部使用）

警告：直接修改返回的数组会破坏数据结构的完整性。 仅在性能关键场景下使用，并确保不会修改数组内容。

Returns

readonly T[]

---

clear()

clear(): void

Defined in: ECS/Utils/SparseSet.ts:244

清空集合

Returns

void

---

toArray()

toArray(): T[]

Defined in: ECS/Utils/SparseSet.ts:252

转换为数组

Returns

T[]

---

toSet()

toSet(): Set<T>

Defined in: ECS/Utils/SparseSet.ts:259

转换为Set

Returns

Set<T>

---

getMemoryStats()

getMemoryStats(): object

Defined in: ECS/Utils/SparseSet.ts:266

获取内存使用统计信息

Returns

object

denseArraySize

denseArraySize: number

sparseMapSize

sparseMapSize: number

totalMemory

totalMemory: number

---

validate()

validate(): boolean

Defined in: ECS/Utils/SparseSet.ts:286

验证数据结构的完整性

调试用方法，检查内部数据结构是否一致。

Returns

boolean