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 ecs/entityOrder.ts
* @brief Permute the JS-side entity containers to a caller-supplied order.
*
* @details Iteration order is painter order: the engine walks its component pools
* and the SDK walks these Maps/Sets, and within a sorting layer whichever
* entity is visited last lands on top. Both sides are insertion-ordered,
* so "apply this order" means re-inserting in rank order — which is what
* {@link World.applyEntityOrder} does through these two helpers.
*
* Ranking is stable: an entity the caller did not rank keeps its position
* relative to the other unranked ones, after every ranked one.
*/
import type { Entity } from '../types';
/** Rank for an entity the caller did not order — sorts last, stably. */
export const UNRANKED = Number.MAX_SAFE_INTEGER;
/** `entity -> rank` for {@link reorderMapByRank}/{@link reorderSetByRank}. */
export type RankOf = (entity: Entity) => number;
/** Build a stable rank function from an ordered entity list (first = rank 0). */
export function rankByOrder(order: readonly Entity[]): RankOf {
const ranks = new Map<Entity, number>();
for (const entity of order) {
if (!ranks.has(entity)) ranks.set(entity, ranks.size); // duplicate: first wins
}
return (entity: Entity) => ranks.get(entity) ?? UNRANKED;
}
/** Re-insert `map`'s entries in rank order (values untouched). */
export function reorderMapByRank<V>(map: Map<Entity, V>, rankOf: RankOf): void {
if (map.size <= 1) return;
const entries = Array.from(map);
// Array.prototype.sort is stable (ES2019+), which is what keeps unranked
// entities in their existing relative order.
entries.sort((a, b) => rankOf(a[0]) - rankOf(b[0]));
map.clear();
for (const [entity, value] of entries) map.set(entity, value);
}
/** Re-insert `set`'s entities in rank order. */
export function reorderSetByRank(set: Set<Entity>, rankOf: RankOf): void {
if (set.size <= 1) return;
const entities = Array.from(set);
entities.sort((a, b) => rankOf(a) - rankOf(b));
set.clear();
for (const entity of entities) set.add(entity);
}