Skip to content

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.

5.5 KB
Raw Blame
// 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 });