DistanceConstraint.hpp

Go to the documentation of this file.

/**************************************************************************
 * EngineSquared v0.1.1
 *
 * EngineSquared is a software package, part of the Engine² organization.
 *
 * This file is part of the EngineSquared project that is under MIT License.
 * Copyright © 2025-present by @EngineSquared, All rights reserved.
 *
 * EngineSquared is a free software: you can redistribute it and/or modify
 * it under the terms of the MIT License. See the project's LICENSE file for
 * the full license text and details.
 *
 * @file DistanceConstraint.hpp
 * @brief Distance constraint component (5 DOF) - rope/spring with min/max distance
 *
 * A distance constraint maintains a specific distance between two bodies,
 * allowing rotation but restricting translation to a range. This is useful
 * for ropes, chains, springs, tethers, and bungee cords.
 *
 * @author @EngineSquared
 * @version 0.1.1
 * @date 2025-12-04
 **************************************************************************/
 
#pragma once
 
#include "ConstraintSettings.hpp"
#include <Engine.hpp>
#include <glm/glm.hpp>
#include <utility>
 
namespace Physics::Component {

struct DistanceConstraint {
    //========================================================================
    // Constraint Bodies
    //========================================================================

    Engine::EntityId bodyA = Engine::EntityId::Null();

    Engine::EntityId bodyB = Engine::EntityId::Null(); // invalid => world (see IsWorldConstraint)
 
    //========================================================================
    // Attachment Points
    //========================================================================

    glm::vec3 localPointA = glm::vec3(0.0f);

    glm::vec3 localPointB = glm::vec3(0.0f);
 
    //========================================================================
    // Distance Properties
    //========================================================================

    float minDistance = -1.0f;

    float maxDistance = -1.0f;
 
    //========================================================================
    // Settings
    //========================================================================

    ConstraintSettings settings = ConstraintSettings::Rigid();
 
    //========================================================================
    // Runtime State
    //========================================================================

    bool broken = false;
 
    //========================================================================
    // Factory Methods
    //========================================================================

    [[nodiscard]] static DistanceConstraint
    Create(Engine::EntityId a, Engine::EntityId b, float distance, const glm::vec3 &pointA = glm::vec3(0.0f),
           const glm::vec3 &pointB = glm::vec3(0.0f),
           const ConstraintSettings &constraintSettings = ConstraintSettings::Rigid())
    {
        DistanceConstraint constraint;
        constraint.bodyA = a;
        constraint.bodyB = b;
        constraint.localPointA = pointA;
        constraint.localPointB = pointB;
        constraint.minDistance = distance;
        constraint.maxDistance = distance;
        constraint.settings = constraintSettings;
        constraint.broken = false;
        return constraint;
    }

    [[nodiscard]] static DistanceConstraint
    CreateWithRange(Engine::EntityId a, Engine::EntityId b, float min, float max,
                    const glm::vec3 &pointA = glm::vec3(0.0f), const glm::vec3 &pointB = glm::vec3(0.0f),
                    const ConstraintSettings &constraintSettings = ConstraintSettings::Soft())
    {
        if (min > max)
            std::swap(min, max);
 
        DistanceConstraint constraint;
        constraint.bodyA = a;
        constraint.bodyB = b;
        constraint.localPointA = pointA;
        constraint.localPointB = pointB;
        constraint.minDistance = min;
        constraint.maxDistance = max;
        constraint.settings = constraintSettings;
        constraint.broken = false;
        return constraint;
    }

    [[nodiscard]] static DistanceConstraint
    CreateToWorld(Engine::EntityId body, const glm::vec3 &worldPoint, float distance,
                  const glm::vec3 &localPoint = glm::vec3(0.0f),
                  const ConstraintSettings &constraintSettings = ConstraintSettings::Rigid())
    {
        DistanceConstraint constraint;
        constraint.bodyA = body;
        constraint.bodyB = Engine::EntityId::Null(); // Invalid entity = world
        constraint.localPointA = localPoint;
        constraint.localPointB = worldPoint; // Used as world position
        constraint.minDistance = distance;
        constraint.maxDistance = distance;
        constraint.settings = constraintSettings;
        constraint.broken = false;
        return constraint;
    }

    [[nodiscard]] static DistanceConstraint
    CreateAutoDistance(Engine::EntityId a, Engine::EntityId b, const glm::vec3 &pointA = glm::vec3(0.0f),
                       const glm::vec3 &pointB = glm::vec3(0.0f),
                       const ConstraintSettings &constraintSettings = ConstraintSettings::Rigid())
    {
        DistanceConstraint constraint;
        constraint.bodyA = a;
        constraint.bodyB = b;
        constraint.localPointA = pointA;
        constraint.localPointB = pointB;
        constraint.minDistance = -1.0f; // Auto-detect
        constraint.maxDistance = -1.0f; // Auto-detect
        constraint.settings = constraintSettings;
        constraint.broken = false;
        return constraint;
    }

    [[nodiscard]] bool IsWorldConstraint() const { return bodyB.IsNull(); }

    [[nodiscard]] bool IsAutoDistance() const { return minDistance < 0.0f || maxDistance < 0.0f; }

    [[nodiscard]] bool IsFixedDistance() const { return minDistance == maxDistance; }
};
 
} // namespace Physics::Component