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
import type { App } from '../app/app';
import type { Color } from '../types';
import type { TransformData, CanvasData } from '../ecs/component';
import type { ResourceDef } from '../ecs/resource';
import type { RigidBody2DData } from './PhysicsComponents';
import type { Physics2DEventsData } from './Physics2DPlugin';
import { Transform, Canvas } from '../ecs/component';
import { Draw } from '../render/draw';
import { defineResource } from '../ecs/resource';
import { registerDrawCallback } from '../render/customDraw';
import { RigidBody2D, BodyType } from './PhysicsComponents';
import { readCollider2DShapes, shapeCenter, collider2DOutline } from './ColliderShape2D';
export interface Physics2DDebugDrawConfig {
enabled: boolean;
showColliders: boolean;
showVelocity: boolean;
showContacts: boolean;
}
export const Physics2DDebugDraw = defineResource<Physics2DDebugDrawConfig>({
enabled: false,
showColliders: true,
showVelocity: false,
showContacts: false,
}, 'Physics2DDebugDraw');
interface VelocityProvider {
getLinearVelocity(entity: number): { x: number; y: number };
}
const STATIC_COLOR: Color = { r: 0.2, g: 0.4, b: 1.0, a: 0.7 };
const DYNAMIC_COLOR: Color = { r: 0.2, g: 1.0, b: 0.2, a: 0.7 };
const KINEMATIC_COLOR: Color = { r: 0.2, g: 1.0, b: 1.0, a: 0.7 };
const SENSOR_COLOR: Color = { r: 1.0, g: 1.0, b: 0.2, a: 0.5 };
const VELOCITY_COLOR: Color = { r: 1.0, g: 0.2, b: 0.2, a: 0.8 };
const CONTACT_COLOR: Color = { r: 1.0, g: 0.2, b: 0.2, a: 1.0 };
/** The outline the solver declined — drawn faintly, in the colour of a mistake. */
const DECLINED_COLOR: Color = { r: 1.0, g: 0.35, b: 0.1, a: 0.45 };
const DEBUG_LINE_THICKNESS = 1.5;
const CONTACT_POINT_RADIUS = 3;
const VELOCITY_SCALE = 0.5;
const CIRCLE_SEGMENTS = 32;
function quatToAngleZ(q: { w: number; x: number; y: number; z: number }): number {
return Math.atan2(2 * (q.w * q.z + q.x * q.y), 1 - 2 * (q.y * q.y + q.z * q.z));
}
function bodyTypeColor(bodyType: number): Color {
switch (bodyType) {
case BodyType.Static: return STATIC_COLOR;
case BodyType.Kinematic: return KINEMATIC_COLOR;
case BodyType.Dynamic: return DYNAMIC_COLOR;
default: return DYNAMIC_COLOR;
}
}
function readPixelsPerUnit(app: App): number {
const entities = app.world.getEntitiesWithComponents([Canvas]);
for (const entity of entities) {
const canvas = app.world.get(entity, Canvas) as CanvasData;
if (canvas && canvas.pixelsPerUnit) {
return canvas.pixelsPerUnit;
}
}
return 100;
}
function drawVelocityArrow(
x: number, y: number,
vx: number, vy: number,
): void {
const endX = x + vx * VELOCITY_SCALE;
const endY = y + vy * VELOCITY_SCALE;
Draw.line({ x, y }, { x: endX, y: endY }, VELOCITY_COLOR, DEBUG_LINE_THICKNESS);
const len = Math.sqrt(vx * vx + vy * vy);
if (len < 1) return;
const ARROWHEAD_LENGTH = 6;
const ARROWHEAD_ANGLE = Math.PI / 6;
const dirX = vx / len;
const dirY = vy / len;
const leftX = endX - ARROWHEAD_LENGTH * (dirX * Math.cos(ARROWHEAD_ANGLE) - dirY * Math.sin(ARROWHEAD_ANGLE));
const leftY = endY - ARROWHEAD_LENGTH * (dirX * Math.sin(ARROWHEAD_ANGLE) + dirY * Math.cos(ARROWHEAD_ANGLE));
const rightX = endX - ARROWHEAD_LENGTH * (dirX * Math.cos(ARROWHEAD_ANGLE) + dirY * Math.sin(ARROWHEAD_ANGLE));
const rightY = endY - ARROWHEAD_LENGTH * (-dirX * Math.sin(ARROWHEAD_ANGLE) + dirY * Math.cos(ARROWHEAD_ANGLE));
Draw.line({ x: endX, y: endY }, { x: leftX, y: leftY }, VELOCITY_COLOR, DEBUG_LINE_THICKNESS);
Draw.line({ x: endX, y: endY }, { x: rightX, y: rightY }, VELOCITY_COLOR, DEBUG_LINE_THICKNESS);
}
export function drawPhysics2DDebug(
app: App,
physicsApiRes: ResourceDef<VelocityProvider>,
physicsEventsRes: ResourceDef<Physics2DEventsData>,
): void {
const config = app.getResource<Physics2DDebugDrawConfig>(Physics2DDebugDraw);
if (!config || !config.enabled) return;
const ppu = readPixelsPerUnit(app);
const entities = app.world.getEntitiesWithComponents([RigidBody2D, Transform]);
let physics: VelocityProvider | null = null;
if (config.showVelocity && app.hasResource(physicsApiRes)) {
physics = app.getResource<VelocityProvider>(physicsApiRes);
}
for (const entity of entities) {
const rb = app.world.get(entity, RigidBody2D) as RigidBody2DData;
if (!rb.enabled) continue;
const wt = app.world.get(entity, Transform) as TransformData;
const wx = wt.worldPosition.x;
const wy = wt.worldPosition.y;
const angle = quatToAngleZ(wt.worldRotation);
if (config.showColliders) {
// One projection for every shape: read the collider(s), take the offset+rotation
// centre, and stroke the world-space outline. Same geometry the per-type branches
// produced, now shared with the editor gizmo (see Collider2DShape).
for (const { shape, isSensor, enabled } of readCollider2DShapes(app.world, entity)) {
if (!enabled) continue; // no shape in the world → nothing to outline
const color = isSensor ? SENSOR_COLOR : bodyTypeColor(rb.bodyType);
const center = shapeCenter(shape, { x: wx, y: wy }, angle, ppu);
const outline = collider2DOutline(shape, center, angle, ppu);
for (const pl of outline.polylines) {
for (let i = 0; i + 1 < pl.length; i++) {
Draw.line(pl[i], pl[i + 1], color, DEBUG_LINE_THICKNESS);
}
}
for (const circ of outline.circles) {
Draw.circleOutline(circ.c, circ.r, color, DEBUG_LINE_THICKNESS, CIRCLE_SEGMENTS);
}
// What was authored past what collides: a concave polygon's filled-in
// notch. Without it the overlay draws a hull nobody wrote and reads as
// the collider having moved.
for (const pl of outline.declined ?? []) {
for (let i = 0; i + 1 < pl.length; i++) {
Draw.line(pl[i], pl[i + 1], DECLINED_COLOR, DEBUG_LINE_THICKNESS);
}
}
}
}
if (config.showVelocity && physics && rb.bodyType === BodyType.Dynamic) {
const vel = physics.getLinearVelocity(entity);
drawVelocityArrow(wx, wy, vel.x * ppu, vel.y * ppu);
}
}
if (config.showContacts && app.hasResource(physicsEventsRes)) {
const events = app.getResource<Physics2DEventsData>(physicsEventsRes);
for (const collision of events.collisionEnters) {
Draw.circle(
{ x: collision.contactX, y: collision.contactY },
CONTACT_POINT_RADIUS,
CONTACT_COLOR,
true,
CIRCLE_SEGMENTS,
);
}
}
}
export function setupPhysics2DDebugDraw(
app: App,
physicsApiRes: ResourceDef<VelocityProvider>,
physicsEventsRes: ResourceDef<Physics2DEventsData>,
): void {
app.insertResource(Physics2DDebugDraw, {
enabled: false,
showColliders: true,
showVelocity: false,
showContacts: false,
});
registerDrawCallback('physics-debug-draw', () => {
drawPhysics2DDebug(app, physicsApiRes, physicsEventsRes);
});
}