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 ColliderShape3D.ts
* @brief The single geometry projection over the 3D collider components — the
* shared seam for every visualizer of the 3D world.
* @details A 3D collider is invisible in a way a 2D one never was: the shape is
* not the sprite, the entity may be rotated on three axes, and nothing
* on screen says how big the box around a model is. This reads the
* components into shape descriptors and emits wireframes from them, so
* the editor gizmo and any runtime overlay draw the same geometry.
*
* What it reports is what the SOLVER builds, not what the scene carries:
* the running world gives an entity ONE body shape, chosen in the order
* {@link readCollider3DShapes} walks, and none at all without an enabled
* RigidBody3D. A gizmo that drew every authored collider would promise
* collisions that do not happen.
*
* Units: 3D collider fields are world units already (the system divides by
* pixels-per-unit on its way into the solver), so nothing here scales.
*/
import type { Entity, Vec3, Quat } from '../types';
import { isImplicitStatic } from './implicitStatic';
import { q } from '../math/quat';
import type { World } from '../ecs/world';
import {
RigidBody3D, BoxCollider3D, SphereCollider3D, CapsuleCollider3D,
MeshCollider3D, ConvexCollider3D, CharacterController3D,
} from './Physics3DComponents';
import type {
RigidBody3DData, BoxCollider3DData, SphereCollider3DData, CapsuleCollider3DData,
MeshCollider3DData, ConvexCollider3DData, CharacterController3DData,
} from './Physics3DComponents';
import { Transform } from '../ecs/component';
import { CompoundCollider3D, encodeCompoundParts } from './CompoundCollider3D';
import { getMeshCollision } from '../asset/meshCollision';
/** Points per full circle in a sphere/capsule wireframe. */
export const COLLIDER3D_RING_SEGMENTS = 24;
/** A 3D collider's geometry in entity-local space, in world units. */
export type Collider3DShape = { rotation?: Quat } & (
| { kind: 'box'; halfExtents: Vec3; center: Vec3 }
| { kind: 'sphere'; radius: number; center?: Vec3 }
| { kind: 'capsule'; radius: number; halfHeight: number; center?: Vec3 });
/** Which component authored a shape — the Inspector target behind a gizmo. */
export type Collider3DComponent =
| 'CompoundCollider3D' | 'BoxCollider3D' | 'SphereCollider3D' | 'CapsuleCollider3D'
| 'MeshCollider3D' | 'ConvexCollider3D' | 'CharacterController3D';
export interface Collider3DInstance {
component: Collider3DComponent;
shape: Collider3DShape;
isSensor: boolean;
/** Whether the running world builds this shape. False for a disabled collider,
* one shadowed by a higher-priority shape on the same entity, one whose mesh
* never loaded, or any collider on an entity with no enabled RigidBody3D —
* all authorable, none of them in the solver. */
active: boolean;
}
const ZERO: Vec3 = { x: 0, y: 0, z: 0 };
/** Turn a vector by a rotation — what places an anchor, an axis or a wireframe
* vertex in the world. The maths is the math module's; this is its name here. */
export function rotateVec3ByQuat(rot: Quat, v: Vec3): Vec3 {
return q.rotate(rot, v);
}
/** Local AABB of a loaded mesh's collision triangles, or null when nothing loaded them. */
function meshBounds(handle: number, scale: Vec3 = { x:1, y:1, z:1 }): { center: Vec3; halfExtents: Vec3 } | null {
const data = handle !== 0 ? getMeshCollision(handle) : null;
if (!data || data.positions.length < 3) return null;
const p = data.positions;
let minX = p[0]!, minY = p[1]!, minZ = p[2]!;
let maxX = minX, maxY = minY, maxZ = minZ;
for (let i = 3; i + 2 < p.length; i += 3) {
const x = p[i]!, y = p[i + 1]!, z = p[i + 2]!;
if (x < minX) minX = x; else if (x > maxX) maxX = x;
if (y < minY) minY = y; else if (y > maxY) maxY = y;
if (z < minZ) minZ = z; else if (z > maxZ) maxZ = z;
}
return {
center: { x: (minX + maxX) / 2 * scale.x, y: (minY + maxY) / 2 * scale.y, z: (minZ + maxZ) / 2 * scale.z },
halfExtents: { x: (maxX - minX) / 2 * Math.abs(scale.x), y: (maxY - minY) / 2 * Math.abs(scale.y), z: (maxZ - minZ) / 2 * Math.abs(scale.z) },
};
}
/**
* Every 3D collider on `entity`, each marked with whether it is the one the solver
* ends up building. The order mirrors `createBody` in Physics3DSystem — box, sphere,
* mesh, hull, capsule — and must keep mirroring it: a visualizer drawing a different
* shape than the world collides with is worse than none.
*/
export function readCollider3DShapes(world: World, entity: number): Collider3DInstance[] {
const out: Collider3DInstance[] = [];
const on = (c: { enabled?: boolean }): boolean => c.enabled !== false;
const body = world.has(entity, RigidBody3D)
? world.get(entity, RigidBody3D) as RigidBody3DData : null;
// With no RigidBody3D a collider is a static body of its own (implicitStatic.ts), as the world builds it.
const bodyLive = body !== null ? on(body) : isImplicitStatic(world, entity as Entity);
let taken = false;
if (world.has(entity, CompoundCollider3D)) {
const c = world.get(entity, CompoundCollider3D), scale = world.has(entity, Transform)
? world.get(entity, Transform).worldScale : { x: 1, y: 1, z: 1 };
const packet = encodeCompoundParts(c.parts, scale, 1);
taken = on(c) && c.parts.length > 0;
for (let i = 0; i < c.parts.length; i++) {
const p = packet.subarray(i * 11, (i + 1) * 11);
const common = { center: { x: p[4]!, y: p[5]!, z: p[6]! }, rotation: { x: p[7]!, y: p[8]!, z: p[9]!, w: p[10]! } };
const shape: Collider3DShape = p[0] === 0 ? { ...common, kind: 'box', halfExtents: { x: p[1]!, y: p[2]!, z: p[3]! } }
: p[0] === 1 ? { ...common, kind: 'sphere', radius: p[1]! } : { ...common, kind: 'capsule', radius: p[1]!, halfHeight: p[2]! };
out.push({ component: 'CompoundCollider3D', shape, isSensor: c.isSensor, active: taken && bodyLive });
}
}
const box = world.has(entity, BoxCollider3D)
? world.get(entity, BoxCollider3D) as BoxCollider3DData : null;
if (box) {
const chosen = !taken && on(box);
if (chosen) taken = true;
out.push({
component: 'BoxCollider3D',
shape: { kind: 'box', halfExtents: box.halfExtents, center: box.center ?? ZERO },
isSensor: box.isSensor === true,
active: chosen && bodyLive,
});
}
const sphere = world.has(entity, SphereCollider3D)
? world.get(entity, SphereCollider3D) as SphereCollider3DData : null;
if (sphere) {
const chosen = !taken && on(sphere);
if (chosen) taken = true;
out.push({
component: 'SphereCollider3D',
shape: { kind: 'sphere', radius: sphere.radius, ...(sphere.center ? { center: sphere.center } : {}) },
isSensor: sphere.isSensor === true,
active: chosen && bodyLive,
});
}
const mesh = world.has(entity, MeshCollider3D)
? world.get(entity, MeshCollider3D) as MeshCollider3DData : null;
if (mesh) {
// A mesh collider claims the entity's one body slot as soon as it names a
// mesh; whether that mesh loaded decides only if a body appears at all.
const chosen = !taken && on(mesh) && mesh.mesh !== 0;
if (chosen) taken = true;
const bounds = meshBounds(mesh.mesh, world.has(entity, Transform) ? world.get(entity, Transform).worldScale : undefined);
if (bounds) {
out.push({
component: 'MeshCollider3D',
shape: { kind: 'box', halfExtents: bounds.halfExtents, center: bounds.center },
isSensor: false,
active: chosen && bodyLive,
});
}
}
const hull = world.has(entity, ConvexCollider3D)
? world.get(entity, ConvexCollider3D) as ConvexCollider3DData : null;
if (hull) {
const chosen = !taken && on(hull) && hull.mesh !== 0;
if (chosen) taken = true;
const bounds = meshBounds(hull.mesh, world.has(entity, Transform) ? world.get(entity, Transform).worldScale : undefined);
if (bounds) {
out.push({
component: 'ConvexCollider3D',
shape: { kind: 'box', halfExtents: bounds.halfExtents, center: bounds.center },
isSensor: hull.isSensor === true,
active: chosen && bodyLive,
});
}
}
const capsule = world.has(entity, CapsuleCollider3D)
? world.get(entity, CapsuleCollider3D) as CapsuleCollider3DData : null;
if (capsule) {
const chosen = !taken && on(capsule);
if (chosen) taken = true;
out.push({
component: 'CapsuleCollider3D',
shape: { kind: 'capsule', radius: capsule.radius, halfHeight: capsule.halfHeight, ...(capsule.center ? { center: capsule.center } : {}) },
isSensor: capsule.isSensor === true,
active: chosen && bodyLive,
});
}
// A character is swept rather than solved, on its own path: it stands beside
// whatever body the entity has instead of competing for the slot.
const character = world.has(entity, CharacterController3D)
? world.get(entity, CharacterController3D) as CharacterController3DData : null;
if (character) {
out.push({
component: 'CharacterController3D',
shape: { kind: 'capsule', radius: character.radius, halfHeight: character.halfHeight },
isSensor: false,
active: on(character),
});
}
return out;
}
function ring(radius: number, axis: 'xy' | 'xz' | 'yz', offset: Vec3, segments: number): Vec3[] {
const pts: Vec3[] = [];
for (let i = 0; i <= segments; i++) {
const a = (i / segments) * Math.PI * 2;
const c = Math.cos(a) * radius;
const s = Math.sin(a) * radius;
pts.push(axis === 'xy' ? { x: offset.x + c, y: offset.y + s, z: offset.z }
: axis === 'xz' ? { x: offset.x + c, y: offset.y, z: offset.z + s }
: { x: offset.x, y: offset.y + c, z: offset.z + s });
}
return pts;
}
/** Half-circle cap from angle 0 to π, in the plane the axis names, around `offset`. */
function arc(radius: number, axis: 'xy' | 'zy', offset: Vec3, sign: 1 | -1, segments: number): Vec3[] {
const pts: Vec3[] = [];
for (let i = 0; i <= segments; i++) {
const a = (i / segments) * Math.PI;
const c = Math.cos(a) * radius;
const s = Math.sin(a) * radius * sign;
pts.push(axis === 'xy'
? { x: offset.x + c, y: offset.y + s, z: offset.z }
: { x: offset.x, y: offset.y + s, z: offset.z + c });
}
return pts;
}
/**
* The shape's wireframe as entity-local polylines (world units, unrotated).
* A box gives its 12 edges; a sphere three great circles; a capsule two rings,
* four caps and the four lines between them.
*/
export function collider3DWireframe(shape: Collider3DShape, segments = COLLIDER3D_RING_SEGMENTS): Vec3[][] {
if (shape.rotation) {
const lines = collider3DWireframe({ ...shape, rotation: undefined, center: ZERO }, segments);
return placeCollider3DWireframe(lines, shape.center ?? ZERO, shape.rotation);
}
const lines = centredWireframe(shape, segments);
const c = shape.kind === 'box' ? undefined : shape.center;
return c ? lines.map((line) => line.map((p) => ({ x: p.x + c.x, y: p.y + c.y, z: p.z + c.z }))) : lines;
}
function centredWireframe(shape: Collider3DShape, segments: number): Vec3[][] {
if (shape.kind === 'box') {
const { center: c, halfExtents: h } = shape;
const corner = (sx: number, sy: number, sz: number): Vec3 =>
({ x: c.x + sx * h.x, y: c.y + sy * h.y, z: c.z + sz * h.z });
const face = (sy: number): Vec3[] => [
corner(-1, sy, -1), corner(1, sy, -1), corner(1, sy, 1), corner(-1, sy, 1), corner(-1, sy, -1),
];
const posts: Vec3[][] = [];
for (const [sx, sz] of [[-1, -1], [1, -1], [1, 1], [-1, 1]] as const) {
posts.push([corner(sx, -1, sz), corner(sx, 1, sz)]);
}
return [face(-1), face(1), ...posts];
}
if (shape.kind === 'sphere') {
const r = shape.radius;
return [
ring(r, 'xy', ZERO, segments),
ring(r, 'xz', ZERO, segments),
ring(r, 'yz', ZERO, segments),
];
}
// Capsule: Y-up, the axis Jolt's CapsuleShape uses, so a wireframe rotated by
// the entity lands on the shape the solver built.
const { radius: r, halfHeight: hh } = shape;
const top: Vec3 = { x: 0, y: hh, z: 0 };
const bottom: Vec3 = { x: 0, y: -hh, z: 0 };
const half = Math.max(2, Math.round(segments / 2));
const posts: Vec3[][] = [];
for (const [sx, sz] of [[1, 0], [-1, 0], [0, 1], [0, -1]] as const) {
posts.push([
{ x: sx * r, y: -hh, z: sz * r },
{ x: sx * r, y: hh, z: sz * r },
]);
}
return [
ring(r, 'xz', top, segments),
ring(r, 'xz', bottom, segments),
arc(r, 'xy', top, 1, half),
arc(r, 'zy', top, 1, half),
arc(r, 'xy', bottom, -1, half),
arc(r, 'zy', bottom, -1, half),
...posts,
];
}
/**
* Local polylines placed in the world by an entity's position and rotation.
*
* Scale is deliberately left out: the solver builds the shape from the collider's
* own numbers, so a scaled entity still collides at its authored size and a gizmo
* that grew with the scale would be drawing a body that does not exist.
*/
export function placeCollider3DWireframe(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][] {
return lines.map((line) => line.map((p) => {
const r = rotateVec3ByQuat(rotation, p);
return { x: position.x + r.x, y: position.y + r.y, z: position.z + r.z };
}));
}
/** Points around a sphere or capsule when it is turned into triangles. Coarser
* than the wireframe: this feeds a voxeliser, which rounds everything onto its
* own grid anyway, and every extra ring is triangles it has to rasterise. */
const SOLID_SEGMENTS = 8;
/**
* The shape as a closed triangle soup in entity-local space, wound so a face's
* normal points OUT — which way a face points is part of the answer to a caller
* like a navigation bake, where an upward normal is what makes a triangle ground
* rather than wall. The sibling of {@link collider3DWireframe}, in triangles.
*/
export function collider3DTriangles(
shape: Collider3DShape,
): { positions: Float32Array; indices: Uint32Array } {
if (shape.rotation) {
const data = collider3DTriangles({ ...shape, rotation: undefined, center: ZERO });
const c = shape.center ?? ZERO;
for (let i = 0; i < data.positions.length; i += 3) {
const p = q.rotate(shape.rotation, { x: data.positions[i]!, y: data.positions[i + 1]!, z: data.positions[i + 2]! });
data.positions.set([p.x + c.x, p.y + c.y, p.z + c.z], i);
}
return data;
}
if (shape.kind === 'box') {
const { center: c, halfExtents: h } = shape;
const positions = new Float32Array(8 * 3);
let n = 0;
for (const sy of [-1, 1] as const) {
for (const [sx, sz] of [[-1, -1], [1, -1], [1, 1], [-1, 1]] as const) {
positions[n++] = c.x + sx * h.x;
positions[n++] = c.y + sy * h.y;
positions[n++] = c.z + sz * h.z;
}
}
return { positions, indices: Uint32Array.from(BOX_INDICES) };
}
// A capsule is a sphere cut at its equator and pulled apart, so both are the
// same stack of rings with the two halves offset — and the equator ring
// appears twice, which is what makes the straight wall between them.
const radius = shape.radius;
const halfHeight = shape.kind === 'capsule' ? shape.halfHeight : 0;
const off = shape.center ?? ZERO;
const rings = SOLID_SEGMENTS;
const segs = SOLID_SEGMENTS;
const rows = rings + 2;
const positions = new Float32Array(rows * (segs + 1) * 3);
let n = 0;
for (let r = 0; r < rows; r++) {
const upper = r <= rings / 2;
const phi = ((upper ? r : r - 1) / rings) * Math.PI;
const y = Math.cos(phi) * radius + (upper ? halfHeight : -halfHeight);
const ringRadius = Math.sin(phi) * radius;
for (let s = 0; s <= segs; s++) {
const theta = (s / segs) * Math.PI * 2;
positions[n++] = Math.cos(theta) * ringRadius + off.x;
positions[n++] = y + off.y;
positions[n++] = Math.sin(theta) * ringRadius + off.z;
}
}
const indices: number[] = [];
for (let r = 0; r + 1 < rows; r++) {
for (let s = 0; s < segs; s++) {
const a = r * (segs + 1) + s;
const b = a + segs + 1;
indices.push(a, a + 1, b, a + 1, b + 1, b);
}
}
return { positions, indices: Uint32Array.from(indices) };
}
/** The twelve triangles over the eight corners emitted above, every one of them
* wound counter-clockwise seen from outside the box. */
const BOX_INDICES: readonly number[] = [
0, 1, 2, 0, 2, 3,
4, 6, 5, 4, 7, 6,
0, 4, 5, 0, 5, 1,
1, 5, 6, 1, 6, 2,
2, 6, 7, 2, 7, 3,
3, 7, 4, 3, 4, 0,
];