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 geometry.ts
* @brief Geometry API for custom mesh rendering
* @details Provides geometry creation and management for custom shapes,
* particles, trails, and other procedural meshes.
*/
import type { ESEngineModule } from '../wasm';
import { CoreApiBridge } from '../wasm/CoreApiBridge';
// =============================================================================
// Types
// =============================================================================
export type GeometryHandle = number;
export enum DataType {
Float = 1,
Float2 = 2,
Float3 = 3,
Float4 = 4,
Int = 5,
Int2 = 6,
Int3 = 7,
Int4 = 8,
}
export interface VertexAttributeDescriptor {
name: string;
type: DataType;
}
export interface GeometryOptions {
vertices: Float32Array;
layout: VertexAttributeDescriptor[];
indices?: Uint16Array | Uint32Array;
dynamic?: boolean;
}
// =============================================================================
// Internal State
// =============================================================================
const bridge = new CoreApiBridge('geometry');
let module: ESEngineModule | null = null;
let vertexPtr: number = 0;
let indexPtr: number = 0;
let layoutPtr: number = 0;
const VERTEX_BUFFER_SIZE = 64 * 1024;
const INDEX_BUFFER_SIZE = 16 * 1024;
const LAYOUT_BUFFER_SIZE = 64;
// =============================================================================
// Initialization
// =============================================================================
/** @internal Wired by the engine plugins — not part of the public API. */
export function initGeometryAPI(wasmModule: ESEngineModule): void {
bridge.connect(wasmModule);
module = bridge.module;
vertexPtr = module._malloc(VERTEX_BUFFER_SIZE * 4);
indexPtr = module._malloc(INDEX_BUFFER_SIZE * 4);
layoutPtr = module._malloc(LAYOUT_BUFFER_SIZE * 4);
}
export function shutdownGeometryAPI(): void {
if (module) {
if (vertexPtr) module._free(vertexPtr);
if (indexPtr) module._free(indexPtr);
if (layoutPtr) module._free(layoutPtr);
vertexPtr = 0;
indexPtr = 0;
layoutPtr = 0;
}
bridge.disconnect();
module = null;
}
// =============================================================================
// Geometry API
// =============================================================================
function getModule(): ESEngineModule {
if (!module) {
throw new Error('Geometry API not initialized. Call initGeometryAPI() first.');
}
return module;
}
export const Geometry = {
/**
* Creates a new geometry with vertices and optional indices.
* @param options Geometry creation options
* @returns Geometry handle
*/
create(options: GeometryOptions): GeometryHandle {
const m = getModule();
const handle = m.geometry_create();
if (handle === 0) {
throw new Error('Failed to create geometry');
}
const vertexCount = options.vertices.length;
if (vertexCount * 4 > VERTEX_BUFFER_SIZE * 4) {
throw new Error(`Vertex data too large: ${vertexCount} floats (max ${VERTEX_BUFFER_SIZE})`);
}
m.HEAPF32.set(options.vertices, vertexPtr / 4);
const layoutCount = options.layout.length;
const layoutArray = new Int32Array(layoutCount);
for (let i = 0; i < layoutCount; i++) {
layoutArray[i] = options.layout[i].type;
}
const heap32 = new Int32Array(m.HEAPU8.buffer, layoutPtr, layoutCount);
heap32.set(layoutArray);
m.geometry_init(
handle,
vertexPtr,
vertexCount,
layoutPtr,
layoutCount,
options.dynamic ?? false
);
if (options.indices) {
const indexCount = options.indices.length;
if (indexCount * 4 > INDEX_BUFFER_SIZE * 4) {
throw new Error(`Index data too large: ${indexCount} indices (max ${INDEX_BUFFER_SIZE})`);
}
if (options.indices instanceof Uint16Array) {
const heap16 = new Uint16Array(m.HEAPU8.buffer, indexPtr, indexCount);
heap16.set(options.indices);
m.geometry_setIndices16(handle, indexPtr, indexCount);
} else {
const heap32 = new Uint32Array(m.HEAPU8.buffer, indexPtr, indexCount);
heap32.set(options.indices);
m.geometry_setIndices32(handle, indexPtr, indexCount);
}
}
return handle;
},
/**
* Updates vertices of a dynamic geometry.
* @param handle Geometry handle
* @param vertices New vertex data
* @param offset Offset in floats
*/
updateVertices(handle: GeometryHandle, vertices: Float32Array, offset = 0): void {
const m = getModule();
const vertexCount = vertices.length;
if (vertexCount * 4 > VERTEX_BUFFER_SIZE * 4) {
throw new Error(`Vertex data too large: ${vertexCount} floats (max ${VERTEX_BUFFER_SIZE})`);
}
m.HEAPF32.set(vertices, vertexPtr / 4);
m.geometry_updateVertices(handle, vertexPtr, vertexCount, offset);
},
/**
* Releases a geometry.
* @param handle Geometry handle
*/
release(handle: GeometryHandle): void {
if (handle > 0) {
getModule().geometry_release(handle);
}
},
/**
* Checks if a geometry handle is valid.
* @param handle Geometry handle
* @returns True if valid
*/
isValid(handle: GeometryHandle): boolean {
if (!module || handle <= 0) return false;
return module.geometry_isValid(handle);
},
// =========================================================================
// Helper Functions
// =========================================================================
/**
* Creates a unit quad geometry (1x1, centered at origin).
* @returns Geometry handle
*/
createQuad(width = 1, height = 1): GeometryHandle {
const hw = width / 2;
const hh = height / 2;
return Geometry.create({
vertices: new Float32Array([
// x, y, u, v
-hw, -hh, 0, 0,
hw, -hh, 1, 0,
hw, hh, 1, 1,
-hw, hh, 0, 1,
]),
layout: [
{ name: 'a_position', type: DataType.Float2 },
{ name: 'a_texCoord', type: DataType.Float2 },
],
indices: new Uint16Array([0, 1, 2, 2, 3, 0]),
});
},
/**
* Creates a circle geometry.
* @param radius Circle radius
* @param segments Number of segments
* @returns Geometry handle
*/
createCircle(radius = 1, segments = 32): GeometryHandle {
const vertices: number[] = [];
const indices: number[] = [];
vertices.push(0, 0, 0.5, 0.5);
for (let i = 0; i <= segments; i++) {
const angle = (i / segments) * Math.PI * 2;
const x = Math.cos(angle) * radius;
const y = Math.sin(angle) * radius;
const u = (Math.cos(angle) + 1) / 2;
const v = (Math.sin(angle) + 1) / 2;
vertices.push(x, y, u, v);
}
for (let i = 1; i <= segments; i++) {
indices.push(0, i, i + 1);
}
return Geometry.create({
vertices: new Float32Array(vertices),
layout: [
{ name: 'a_position', type: DataType.Float2 },
{ name: 'a_texCoord', type: DataType.Float2 },
],
indices: new Uint16Array(indices),
});
},
/**
* Creates a polygon geometry from vertices.
* @param points Array of {x, y} points
* @returns Geometry handle
*/
createPolygon(points: Array<{ x: number; y: number }>): GeometryHandle {
if (points.length < 3) {
throw new Error('Polygon must have at least 3 points');
}
let minX = Infinity, minY = Infinity;
let maxX = -Infinity, maxY = -Infinity;
for (const p of points) {
minX = Math.min(minX, p.x);
minY = Math.min(minY, p.y);
maxX = Math.max(maxX, p.x);
maxY = Math.max(maxY, p.y);
}
// A polygon that is degenerate on an axis (all points share an x or y)
// has a zero span there; guard the divide so UVs stay finite (0) instead
// of NaN/Inf poisoning the vertex buffer for any textured use.
const spanX = maxX - minX;
const spanY = maxY - minY;
const vertices: number[] = [];
for (const p of points) {
const u = spanX > 0 ? (p.x - minX) / spanX : 0;
const v = spanY > 0 ? (p.y - minY) / spanY : 0;
vertices.push(p.x, p.y, u, v);
}
const indices: number[] = [];
for (let i = 1; i < points.length - 1; i++) {
indices.push(0, i, i + 1);
}
return Geometry.create({
vertices: new Float32Array(vertices),
layout: [
{ name: 'a_position', type: DataType.Float2 },
{ name: 'a_texCoord', type: DataType.Float2 },
],
indices: new Uint16Array(indices),
});
},
};