A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file entity-generation.test.ts
* @brief Verify Entity packing helpers and World's stale-handle detection.
*/
import { describe, expect, it } from 'vitest';
import { World } from '../src/ecs/world';
import {
ENTITY_GEN_BITS,
ENTITY_GEN_MASK,
ENTITY_INDEX_BITS,
ENTITY_INDEX_MASK,
entityGeneration,
entityIndex,
isValidEntity,
makeEntity,
INVALID_ENTITY,
} from '../src/types';
describe('Entity packing', () => {
it('round-trips index/generation through makeEntity', () => {
const e = makeEntity(12345, 7);
expect(entityIndex(e)).toBe(12345);
expect(entityGeneration(e)).toBe(7);
});
it('uses the documented 22/10 bit layout (matches C++ PackedId<22,10>)', () => {
expect(ENTITY_INDEX_BITS).toBe(22);
expect(ENTITY_GEN_BITS).toBe(10);
expect(ENTITY_INDEX_MASK).toBe(0x3FFFFF);
});
it('masks out-of-range index/generation to their documented widths', () => {
const e = makeEntity(0xFFFFFFFF, 0xFFFFFFFF);
expect(entityIndex(e)).toBe(0x3FFFFF);
expect(entityGeneration(e)).toBe(0x3FF);
});
it('packs a high generation without int32 overflow (stays unsigned)', () => {
// gen << 22 would overflow int32 to a negative number; makeEntity must
// produce the same unsigned u32 the C++ side stores in Entity::raw.
const e = makeEntity(7, ENTITY_GEN_MASK); // max generation
expect(e).toBeGreaterThan(0); // not a negative int32
expect(entityIndex(e)).toBe(7);
expect(entityGeneration(e)).toBe(ENTITY_GEN_MASK);
});
it('treats both sentinels as invalid', () => {
expect(isValidEntity(INVALID_ENTITY)).toBe(false);
expect(isValidEntity(0xFFFFFFFF)).toBe(false);
expect(isValidEntity(makeEntity(1, 0))).toBe(true);
});
});
describe('World stale-handle detection (pure-JS mode)', () => {
it('valid() distinguishes live from despawned handles', () => {
const world = new World();
const a = world.spawn();
expect(world.valid(a)).toBe(true);
world.despawn(a);
expect(world.valid(a)).toBe(false);
});
it('isStale() returns false for a live handle', () => {
const world = new World();
const a = world.spawn();
expect(world.isStale(a)).toBe(false);
});
it('isStale() returns false for a never-existed handle (not same as stale)', () => {
const world = new World();
const neverSpawned = makeEntity(999_999, 0);
expect(world.valid(neverSpawned)).toBe(false);
expect(world.isStale(neverSpawned)).toBe(false);
});
it('pure-JS spawns pack generation=0 into the layout', () => {
const world = new World();
const a = world.spawn();
// Pure-JS mode does not recycle indices yet, so every spawn is gen=0.
expect(entityGeneration(a)).toBe(0);
expect(entityIndex(a)).toBeGreaterThan(0);
});
});