EntityPool

Defined in: EntityPool.ts:105

A group of entities cycled by deactivation instead of spawn and destroy. A member is built once, parked dormant when released, and woken on the next acquire, so its Rapier body, Pixi display object and component instances stay allocated between lives.

class Spark extends Entity {
  setup() { this.add(new Transform()); this.add(new GraphicsComponent()...); }
  onAcquire(x: number, y: number) { this.get(Transform).setPosition(x, y); }
}

// In the scene's onEnter — the members' components resolve scene services.
this.sparks = new EntityPool(this, Spark, { prewarm: 32 });

const spark = this.sparks.acquire(x, y);   // Spark: elastic pools always give one
this.sparks.release(spark);                // dormant, back in the pool

acquire’s arguments are the entity’s own onAcquire parameters, and its return type follows the pool: T while elastic, T | undefined once maxSize is set. forceAcquire always returns a member, reclaiming the lowest-priority live one when a capped pool is saturated.

Reuse resets nothing by itself. onAcquire is where a member returns to a known state — position, health, animation frame — because everything it held while dormant is still there.

Type Parameters

T

T extends PoolableEntity

TMax

TMax extends number | undefined = undefined

Constructors

Constructor

new EntityPool<T, TMax>(scene, Class, …args): EntityPool<T, TMax>

Defined in: EntityPool.ts:135

Parameters

scene

Scene

Class

() => T

args

…EntityPoolArgs<T, TMax>

Returns

EntityPool<T, TMax>

Accessors

free

Get Signature

get free(): number

Defined in: EntityPool.ts:205

Members ready for the next acquire. A member part-way through its release counts in neither free nor leased.

Returns

number

---

leased

Get Signature

get leased(): number

Defined in: EntityPool.ts:197

Members currently handed out.

Returns

number

---

size

Get Signature

get size(): number

Defined in: EntityPool.ts:192

Total members, leased and free together.

Returns

number

Methods

_isLeased()

_isLeased(member): boolean

Defined in: EntityPool.ts:328

Internal

Internal: is this member currently lent out? Entity.handle() asks, so a handle taken on a member sitting in the pool is born dead instead of coming alive at the next acquisition.

Parameters

member

Entity

Returns

boolean

---

_releaseMember()

_releaseMember(member): void

Defined in: EntityPool.ts:317

Internal

Internal: take a member back because Entity.destroy was called on it. A member that is not currently leased is already back in the pool, so retiring it again is a no-op rather than a reported double release.

Parameters

member

Entity

Returns

void

---

acquire()

acquire(…args): AcquireResult<T, TMax>

Defined in: EntityPool.ts:219

Take a member: a dormant one if the pool has any, otherwise a new one while the pool can still grow. Returns undefined only on a capped pool with every member out.

The member is active and in every matching query before onAcquire runs, so the hook can reach its own components and siblings. Acquire during Update and the member renders the same frame; acquire later (Render, EndOfFrame) and it first draws on the next one.

Parameters

args

…Parameters<T["onAcquire"]>

Returns

AcquireResult<T, TMax>

---

dispose()

dispose(): void

Defined in: EntityPool.ts:295

Destroy every member and stop the pool. acquire / forceAcquire throw afterwards. The scene disposes its pools on exit, so a pool that lives as long as its scene never needs this call.

Returns

void

---

forceAcquire()

forceAcquire(…args): T

Defined in: EntityPool.ts:240

Take a member, always. Same as acquire while the pool can serve one; on a saturated capped pool it reclaims instead — the lowest-reclaimPriority live member is released and handed straight back, running onRelease, then onAcquire, in the same call.

The one call it cannot serve is from inside onRelease on a capped pool with no other member left. The member that hook belongs to is mid-release and handing it straight back would run the rest of its release over a fresh acquisition, so this throws instead.

Parameters

args

…Parameters<T["onAcquire"]>

Returns

T

---

release()

release(member): void

Defined in: EntityPool.ts:254

Put a member back: onRelease, then dormant, then available again. Releasing an entity this pool did not hand out — a double release, or another pool’s member — is a reported no-op.

Parameters

member

T

Returns

void

---

releaseAll()

releaseAll(): void

Defined in: EntityPool.ts:279

Release every member leased when the call was made. A lease a release hook creates while this runs is the hook’s to keep: only the leases that existed at call time end, and each only if it is still the same lease when its turn comes.

Returns

void