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 Physics3DDebugDraw.ts
* @brief The 3D world's shapes, drawn by the running game.
* @details The editor gizmo answers "is this box the size I meant" while a scene
* is being authored. This answers the other question — "why did the
* player get stuck there" — which only the running game can be asked,
* and which the editor hides its own overlays for.
*
* Geometry comes from the same seam the gizmo projects
* ({@link readCollider3DShapes}), so the two can never disagree about
* which shape the solver built.
*/
import type { App } from '../app/app';
import type { Color } from '../types';
import { Transform } from '../ecs/component';
import type { TransformData } from '../ecs/component.generated';
import { Draw } from '../render/draw';
import { defineResource } from '../ecs/resource';
import { registerDrawCallback } from '../render/customDraw';
import { RigidBody3D, CharacterController3D } from './Physics3DComponents';
import type { RigidBody3DData } from './Physics3DComponents';
import {
readCollider3DShapes, collider3DWireframe, placeCollider3DWireframe,
} from './ColliderShape3D';
export interface Physics3DDebugDrawConfig {
enabled: boolean;
showColliders: boolean;
showContacts: boolean;
}
/** Off until a game turns it on: a debug overlay costs a line per edge per frame. */
export const Physics3DDebugDraw = defineResource<Physics3DDebugDrawConfig>({
enabled: false,
showColliders: true,
showContacts: false,
}, 'Physics3DDebugDraw');
const STATIC_COLOR: Color = { r: 0.2, g: 0.4, b: 1.0, a: 0.8 };
const DYNAMIC_COLOR: Color = { r: 0.2, g: 1.0, b: 0.2, a: 0.8 };
const KINEMATIC_COLOR: Color = { r: 0.2, g: 1.0, b: 1.0, a: 0.8 };
const SENSOR_COLOR: Color = { r: 1.0, g: 1.0, b: 0.2, a: 0.6 };
const CHARACTER_COLOR: Color = { r: 1.0, g: 0.6, b: 0.1, a: 0.9 };
const CONTACT_COLOR: Color = { r: 1.0, g: 0.2, b: 0.2, a: 1.0 };
/** World units. The 3D world is authored at 100 units to the metre, so this is
* about a centimetre — thin enough not to hide the shape it outlines. */
const LINE_THICKNESS = 2;
const CONTACT_CROSS = 8;
function bodyTypeColor(bodyType: number): Color {
switch (bodyType) {
case 0: return STATIC_COLOR;
case 1: return KINEMATIC_COLOR;
default: return DYNAMIC_COLOR;
}
}
interface Contact3D { pointX: number; pointY: number; pointZ: number }
export function drawPhysics3DDebug(app: App, contacts?: readonly Contact3D[]): void {
const config = app.getResource<Physics3DDebugDrawConfig>(Physics3DDebugDraw);
if (!config || !config.enabled) return;
if (config.showColliders) {
const world = app.world as unknown as Parameters<typeof readCollider3DShapes>[0];
for (const entity of app.world.getEntitiesWithComponents([Transform])) {
const instances = readCollider3DShapes(world, entity as number);
if (instances.length === 0) continue;
const t = app.world.get(entity, Transform) as TransformData;
const body = app.world.has(entity, RigidBody3D)
? app.world.get(entity, RigidBody3D) as RigidBody3DData : null;
for (const inst of instances) {
// What the solver did NOT build is not drawn here: the running
// game is not the place to see geometry that collides with
// nothing, and the editor already shows it while it is authored.
if (!inst.active) continue;
const color = inst.component === 'CharacterController3D' ? CHARACTER_COLOR
: inst.isSensor ? SENSOR_COLOR
: bodyTypeColor(body?.bodyType ?? 2);
const lines = placeCollider3DWireframe(
collider3DWireframe(inst.shape),
t.worldPosition, t.worldRotation);
for (const line of lines) {
for (let i = 0; i + 1 < line.length; i++) {
Draw.line3D(line[i]!, line[i + 1]!, color, LINE_THICKNESS);
}
}
}
}
}
if (config.showContacts && contacts) {
for (const c of contacts) {
const at = { x: c.pointX, y: c.pointY, z: c.pointZ };
for (const axis of [{ x: CONTACT_CROSS, y: 0, z: 0 },
{ x: 0, y: CONTACT_CROSS, z: 0 },
{ x: 0, y: 0, z: CONTACT_CROSS }]) {
Draw.line3D({ x: at.x - axis.x, y: at.y - axis.y, z: at.z - axis.z },
{ x: at.x + axis.x, y: at.y + axis.y, z: at.z + axis.z },
CONTACT_COLOR, LINE_THICKNESS);
}
}
}
}
/** Installed by the 3D physics plugin; the resource decides whether it draws. */
export function setupPhysics3DDebugDraw(app: App, contacts: () => readonly Contact3D[]): void {
app.insertResource(Physics3DDebugDraw, {
enabled: false, showColliders: true, showContacts: false,
});
registerDrawCallback('physics3d-debug-draw', () => {
drawPhysics3DDebug(app, contacts());
});
}