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.

9.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    RigidBody3D.hpp
 * @brief   A body the 3D world simulates, and the shapes that give it extent.
 * @details Its own components rather than a third dimension bolted onto the 2D
 *          ones: a 2D scene keeps the solver, the units and the feel it already
 *          has, and pays nothing for a world it never asks for. A scene picks one
 *          of the two — an entity carrying both is served by the 2D one, which was
 *          there first.
 *
 * @author  ESEngine Team
 * @date    2026
 *
 * @copyright Copyright (c) 2026 ESEngine Team
 *            Licensed under the Apache License, Version 2.0.
 */
#pragma once

#include "../../core/Types.hpp"
#include "../../core/Reflection.hpp"
#include "../../math/Math.hpp"
#include "./BodyType.hpp"

namespace esengine::ecs {

/**
 * @brief A body in the 3D world.
 *
 * @code
 * auto& body = registry.emplace<RigidBody3D>(e);
 * body.bodyType = BodyType::Dynamic;
 * @endcode
 */
ES_COMPONENT()
struct RigidBody3D {
    /** @brief Static never moves, Kinematic is moved by hand, Dynamic is solved. */
    ES_PROPERTY(enum=BodyType)
    BodyType bodyType{BodyType::Dynamic};

    /** @brief Scales this body's share of the world's gravity. 0 = weightless. */
    ES_PROPERTY(min=0)
    f32 gravityScale{1.0f};

    ES_PROPERTY(min=0)
    f32 linearDamping{0.05f};

    ES_PROPERTY(min=0)
    f32 angularDamping{0.05f};

    /** @brief Its mass in kilograms. 0 = as heavy as its shape at the density of water,
     *         a ball of 10 cm radius 4.2 kg; set it to make a hollow thing light or a small thing
     *         heavy. A static or kinematic body has none: nothing moves it. */
    ES_PROPERTY(min=0, tooltip="Kilograms. 0 = from its shape at the density of water (a ball of 10 cm radius is 4.2 kg).")
    f32 mass{0.0f};

    /** @brief Keeps the body upright: the solver may move it, never turn it. What a
     *         character on legs wants, and what a crate does not. */
    ES_PROPERTY()
    bool fixedRotation{false};

    /** @brief Which collision layer this body is in (0..15). ONE layer, unlike the
     *         2D world's category bits: Jolt classifies a body by a single id. */
    ES_PROPERTY(min=0, max=15, advanced)
    u32 layer{0};

    /** @brief Checks the whole path a step covers rather than where the body ended
     *         up. What a bullet needs: discrete collision only asks where a body IS,
     *         so anything crossing more than its own thickness in one step arrives
     *         on the far side of a wall having never touched it. Costs more, which
     *         is why it is off. */
    ES_PROPERTY(advanced)
    bool continuousCollision{false};

    /** @brief Disabled bodies are left out of the world entirely. */
    ES_PROPERTY()
    bool enabled{true};
};

/** @brief An axis-aligned box, sized in world units around the entity's origin. */
ES_COMPONENT()
struct BoxCollider3D {
    // World units at the reference 100 a metre, scaled by the project's units per metre (sdk ecs/worldUnits.ts).
    ES_PROPERTY()
    glm::vec3 halfExtents{50.0f, 50.0f, 50.0f};

    /** @brief Where the shape sits from the entity's origin, in world units; zero is centred on it. */
    ES_PROPERTY(optional)
    glm::vec3 center{0.0f, 0.0f, 0.0f};

    ES_PROPERTY(min=0)
    f32 friction{0.3f};

    ES_PROPERTY(min=0, max=1)
    f32 restitution{0.0f};

    /** @brief A sensor reports overlaps and stops nothing. */
    ES_PROPERTY()
    bool isSensor{false};

    ES_PROPERTY()
    bool enabled{true};
};

ES_COMPONENT()
struct SphereCollider3D {
    ES_PROPERTY(min=0)
    f32 radius{50.0f};

    /** @brief Where the shape sits from the entity's origin, in world units; zero is centred on it. */
    ES_PROPERTY(optional)
    glm::vec3 center{0.0f, 0.0f, 0.0f};

    ES_PROPERTY(min=0)
    f32 friction{0.3f};

    ES_PROPERTY(min=0, max=1)
    f32 restitution{0.0f};

    ES_PROPERTY()
    bool isSensor{false};

    ES_PROPERTY()
    bool enabled{true};
};

/**
 * @brief An upright capsule — the shape a character is.
 * @details Total height is `2*(halfHeight + radius)`: @ref halfHeight is the
 *          cylinder's half, and a cap of @ref radius sits on each end. Stated
 *          because the two are easy to swap and their SUM still holds a body at
 *          the same height, so a swap shows up only in how wide it is.
 */
ES_COMPONENT()
struct CapsuleCollider3D {
    ES_PROPERTY(min=0)
    f32 radius{30.0f};

    ES_PROPERTY(min=0)
    f32 halfHeight{50.0f};

    /** @brief Where the shape sits from the entity's origin, in world units; zero is centred on it. */
    ES_PROPERTY(optional)
    glm::vec3 center{0.0f, 0.0f, 0.0f};

