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 types.ts
* @brief Core type definitions for ESEngine SDK
*/
import { ENTITY_INDEX_BITS, ENTITY_GEN_BITS } from './wasm/entityLayout.generated';
// =============================================================================
// Entity
// =============================================================================
/**
* Entity identifier — a packed u32 with layout `[generation(10) | index(22)]`,
* matching the C++ `Entity` type in `src/esengine/core/Types.hpp`
* (`PackedId<22, 10>`).
*
* The 22-bit index is the slot in the registry (up to 4,194,303 live entities);
* the 10-bit generation is bumped each time an index is recycled (up to 1,023
* generations per slot before wrap). Comparing two raw Entity values thus
* detects stale handles: a handle from a despawned entity will have a
* different (generation, index) pair than any current live entity that reuses
* the index, so `rawA !== rawB` reliably distinguishes them.
*
* The value is transported across the WASM boundary as a plain u32 and used
* directly as a Map/Set key on the JS side.
*
* @public
*/
export type Entity = number;
/**
* Bit widths of the packed Entity representation, from the C++ `Entity::Layout`
* that owns them — EHT reads the header, so this is not a second answer. The
* split is in the ABI layout hash, so a WASM binary and an SDK bundle built from
* different ones refuse each other rather than decoding each other's handles.
*/
export { ENTITY_INDEX_BITS, ENTITY_GEN_BITS };
/** Number of representable indices (2^INDEX_BITS) — used for overflow-safe packing. */
const ENTITY_INDEX_COUNT = 2 ** ENTITY_INDEX_BITS;
export const ENTITY_INDEX_MASK = ENTITY_INDEX_COUNT - 1;
export const ENTITY_GEN_MASK = (1 << ENTITY_GEN_BITS) - 1;
/** Index portion (low ENTITY_INDEX_BITS) of an Entity handle. */
export function entityIndex(e: Entity): number {
// `& MASK` is correct even for e > 2^31: the low INDEX_BITS survive the
// int32 coercion, and MASK (2^22-1) is well within int32 range.
return e & ENTITY_INDEX_MASK;
}
/** Generation portion (high ENTITY_GEN_BITS) of an Entity handle. */
export function entityGeneration(e: Entity): number {
// `>>>` reads e as unsigned 32-bit, so this is correct for the full u32 range.
return (e >>> ENTITY_INDEX_BITS) & ENTITY_GEN_MASK;
}
/** Construct an Entity from an index + generation pair. */
export function makeEntity(index: number, generation: number): Entity {
// Build via multiply + `>>> 0` rather than `<<`: `gen << 22` would overflow
// int32 (go negative) for high generations. The product is < 2^32, and
// `>>> 0` coerces it to the same unsigned value C++ stores in Entity::raw.
return (((generation & ENTITY_GEN_MASK) * ENTITY_INDEX_COUNT + (index & ENTITY_INDEX_MASK)) >>> 0) as Entity;
}
/**
* JS-side invalid-entity sentinel.
*
* NOTE: this is `0` for legacy serialization compatibility — scenes written
* before this packing was documented use `0` to mean "no entity reference".
* C++ uses `0xFFFFFFFF` as its sentinel; producers/consumers at the WASM
* boundary must translate between the two. New code should prefer
* `isValidEntity()` over comparing against this constant directly.
*/
export const INVALID_ENTITY = 0 as Entity;
/** True when the handle is neither the JS nor C++ invalid sentinel. */
export function isValidEntity(e: Entity): boolean {
return e !== INVALID_ENTITY && e !== 0xFFFFFFFF;
}
export type TextureHandle = number;
export const INVALID_TEXTURE = 0 as TextureHandle;
export type FontHandle = number;
export const INVALID_FONT = 0 as FontHandle;
export const INVALID_MATERIAL = 0;
// =============================================================================
// Math Types
// =============================================================================
/**
* A 2D vector in world units. Plain data, so it is what a component field holds
* and what crosses to the engine — `v2` builds one, and `scalar`/`v2` carry the
* operations rather than the value.
*
* @public
*/
export interface Vec2 {
x: number;
y: number;
}
/**
* A 3D vector. `z` orders drawing within a layer rather than adding depth: the
* renderer is 2D, and a Transform's z is a sort key.
*
* @public
*/
export interface Vec3 {
x: number;
y: number;
z: number;
}
/**
* Four components, for a shader uniform or a rect passed as one value.
*
* @public
*/
export interface Vec4 {
x: number;
y: number;
z: number;
w: number;
}
/**
* A rotation. Stored as a quaternion because the engine composes transforms
* with it; for 2D work, `quat`'s helpers and `quaternionToAngle2D` are the way
* in and out of an angle.
*
* @public
*/
export interface Quat {
w: number;
x: number;
y: number;
z: number;
}
/**
* A colour with straight (non-premultiplied) alpha, each channel 0..1.
*
* @public
*/
export interface Color {
r: number;
g: number;
b: number;
a: number;
}
// =============================================================================
// Factory Functions
// =============================================================================
export const vec2 = (x = 0, y = 0): Vec2 => ({ x, y });
export const vec3 = (x = 0, y = 0, z = 0): Vec3 => ({ x, y, z });
export const vec4 = (x = 0, y = 0, z = 0, w = 1): Vec4 => ({ x, y, z, w });
export const color = (r = 1, g = 1, b = 1, a = 1): Color => ({ r, g, b, a });
export const quat = (w = 1, x = 0, y = 0, z = 0): Quat => ({ w, x, y, z });