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 disabled-entities.test.ts
* @brief A switched-off entity is out of the frame, not just marked.
*
* `Disabled`'s doc promised that "the engine's systems skip it" and
* nothing read the tag: `setEntityActive(world, e, false)` returned,
* every query went on answering with the entity, and the only sign was
* a comment in ui/controller/ai-builtins admitting it. A query is where
* a system meets the world, so that is where the promise is kept.
*/
import { describe, it, expect } from 'vitest';
import { World } from '../src/ecs/world';
import { defineComponent, defineTag, Disabled, Children } from '../src/ecs/component';
import { setEntityActive, isEntityActive } from '../src/ecs/entityUtils';
import type { Entity } from '../src/types';
const Health = defineComponent('TestHealth', { hp: 10 });
const Hostile = defineTag('TestHostile');
function worldWith(n: number): { world: World; entities: Entity[] } {
const world = new World();
const entities = Array.from({ length: n }, () => {
const e = world.spawn();
world.insert(e, Health, { hp: 10 });
return e;
});
return { world, entities };
}
describe('a disabled entity', () => {
it('filters component-free queries while retaining raw management access', () => {
const { world, entities } = worldWith(2);
setEntityActive(world, entities[0]!, false);
expect(world.queryEntities([])).toEqual([entities[1]]);
expect(world.getAllEntities()).toEqual(entities);
setEntityActive(world, entities[0]!, true);
expect(world.queryEntities([])).toEqual(entities);
});
it('observes core activity changes after a query cache hit', () => {
const { world, entities } = worldWith(2);
const disabled = new Set<Entity>();
let epoch = 0;
const core = {
setEntityEnabled: (e: Entity, enabled: boolean) => {
if (enabled) disabled.delete(e); else disabled.add(e);
++epoch; return true;
},
isEntityActive: (e: Entity) => !disabled.has(e),
isEntityEnabled: (e: Entity) => !disabled.has(e),
hasInactiveEntities: () => disabled.size > 0,
activityEpoch: () => epoch,
};
world.connectCpp(core as never);
expect(world.queryEntities([Health])).toEqual(entities);
core.setEntityEnabled(entities[0]!, false);
expect(world.queryEntities([Health])).toEqual([entities[1]]);
expect(isEntityActive(world, entities[0]!)).toBe(false);
setEntityActive(world, entities[0]!, true);
expect(world.queryEntities([Health])).toEqual(entities);
setEntityActive(world, entities[1]!, false);
expect(core.isEntityActive(entities[1]!)).toBe(false);
});
it('is not answered by a query', () => {
const { world, entities } = worldWith(3);
expect(world.getEntitiesWithComponents([Health])).toHaveLength(3);
setEntityActive(world, entities[1]!, false);
const live = world.getEntitiesWithComponents([Health]);
expect(live).toHaveLength(2);
expect(live).not.toContain(entities[1]);
setEntityActive(world, entities[1]!, true);
expect(world.getEntitiesWithComponents([Health])).toHaveLength(3);
});
it('is seen by a query that asks for the tag', () => {
const { world, entities } = worldWith(2);
setEntityActive(world, entities[0]!, false);
// Something has to be able to manage the switch — a query naming Disabled
// is that something, and excluding them there would make it unanswerable.
expect(world.getEntitiesWithComponents([Health, Disabled])).toEqual([entities[0]]);
});
it('marks itself and nothing else — the subtree is derived', () => {
const { world, entities } = worldWith(2);
setEntityActive(world, entities[0]!, false);
// The tag says what the AUTHOR switched off; which entities that takes
// out of a query is a walk down the tree, driven by the play-realm check
// (a real hierarchy is the one thing a unit test has no engine for).
expect(isEntityActive(world, entities[0]!)).toBe(false);
expect(isEntityActive(world, entities[1]!)).toBe(true);
expect(world.getEntitiesWithComponents([Health, Disabled])).toEqual([entities[0]]);
});
it('leaves the cached answer behind when it is switched', () => {
const { world, entities } = worldWith(2);
world.insert(entities[0]!, Hostile, {});
world.insert(entities[1]!, Hostile, {});
// Warm the cache, then switch: a query cache that does not depend on the
// tag hands back the entity it already found.
expect(world.getEntitiesWithComponents([Health], [Hostile])).toHaveLength(2);
setEntityActive(world, entities[0]!, false);
expect(world.getEntitiesWithComponents([Health], [Hostile])).toHaveLength(1);
});
it('is still a real entity — its components are readable', () => {
const { world, entities } = worldWith(1);
setEntityActive(world, entities[0]!, false);
// Off is not gone: the scene still holds it, and switching it back on has
// to find what it had. (Children is how the subtree walk reaches it.)
expect(world.valid(entities[0]!)).toBe(true);
expect((world.get(entities[0]!, Health) as { hp: number }).hp).toBe(10);
expect(world.has(entities[0]!, Children)).toBe(false);
});
});