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.

14.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect, beforeEach, vi } from 'vitest';
import {
    Physics2DDebugDraw,
    drawPhysics2DDebug,
    setupPhysics2DDebugDraw,
    type Physics2DDebugDrawConfig,
} from '../src/physics/Physics2DDebugDraw';
import { BodyType } from '../src/physics/PhysicsComponents';
import { defineResource } from '../src/ecs/resource';
import type { ResourceDef } from '../src/ecs/resource';
import { clearDrawCallbacks, getDrawCallbacks } from '../src/render/customDraw';
import { clearUserComponents } from '../src/ecs/component';

vi.mock('../src/render/draw', () => ({
    Draw: {
        line: vi.fn(),
        circle: vi.fn(),
        circleOutline: vi.fn(),
        rect: vi.fn(),
        rectOutline: vi.fn(),
    },
}));

import { Draw } from '../src/render/draw';

interface MockEntity {
    components: Map<string, any>;
}

function createMockApp(entities: MockEntity[] = [], resources: Map<symbol, any> = new Map()) {
    const entityList = entities;
    const resourceMap = resources;
    return {
        world: {
            getEntitiesWithComponents: vi.fn((_comps: any[]) => {
                return entityList.map((_, i) => i);
            }),
            get: vi.fn((entityIdx: number, comp: any) => {
                const entity = entityList[entityIdx];
                return entity?.components.get(comp._name) ?? null;
            }),
            has: vi.fn((entityIdx: number, comp: any) => {
                const entity = entityList[entityIdx];
                return entity?.components.has(comp._name) ?? false;
            }),
        },
        getResource: vi.fn(<T,>(res: ResourceDef<T>): T | null => {
            return resourceMap.get(res._id) ?? null;
        }),
        hasResource: vi.fn((res: ResourceDef<any>) => {
            return resourceMap.has(res._id);
        }),
        insertResource: vi.fn((res: ResourceDef<any>, value: any) => {
            resourceMap.set(res._id, value);
        }),
    } as any;
}

function mockEntity(comps: Record<string, any>): MockEntity {
    const map = new Map<string, any>();
    for (const [name, data] of Object.entries(comps)) {
        map.set(name, data);
    }
    return { components: map };
}

const MockPhysicsAPI = defineResource<any>({}, 'MockPhysicsAPI');
const MockPhysicsEvents = defineResource<any>({}, 'MockPhysicsEvents');

describe('Physics2DDebugDraw resource', () => {
    it('should define resource with correct defaults', () => {
        expect(Physics2DDebugDraw._name).toBe('Physics2DDebugDraw');
        expect(Physics2DDebugDraw._default).toEqual({
            enabled: false,
            showColliders: true,
            showVelocity: false,
            showContacts: false,
        });
    });
});