    ES_PROPERTY(min=0)
    f32 friction{0.3f};

    ES_PROPERTY(min=0, max=1)
    f32 restitution{0.0f};

    ES_PROPERTY()
    bool isSensor{false};

    ES_PROPERTY()
    bool enabled{true};
};

/**
 * @brief Imported geometry, used as it is, for a level to collide against.
 *
 * @details What a box or a capsule cannot say: a terrain, a staircase, a room.
 *          ALWAYS STATIC whatever the RigidBody3D says — a triangle soup has no
 *          inertia tensor, so there is nothing for a solver to push. Its triangles
 *          are also ONE-SIDED: reversed winding stops nothing.
 */
ES_COMPONENT()
struct MeshCollider3D {
    /** @brief The geometry to collide against. Its triangles are used directly. */
    ES_PROPERTY(asset = mesh, tooltip="Geometry (.esmesh) to collide against.")
    resource::MeshHandle mesh;

    ES_PROPERTY(min=0)
    f32 friction{0.3f};

    ES_PROPERTY(min=0, max=1)
    f32 restitution{0.0f};

    /** @brief Which collision layer the geometry is in (0..15). */
    ES_PROPERTY(min=0, max=15, advanced)
    u32 layer{0};

    ES_PROPERTY()
    bool enabled{true};
};

/**
 * @brief The convex hull of imported geometry — a shape a solver can push.
 *
 * @details What MeshCollider3D cannot be: a triangle soup has no inertia tensor,
 *          so it can only ever be scenery. A hull is the tightest convex volume
 *          around the same vertices, which a rigid-body solver handles as easily
 *          as a box — a rock, a crate with a chamfer, a barrel that rolls.
 */
ES_COMPONENT()
struct ConvexCollider3D {
    /** @brief Geometry whose hull is the shape. Its concave detail is filled in. */
    ES_PROPERTY(asset = mesh, tooltip="Geometry (.esmesh) whose convex hull collides.")
    resource::MeshHandle mesh;

    ES_PROPERTY(min=0)
    f32 friction{0.3f};

    ES_PROPERTY(min=0, max=1)
    f32 restitution{0.0f};

    ES_PROPERTY()
    bool isSensor{false};

    ES_PROPERTY()
    bool enabled{true};
};

/**
 * @brief A kinematic mover for a 3D player or NPC.
 *
 * @details Swept against the world rather than solved in it, which is what lets it
 *          climb a step without inheriting the momentum of what it stands on. Set
 *          @ref velocity each step; the vertical component is carried for you, so a
 *          zero there means "walk". REPLACES a RigidBody3D rather than joining one.
 */
ES_COMPONENT()
struct CharacterController3D {
    /** @brief Desired velocity in world units/second. A positive y is a jump. */
    ES_PROPERTY()
    glm::vec3 velocity{0.0f, 0.0f, 0.0f};

    /** @brief World units, as every length here: these defaults are a 1.6 m person at the reference scale of 100 units
     *         a metre, and scale with the project's units per metre (sdk ecs/worldUnits.ts). They read 0.3 / 0.5 before —
     *         metres, under a solver that reads centimetres by default, which made a 3 mm character. */
    ES_PROPERTY(min=0)
    f32 radius{30.0f};

    /** @brief Half the cylinder; total height is `2*(halfHeight + radius)`. */
    ES_PROPERTY(min=0)
    f32 halfHeight{50.0f};

    /** @brief Steepest ground it can stand on. Beyond this it slides. */
    ES_PROPERTY(min=0, max=1.5708, unit="rad")
    f32 maxSlope{0.87f};

    /** @brief Tallest step it climbs instead of stopping at. 0 = climbs nothing. */
    ES_PROPERTY(min=0, advanced)
    f32 stepHeight{40.0f};

    /** @brief How far it reaches down to stay on the floor over a crest. 0 = off. */
    ES_PROPERTY(min=0, advanced)
    f32 snapDown{50.0f};

    /** @brief Mass used when it pushes dynamic bodies. */
    ES_PROPERTY(min=0, advanced)
    f32 mass{70.0f};

    /** @brief How hard it can shove what it walks into, in newtons. A character is
     *         swept rather than solved, so nothing moves out of its way unless it
     *         is given the strength to move it — and the force a solver needs to
     *         get a crate going is well above the one that would hold it there.
     *         0 pushes nothing at all. */
    ES_PROPERTY(min=0, advanced)
    f32 pushForce{5000.0f};

    ES_PROPERTY()
    bool enabled{true};

    /** @brief Which collision layer it is in (0..15). */
    ES_PROPERTY(min=0, max=15, advanced)
    u32 layer{0};

    /** @brief Output: standing on ground it can walk on. */
    ES_PROPERTY(advanced)
    bool isOnFloor{false};

    /** @brief Output: the floor's normal; zero while airborne. */
    ES_PROPERTY(advanced)
    glm::vec3 floorNormal{0.0f, 0.0f, 0.0f};

    /** @brief Output: what it actually moved, per second, after collisions. */
    ES_PROPERTY(advanced)
    glm::vec3 realVelocity{0.0f, 0.0f, 0.0f};
};

}  // namespace esengine::ecs