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.

4.6 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    Physics3DComponents.ts
 * @brief   The 3D world's components, as a scene authors them.
 * @details Their own set rather than a third dimension on the 2D ones: a 2D scene
 *          keeps the solver, units and feel it already has, and pays nothing for a
 *          world it never asks for.
 */
import { defineBuiltin } from '../ecs/component';
import type {
    RigidBody3DData, BoxCollider3DData, SphereCollider3DData, CapsuleCollider3DData,
    CharacterController3DData, MeshCollider3DData, ConvexCollider3DData,
} from '../ecs/component.generated';

export type {
    RigidBody3DData, BoxCollider3DData, SphereCollider3DData, CapsuleCollider3DData,
    CharacterController3DData, MeshCollider3DData, ConvexCollider3DData,
};

export const RigidBody3D = defineBuiltin<RigidBody3DData>('RigidBody3D', {
    bodyType: 2,
    layer: 0,
    gravityScale: 1.0,
    linearDamping: 0.05,
    angularDamping: 0.05,
    fixedRotation: false,
    continuousCollision: false,
    enabled: true,
    mass: 0,
}, {
    fields: {
        mass: { min: 0, tooltip: 'Kilograms. 0 = from its shape at the density of water (a ball of 10 cm radius is 4.2 kg).' },
        linearDamping: { min: 0, advanced: true },
        angularDamping: { min: 0, advanced: true },
        fixedRotation: { advanced: true },
        continuousCollision: { advanced: true,
                               tooltip: 'Check the whole path a step covers — what a bullet needs' },
    },
});

export const BoxCollider3D = defineBuiltin<BoxCollider3DData>('BoxCollider3D', {
    // World units at the reference 100 a metre (a 1 m box), scaled by the project's units per metre.
    halfExtents: { x: 50, y: 50, z: 50 },
    center: { x: 0, y: 0, z: 0 },
    friction: 0.3,
    restitution: 0.0,
    isSensor: false,
    enabled: true,
});

export const SphereCollider3D = defineBuiltin<SphereCollider3DData>('SphereCollider3D', {
    radius: 50,
    center: { x: 0, y: 0, z: 0 },
    friction: 0.3,
    restitution: 0.0,
    isSensor: false,
    enabled: true,
});

export const CapsuleCollider3D = defineBuiltin<CapsuleCollider3DData>('CapsuleCollider3D', {
    radius: 30,
    halfHeight: 50,
    center: { x: 0, y: 0, z: 0 },
    friction: 0.3,
    restitution: 0.0,
    isSensor: false,
    enabled: true,
});

/**
 * Imported geometry used as it is, for a level to collide against. Always static:
 * a triangle soup has no inertia tensor, so there is nothing for a solver to push.
 *
 * @experimental
 */
export const MeshCollider3D = defineBuiltin<MeshCollider3DData>('MeshCollider3D', {
    mesh: 0,
    layer: 0,
    friction: 0.3,
    restitution: 0.0,
    enabled: true,
});

/**
 * The convex hull of imported geometry — what a `MeshCollider3D` cannot be. A
 * triangle soup has no inertia tensor and is scenery whatever its body says; a
 * hull is a volume a solver pushes as readily as a box.
 *
 * @experimental
 */
export const ConvexCollider3D = defineBuiltin<ConvexCollider3DData>('ConvexCollider3D', {
    mesh: 0,
    friction: 0.3,
    restitution: 0.0,
    isSensor: false,
    enabled: true,
});

/**
 * A kinematic mover for a 3D player or NPC: swept against the world rather than
 * solved in it. Set `velocity` each step and read `isOnFloor` back; the vertical
 * component is carried for you, so a zero there means "walk", not "hang".
 *
 * @experimental
 */
export const CharacterController3D = defineBuiltin<CharacterController3DData>(
    'CharacterController3D', {
        velocity: { x: 0, y: 0, z: 0 },
        // World units at the reference 100 a metre (a 1.6 m person), scaled by the project's units per metre.
        radius: 30,
        halfHeight: 50,
        maxSlope: 0.87,
        layer: 0,
        stepHeight: 40,
        snapDown: 50,
        mass: 70,
        pushForce: 5000,
        enabled: true,
        isOnFloor: false,
        floorNormal: { x: 0, y: 0, z: 0 },
        realVelocity: { x: 0, y: 0, z: 0 },
    }, {
        fields: {
            maxSlope: { min: 0, max: 1.5708, step: 0.01, unit: 'rad',
                        tooltip: 'Steepest ground it can stand on' },
            stepHeight: { min: 0, step: 0.05, advanced: true },
            snapDown: { min: 0, step: 0.05, advanced: true },
            mass: { min: 0, advanced: true },
            pushForce: { min: 0, advanced: true,
                         tooltip: 'How hard it can shove what it walks into' },
            layer: { min: 0, max: 15, step: 1, advanced: true },
            isOnFloor: { advanced: true },
            floorNormal: { advanced: true },
            realVelocity: { advanced: true },
        },
    });