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.

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