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 cells.ts
* @brief What a cooked world IS, and the one function that decides which of its
* cells should exist right now.
*
* @details Separated from the streamer on purpose: residency is a decision about
* geometry and radii, and everything expensive — loading, spawning,
* releasing — is what happens AFTER it. Pure here means the union rule
* and the hysteresis band can be held to by a criterion that never
* builds a world.
*/
/** One cooked cell: an additive scene, and the ground it covers. @experimental */
export interface WorldCell {
/** Registered scene name — what `SceneManager` is asked to bring up. */
name: string;
/** Where its document ships, package-relative. */
path: string;
/** Grid coordinate on the XZ plane. */
x: number;
z: number;
/**
* The ground it covers, world units. The grid square UNIONED with where its
* content actually is: a cell is asked for by distance to this box, and a
* prop hanging over the edge is part of the place the box stands for.
*/
minX: number;
minZ: number;
maxX: number;
maxZ: number;
/** Authored entities inside, for a report that can be checked against the world. */
entityCount: number;
/** Top-level authored entities inside — each one a residency atom. */
rootCount: number;
}
/** A cooked world: the persistent scene's cells. @experimental */
export interface WorldManifest {
version: number;
/** Registered name of the persistent scene these cells belong to. */
scene: string;
/** Edge of one grid square, world units. */
cellSize: number;
/**
* The world plane the cells lie on: `'xz'` (the default, and what a manifest cooked before this field has) or `'xy'` for a 2D world. A cell's
* `z` and `minZ`/`maxZ` are the SECOND axis of that plane, so on `'xy'` they are world y.
*/
plane?: 'xz' | 'xy';
/**
* Authored ids in the persistent world that a cell holds a hard reference to.
* Only these are kept resolvable — a table of every row would be a cost the
* whole world pays for the handful of references that exist.
*/
persistentRefs: number[];
cells: WorldCell[];
}
/** One source's ask, as the streamer samples it. @experimental */
export interface ResidencySource {
x: number;
z: number;
loadRadius: number;
unloadRadius: number;
/** How early this source is worth preparing for. Never below `loadRadius`. */
prefetchRadius: number;
}
/** The plane a manifest's cells lie on, a manifest cooked before the field existing as the ground. @experimental */
export function manifestPlane(manifest: { plane?: 'xz' | 'xy' } | null): 'xz' | 'xy' {
return manifest?.plane === 'xy' ? 'xy' : 'xz';
}
/** The second coordinate of a world position on a plane: z on the ground, y on the screen. @experimental */
export function planeSecond(position: { y: number; z?: number }, plane: 'xz' | 'xy'): number {
return plane === 'xy' ? position.y : position.z ?? 0;
}
/** What residency should be, and the moves that get there. @experimental */
export interface ResidencyDecision {
/** Every cell that should exist after this tick, in manifest order. */
target: string[];
/**
* Cells worth PREPARING: near enough that a source may soon want them. A
* superset of the demanded ones in the ordinary case, but not by rule — a
* cell held by hysteresis can sit past every prefetch radius.
*/
prefetch: string[];
/** Demanded and not resident, nearest first: what to publish. */
toLoad: string[];
toUnload: string[];
}
/**
* The cell a world position falls in — the one rule, with two callers that must
* not drift: the cook assigns every top-level root by it, and the editor draws
* its grid from it. `z` is the position's SECOND coordinate on the plane the
* world is cut on: world z on the ground, world y on the screen plane.
*/
export function cellAt(x: number, z: number, cellSize: number): { x: number; z: number } {
return { x: Math.floor(x / cellSize), z: Math.floor(z / cellSize) };
}
/**
* The grid square one cell coordinate stands for.
*
* NOT the same as {@link WorldCell}'s box: a cooked cell's box is this square
* unioned with where its content actually reached, so it is usually larger. This
* is the partition; that is the partition plus its overhang.
*/
export function cellSquare(cellX: number, cellZ: number, cellSize: number): {
minX: number; minZ: number; maxX: number; maxZ: number;
} {
const minX = cellX * cellSize;
const minZ = cellZ * cellSize;
return { minX, minZ, maxX: minX + cellSize, maxZ: minZ + cellSize };
}
/**
* Ground-plane distance from a point to a cell's box; zero inside it.
*
* To the BOX rather than to the cell's centre, because a centre answers the same
* for a source standing on a diagonal corner as for one a whole cell away, and
* that is where holes open in a world laid out on a grid.
*/
export function distanceToCell(cell: WorldCell, x: number, z: number): number {
const dx = Math.max(cell.minX - x, 0, x - cell.maxX);
const dz = Math.max(cell.minZ - z, 0, z - cell.maxZ);
return Math.hypot(dx, dz);
}
/**
* Which cells should exist, given where the sources are and what is resident.
*
* A UNION, never a fold: a fold lets the last source win, and a second camera
* then deletes the world the first is standing in. The band is the other half —
* in at `loadRadius`, out past `unloadRadius`, so a boundary is not a treadmill.
*/
export function desiredResidency(
cells: readonly WorldCell[],
sources: readonly ResidencySource[],
resident: ReadonlySet<string>,
): ResidencyDecision {
const target: string[] = [];
const prefetch: string[] = [];
const toUnload: string[] = [];
/** Demanded-and-absent cells with how far the nearest source is. */
const pending: Array<{ name: string; distance: number }> = [];
for (const cell of cells) {
let wanted = false;
let kept = false;
let speculated = false;
let nearest = Infinity;
for (const source of sources) {
const distance = distanceToCell(cell, source.x, source.z);
if (distance < nearest) nearest = distance;
if (distance <= source.loadRadius) wanted = true;
// An authored band that is not a band is not one the streamer invents:
// the wider of the two is the only reading under which a resident cell
// cannot be dropped by the same distance that just asked for it.
else if (distance <= Math.max(source.loadRadius, source.unloadRadius)) kept = true;
if (distance <= Math.max(source.loadRadius, source.prefetchRadius)) speculated = true;
}
if (speculated) prefetch.push(cell.name);
const isResident = resident.has(cell.name);
if (wanted || (kept && isResident)) {
target.push(cell.name);
if (!isResident) pending.push({ name: cell.name, distance: nearest });
} else if (isResident) {
toUnload.push(cell.name);
}
}
// Nearest first, and stable: two cells a source is equally far from keep the
// order the cook wrote them in rather than one the sort invented.
pending.sort((a, b) => a.distance - b.distance);
return { target, prefetch, toLoad: pending.map((p) => p.name), toUnload };
}