describe('drawPhysics2DDebug', () => {
    beforeEach(() => {
        vi.clearAllMocks();
        clearUserComponents();
    });

    it('should do nothing when config is not present', () => {
        const app = createMockApp();
        drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);
        expect(Draw.line).not.toHaveBeenCalled();
        expect(Draw.circleOutline).not.toHaveBeenCalled();
    });

    it('should do nothing when enabled=false', () => {
        const resources = new Map<symbol, any>();
        resources.set(Physics2DDebugDraw._id, {
            enabled: false, showColliders: true, showVelocity: false, showContacts: false,
        });
        const app = createMockApp([], resources);

        drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);
        expect(Draw.line).not.toHaveBeenCalled();
    });

    it('should draw box collider when enabled', () => {
        const resources = new Map<symbol, any>();
        resources.set(Physics2DDebugDraw._id, {
            enabled: true, showColliders: true, showVelocity: false, showContacts: false,
        } as Physics2DDebugDrawConfig);

        const entity = mockEntity({
            RigidBody2D: { bodyType: BodyType.Static, enabled: true },
            Transform: {
                worldPosition: { x: 100, y: 200 },
                worldRotation: { w: 1, x: 0, y: 0, z: 0 },
            },
            BoxCollider2D: {
                halfExtents: { x: 0.5, y: 0.5 },
                offset: { x: 0, y: 0 },
                isSensor: false,
            },
        });

        const app = createMockApp([entity], resources);
        drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);

        expect(Draw.line).toHaveBeenCalledTimes(4);
    });

    it('should draw circle collider when enabled', () => {
        const resources = new Map<symbol, any>();
        resources.set(Physics2DDebugDraw._id, {
            enabled: true, showColliders: true, showVelocity: false, showContacts: false,
        } as Physics2DDebugDrawConfig);

        const entity = mockEntity({
            RigidBody2D: { bodyType: BodyType.Dynamic, enabled: true },
            Transform: {
                worldPosition: { x: 50, y: 50 },
                worldRotation: { w: 1, x: 0, y: 0, z: 0 },
            },
            CircleCollider2D: {
                radius: 1.0,
                offset: { x: 0, y: 0 },
                isSensor: false,
            },
        });

        const app = createMockApp([entity], resources);
        drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);

        expect(Draw.circleOutline).toHaveBeenCalledTimes(1);
    });

    it('should draw capsule collider when enabled', () => {
        const resources = new Map<symbol, any>();
        resources.set(Physics2DDebugDraw._id, {
            enabled: true, showColliders: true, showVelocity: false, showContacts: false,
        } as Physics2DDebugDrawConfig);

        const entity = mockEntity({
            RigidBody2D: { bodyType: BodyType.Dynamic, enabled: true },
            Transform: {
                worldPosition: { x: 0, y: 0 },
                worldRotation: { w: 1, x: 0, y: 0, z: 0 },
            },
            CapsuleCollider2D: {
                radius: 0.25,
                halfHeight: 0.5,
                offset: { x: 0, y: 0 },
                isSensor: false,
            },
        });

        const app = createMockApp([entity], resources);
        drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);

        // 2 side lines + 16 top arc segments + 16 bottom arc segments = 34
        expect(Draw.line).toHaveBeenCalledTimes(34);
    });

    it('should skip disabled rigid bodies', () => {
        const resources = new Map<symbol, any>();
        resources.set(Physics2DDebugDraw._id, {
            enabled: true, showColliders: true, showVelocity: false, showContacts: false,
        } as Physics2DDebugDrawConfig);

        const entity = mockEntity({
            RigidBody2D: { bodyType: BodyType.Dynamic, enabled: false },
            Transform: {
                worldPosition: { x: 0, y: 0 },
                worldRotation: { w: 1, x: 0, y: 0, z: 0 },
            },
            BoxCollider2D: {
                halfExtents: { x: 0.5, y: 0.5 },
                offset: { x: 0, y: 0 },
                isSensor: false,
            },
        });

        const app = createMockApp([entity], resources);
        drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);

        expect(Draw.line).not.toHaveBeenCalled();
    });

    it('should use sensor color for sensor colliders', () => {
        const resources = new Map<symbol, any>();
        resources.set(Physics2DDebugDraw._id, {
            enabled: true, showColliders: true, showVelocity: false, showContacts: false,
        } as Physics2DDebugDrawConfig);

        const entity = mockEntity({
            RigidBody2D: { bodyType: BodyType.Static, enabled: true },
            Transform: {
                worldPosition: { x: 0, y: 0 },
                worldRotation: { w: 1, x: 0, y: 0, z: 0 },
            },
            BoxCollider2D: {
                halfExtents: { x: 1, y: 1 },
                offset: { x: 0, y: 0 },
                isSensor: true,
            },
        });

        const app = createMockApp([entity], resources);
        drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);

        const calls = (Draw.line as any).mock.calls;
        expect(calls.length).toBe(4);
        const sensorColor = { r: 1.0, g: 1.0, b: 0.2, a: 0.5 };
        expect(calls[0][2]).toEqual(sensorColor);
    });

    it('should draw velocity arrows for dynamic bodies', () => {
        const resources = new Map<symbol, any>();
        resources.set(Physics2DDebugDraw._id, {
            enabled: true, showColliders: false, showVelocity: true, showContacts: false,
        } as Physics2DDebugDrawConfig);
        resources.set(MockPhysicsAPI._id, {
            getLinearVelocity: vi.fn().mockReturnValue({ x: 10, y: 5 }),
        });

        const entity = mockEntity({
            RigidBody2D: { bodyType: BodyType.Dynamic, enabled: true },
            Transform: {
                worldPosition: { x: 100, y: 200 },
                worldRotation: { w: 1, x: 0, y: 0, z: 0 },
            },
        });

        const app = createMockApp([entity], resources);
        drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);

        // velocity line + 2 arrowhead lines = 3
        expect(Draw.line).toHaveBeenCalledTimes(3);
    });

    it('should not draw velocity for static bodies', () => {
        const resources = new Map<symbol, any>();
        resources.set(Physics2DDebugDraw._id, {
            enabled: true, showColliders: false, showVelocity: true, showContacts: false,
        } as Physics2DDebugDrawConfig);
        resources.set(MockPhysicsAPI._id, {
            getLinearVelocity: vi.fn(),
        });

        const entity = mockEntity({
            RigidBody2D: { bodyType: BodyType.Static, enabled: true },
            Transform: {
                worldPosition: { x: 0, y: 0 },
                worldRotation: { w: 1, x: 0, y: 0, z: 0 },
            },
        });

        const app = createMockApp([entity], resources);
        drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);

        expect(Draw.line).not.toHaveBeenCalled();
    });

    it('should draw contact points when showContacts is enabled', () => {
        const resources = new Map<symbol, any>();
        resources.set(Physics2DDebugDraw._id, {
            enabled: true, showColliders: false, showVelocity: false, showContacts: true,
        } as Physics2DDebugDrawConfig);
        resources.set(MockPhysicsEvents._id, {
            collisionEnters: [
                { contactX: 10, contactY: 20 },
                { contactX: 30, contactY: 40 },
            ],
        });

        const app = createMockApp([], resources);
        drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);

        expect(Draw.circle).toHaveBeenCalledTimes(2);
    });

    it('should not draw contacts when Physics2DEvents resource is missing', () => {
        const resources = new Map<symbol, any>();
        resources.set(Physics2DDebugDraw._id, {
            enabled: true, showColliders: false, showVelocity: false, showContacts: true,
        } as Physics2DDebugDrawConfig);

        const app = createMockApp([], resources);
        drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);

        expect(Draw.circle).not.toHaveBeenCalled();
    });

    it('should use correct body type colors', () => {
        const resources = new Map<symbol, any>();
        resources.set(Physics2DDebugDraw._id, {
            enabled: true, showColliders: true, showVelocity: false, showContacts: false,
        } as Physics2DDebugDrawConfig);

        const staticEntity = mockEntity({
            RigidBody2D: { bodyType: BodyType.Static, enabled: true },
            Transform: { worldPosition: { x: 0, y: 0 }, worldRotation: { w: 1, x: 0, y: 0, z: 0 } },
            CircleCollider2D: { radius: 1, offset: { x: 0, y: 0 }, isSensor: false },
        });

        const dynamicEntity = mockEntity({
            RigidBody2D: { bodyType: BodyType.Dynamic, enabled: true },
            Transform: { worldPosition: { x: 0, y: 0 }, worldRotation: { w: 1, x: 0, y: 0, z: 0 } },
            CircleCollider2D: { radius: 1, offset: { x: 0, y: 0 }, isSensor: false },
        });

        const kinematicEntity = mockEntity({
            RigidBody2D: { bodyType: BodyType.Kinematic, enabled: true },
            Transform: { worldPosition: { x: 0, y: 0 }, worldRotation: { w: 1, x: 0, y: 0, z: 0 } },
            CircleCollider2D: { radius: 1, offset: { x: 0, y: 0 }, isSensor: false },
        });

        const app = createMockApp([staticEntity, dynamicEntity, kinematicEntity], resources);
        drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);

        expect(Draw.circleOutline).toHaveBeenCalledTimes(3);
        const calls = (Draw.circleOutline as any).mock.calls;

        const staticColor = { r: 0.2, g: 0.4, b: 1.0, a: 0.7 };
        const dynamicColor = { r: 0.2, g: 1.0, b: 0.2, a: 0.7 };
        const kinematicColor = { r: 0.2, g: 1.0, b: 1.0, a: 0.7 };

        expect(calls[0][2]).toEqual(staticColor);
        expect(calls[1][2]).toEqual(dynamicColor);
        expect(calls[2][2]).toEqual(kinematicColor);
    });

    it('should apply collider offset with rotation', () => {
        const resources = new Map<symbol, any>();
        resources.set(Physics2DDebugDraw._id, {
            enabled: true, showColliders: true, showVelocity: false, showContacts: false,
        } as Physics2DDebugDrawConfig);

        // 90 degree rotation: quat z=sin(45°), w=cos(45°)
        const angle = Math.PI / 2;
        const qW = Math.cos(angle / 2);
        const qZ = Math.sin(angle / 2);

        const entity = mockEntity({
            RigidBody2D: { bodyType: BodyType.Static, enabled: true },
            Transform: {
                worldPosition: { x: 100, y: 100 },
                worldRotation: { w: qW, x: 0, y: 0, z: qZ },
            },
            CircleCollider2D: {
                radius: 1,
                offset: { x: 1, y: 0 },
                isSensor: false,
            },
        });

        const app = createMockApp([entity], resources);
        drawPhysics2DDebug(app, MockPhysicsAPI, MockPhysicsEvents);

        expect(Draw.circleOutline).toHaveBeenCalledTimes(1);
        const call = (Draw.circleOutline as any).mock.calls[0];
        const center = call[0];
        // offset (1, 0) rotated 90° → (0, 1) * ppu=100
        expect(center.x).toBeCloseTo(100 + 0, 0);
        expect(center.y).toBeCloseTo(100 + 100, 0);
    });
});

describe('setupPhysics2DDebugDraw', () => {
    beforeEach(() => {
        clearDrawCallbacks();
    });

    it('should insert default resource and register draw callback', () => {
        const resources = new Map<symbol, any>();
        const app = createMockApp([], resources);

        setupPhysics2DDebugDraw(app, MockPhysicsAPI, MockPhysicsEvents);

        expect(app.insertResource).toHaveBeenCalledWith(Physics2DDebugDraw, {
            enabled: false, showColliders: true, showVelocity: false, showContacts: false,
        });

        const callbacks = getDrawCallbacks();
        expect(callbacks.has('physics-debug-draw')).toBe(true);
    });
});