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.8 KB
Raw Blame
#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
#include <doctest.h>

#include "esengine/ecs/TransformSystem.hpp"
#include "esengine/ecs/components/SpringBone.hpp"
#include "esengine/springbone/SpringBoneSolver.hpp"
#include "esengine/springbone/SpringBoneSystem.hpp"

#include <cmath>

using namespace esengine;
using namespace esengine::springbone;

namespace {

/** A chain hanging along -y from the origin: n particles `len` apart, the first the root. */
std::vector<Particle> hanging(int n, f32 len) {
    std::vector<Particle> chain(static_cast<size_t>(n));
    for (int i = 0; i < n; ++i) {
        chain[static_cast<size_t>(i)].parent = i - 1;
        chain[static_cast<size_t>(i)].target = glm::vec3(0.0f, -len * static_cast<f32>(i), 0.0f);
        chain[static_cast<size_t>(i)].restLength = i == 0 ? 0.0f : len;
    }
    reset(chain);
    return chain;
}

void follow(std::vector<Particle>& chain, const glm::vec3& root, f32 len) {
    for (size_t i = 0; i < chain.size(); ++i) chain[i].target = root + glm::vec3(0.0f, -len * static_cast<f32>(i), 0.0f);
}

f32 stretch(const std::vector<Particle>& chain) {
    f32 worst = 0.0f;
    for (size_t i = 1; i < chain.size(); ++i) {
        worst = std::max(worst, std::abs(glm::length(chain[i].position - chain[static_cast<size_t>(chain[i].parent)].position) - chain[i].restLength));
    }
    return worst;
}

}  // namespace

TEST_CASE("shortestArc turns one direction onto another") {
    const glm::vec3 pairs[][2] = {{{1, 0, 0}, {0, 1, 0}}, {{0, -1, 0}, {1, 1, 0}}, {{0, 0, 1}, {0, 0, -1}}, {{3, 0, 0}, {3, 0, 0}}};
    for (const auto& p : pairs) {
        const glm::quat q = shortestArc(p[0], p[1]);
        const glm::vec3 turned = q * glm::normalize(p[0]);
        const glm::vec3 want = glm::normalize(p[1]);
        CHECK(turned.x == doctest::Approx(want.x).epsilon(1e-4));
        CHECK(turned.y == doctest::Approx(want.y).epsilon(1e-4));
        CHECK(turned.z == doctest::Approx(want.z).epsilon(1e-4));
        CHECK(glm::length(q) == doctest::Approx(1.0f));
    }
    const glm::quat none = shortestArc(glm::vec3(0.0f), glm::vec3(1, 0, 0));
    CHECK(none.w == doctest::Approx(1.0f));
}

TEST_CASE("a chain at rest in its pose stays there with no gravity") {
    auto chain = hanging(5, 10.0f);
    StepParams params;
    params.gravity = glm::vec3(0.0f);
    for (int i = 0; i < 120; ++i) step(chain, params, {}, 1.0f / 60.0f);
    for (const auto& p : chain) CHECK(glm::length(p.position - p.target) < 1e-4f);
}

TEST_CASE("full stiffness is the animation, exactly") {
    auto chain = hanging(4, 10.0f);
    StepParams params;
    params.stiffness = 1.0f;
    for (int i = 0; i < 30; ++i) {
        follow(chain, glm::vec3(static_cast<f32>(i) * 3.0f, 0.0f, 0.0f), 10.0f);
        step(chain, params, {}, 1.0f / 60.0f);
    }
    for (const auto& p : chain) CHECK(glm::length(p.position - p.target) < 1e-3f);
}

TEST_CASE("a bone never stretches, whatever the chain is doing") {
    auto chain = hanging(6, 10.0f);
    StepParams params;
    params.stiffness = 0.05f;
    for (int i = 0; i < 240; ++i) {
        follow(chain, glm::vec3(std::sin(static_cast<f32>(i) * 0.2f) * 80.0f, 0.0f, 0.0f), 10.0f);
        step(chain, params, {}, 1.0f / 60.0f);
        CHECK(stretch(chain) < 1e-2f);
    }
}

TEST_CASE("the tip lags a moving root and catches up when it stops") {
    auto chain = hanging(5, 10.0f);
    StepParams params;
    params.gravity = glm::vec3(0.0f);
    follow(chain, glm::vec3(100.0f, 0.0f, 0.0f), 10.0f);
    step(chain, params, {}, 1.0f / 60.0f);
    const auto& tip = chain.back();
    CHECK(glm::length(tip.position - tip.target) > 20.0f);   // it did not jump with the root
    for (int i = 0; i < 400; ++i) step(chain, params, {}, 1.0f / 60.0f);
    CHECK(glm::length(tip.position - tip.target) < 0.5f);
}

TEST_CASE("the defaults do not ring: a body that walks a few bone lengths is overshot only a little") {
    auto chain = hanging(5, 10.0f);
    StepParams params;                      // the defaults a SpringBone starts with
    params.gravity = glm::vec3(0.0f);
    f32 over = 0.0f;
    for (int i = 0; i < 400; ++i) {
        follow(chain, glm::vec3(std::min(static_cast<f32>(i), 20.0f) * 2.0f, 0.0f, 0.0f), 10.0f);   // 40 units over a third of a second
        step(chain, params, {}, 1.0f / 60.0f);
        over = std::max(over, chain.back().position.x - chain.back().target.x);
    }
    CHECK(over < 4.0f);                     // a tenth of the move
    CHECK(glm::length(chain.back().position - chain.back().target) < 0.5f);
}

TEST_CASE("gravity hangs a free chain and the weight of stiffness holds it up") {
    // A chain posed out sideways.
    auto sideways = [](f32 stiffness) {
        std::vector<Particle> chain(5);
        for (int i = 0; i < 5; ++i) {
            chain[static_cast<size_t>(i)].parent = i - 1;
            chain[static_cast<size_t>(i)].target = glm::vec3(10.0f * static_cast<f32>(i), 0.0f, 0.0f);
            chain[static_cast<size_t>(i)].restLength = i == 0 ? 0.0f : 10.0f;
        }
        reset(chain);
        StepParams params;
        params.stiffness = stiffness;
        for (int i = 0; i < 600; ++i) step(chain, params, {}, 1.0f / 60.0f);
        return chain.back().position.y;
    };
    const f32 free = sideways(0.0f), held = sideways(0.5f);
    CHECK(free < -30.0f);            // hangs down
    CHECK(held > free + 10.0f);      // the pose holds it higher
    CHECK(held < 0.0f);              // but gravity still has its say
}

TEST_CASE("a collider keeps the chain out") {
    auto chain = hanging(6, 10.0f);
    StepParams params;
    params.gravity = glm::vec3(0.0f);
    // Off to one side, so the chain grazes it: a chain threaded dead through the middle has no side to go round.
    const Collider sphere{glm::vec3(8.0f, -30.0f, 0.0f), glm::vec3(8.0f, -30.0f, 0.0f), 12.0f};
    for (int i = 0; i < 120; ++i) step(chain, params, {sphere}, 1.0f / 60.0f);
    for (size_t i = 1; i < chain.size(); ++i) CHECK(glm::length(chain[i].position - sphere.a) >= 12.0f - 0.05f);
    CHECK(stretch(chain) < 0.5f);
}

TEST_CASE("a capsule pushes out along its length") {
    glm::vec3 p(2.0f, 0.0f, 0.0f);
    const Collider capsule{glm::vec3(0.0f, -10.0f, 0.0f), glm::vec3(0.0f, 10.0f, 0.0f), 5.0f};
    CHECK(pushOut(p, capsule, 0.0f));
    CHECK(p.x == doctest::Approx(5.0f));
    CHECK(p.y == doctest::Approx(0.0f));
    glm::vec3 distant(20.0f, 0.0f, 0.0f);
    CHECK_FALSE(pushOut(distant, capsule, 0.0f));
    glm::vec3 end(0.0f, 12.0f, 0.0f);   // inside the end cap
    CHECK(pushOut(end, capsule, 0.0f));
    CHECK(glm::length(end - capsule.b) == doctest::Approx(5.0f));
}

TEST_CASE("the same steps give the same chain, and the frame rate hardly matters") {
    auto run = [](int hz) {
        auto chain = hanging(5, 10.0f);
        StepParams params;
        params.gravity = glm::vec3(0.0f);
        for (int i = 0; i < hz; ++i) {
            const f32 t = static_cast<f32>(i) / static_cast<f32>(hz);
            follow(chain, glm::vec3(std::min(t, 0.3f) * 200.0f, 0.0f, 0.0f), 10.0f);
            step(chain, params, {}, 1.0f / static_cast<f32>(hz));
        }
        return chain.back().position;
    };
    const glm::vec3 a = run(60), b = run(60), c = run(120);
    CHECK(a == b);
    CHECK(glm::length(a - c) < 4.0f);
}

namespace {

struct Rig {
    ecs::Registry registry;
    ecs::TransformSystem transforms;
    SpringBoneSystem system;
    Entity root{}, b1{}, b2{};

    explicit Rig(f32 endLength = 0.0f, f32 stiffness = 0.2f) {
        root = registry.create();
        b1 = registry.create();
        b2 = registry.create();
        registry.emplace<ecs::Transform>(root);
        auto& t1 = registry.emplace<ecs::Transform>(b1);
        t1.position = {0.0f, -10.0f, 0.0f};
        auto& t2 = registry.emplace<ecs::Transform>(b2);
        t2.position = {0.0f, -10.0f, 0.0f};
        ecs::setParent(registry, b1, root);
        ecs::setParent(registry, b2, b1);
        auto& sb = registry.emplace<ecs::SpringBone>(root);
        sb.gravity = glm::vec3(0.0f);
        sb.endLength = endLength;
        sb.stiffness = stiffness;
        transforms.ensureComposed(registry);
    }

    void moveRoot(const glm::vec3& p) {
        registry.get<ecs::Transform>(root).position = p;
        ecs::invalidateTransformComposition();
    }
    void frame(f32 dt = 1.0f / 60.0f) { system.update(registry, &transforms, dt); }
    f32 turned(Entity e) { return 2.0f * std::acos(std::min(std::abs(registry.get<ecs::Transform>(e).rotation.w), 1.0f)); }
};

}  // namespace

TEST_CASE("a chain in its pose is left alone") {
    Rig rig;
    for (int i = 0; i < 30; ++i) rig.frame();
    CHECK(rig.turned(rig.b1) < 1e-3f);
    CHECK(rig.system.simulated() == 1);
    // Positions are never written.
    CHECK(rig.registry.get<ecs::Transform>(rig.b1).position.y == doctest::Approx(-10.0f));
}

TEST_CASE("moving the root swings the bones, and they settle back to the animated pose without drifting") {
    Rig rig;
    rig.frame();
    rig.moveRoot({60.0f, 0.0f, 0.0f});
    rig.frame();
    CHECK(rig.turned(rig.b1) > 0.05f);
    for (int i = 0; i < 600; ++i) rig.frame();
    // Nothing animated these bones in between, yet they returned to the pose, not to the last thing this system wrote.
    CHECK(rig.turned(rig.b1) < 0.01f);
    CHECK(rig.turned(rig.b2) < 0.01f);
}

TEST_CASE("an animated rotation is the new pose the chain springs toward") {
    Rig rig;
    rig.frame();
    const glm::quat pose = glm::angleAxis(0.5f, glm::vec3(0.0f, 0.0f, 1.0f));
    for (int i = 0; i < 300; ++i) {
        rig.registry.get<ecs::Transform>(rig.b1).rotation = pose;   // the animation, every frame
        ecs::invalidateTransformComposition();
        rig.frame();
    }
    const glm::quat now = rig.registry.get<ecs::Transform>(rig.b1).rotation;
    CHECK(std::abs(glm::dot(now, pose)) > 0.999f);
}

TEST_CASE("an end length gives the last bone a tip to follow") {
    Rig without(0.0f), with(10.0f);
    for (Rig* r : {&without, &with}) {
        r->frame();
        r->moveRoot({80.0f, 0.0f, 0.0f});
        r->frame();
    }
    CHECK(without.turned(without.b2) < 1e-4f);   // a leaf with no tip is not simulated
    CHECK(with.turned(with.b2) > 0.02f);
}

TEST_CASE("a jump of the root is a teleport, not a whip") {
    Rig rig;
    rig.frame();
    rig.moveRoot({50000.0f, 0.0f, 0.0f});
    rig.frame();
    CHECK(rig.turned(rig.b1) < 1e-3f);
    CHECK(rig.turned(rig.b2) < 1e-3f);
}

TEST_CASE("switching the chain off gives the bones back as the animation had them") {
    Rig rig;
    rig.frame();
    rig.moveRoot({60.0f, 0.0f, 0.0f});
    rig.frame();
    CHECK(rig.turned(rig.b1) > 0.05f);
    rig.registry.get<ecs::SpringBone>(rig.root).enabled = false;
    rig.frame();
    CHECK(rig.turned(rig.b1) < 1e-4f);
    CHECK(rig.system.chain(rig.root) == nullptr);
}

TEST_CASE("releasing a chain gives its bones back at once and forgets it") {
    Rig rig;
    rig.frame();
    rig.moveRoot({60.0f, 0.0f, 0.0f});
    rig.frame();
    CHECK(rig.turned(rig.b1) > 0.05f);
    rig.system.release(rig.registry, rig.root);
    CHECK(rig.turned(rig.b1) < 1e-4f);
    CHECK(rig.system.chain(rig.root) == nullptr);
    // Releasing what is not there is nothing.
    rig.system.release(rig.registry, rig.root);
}

TEST_CASE("weight blends between the animation and the simulation") {
    Rig full, half;
    half.registry.get<ecs::SpringBone>(half.root).weight = 0.5f;
    f32 amounts[2];
    int k = 0;
    for (Rig* r : {&full, &half}) {
        r->frame();
        r->moveRoot({60.0f, 0.0f, 0.0f});
        r->frame();
        amounts[k++] = r->turned(r->b1);
    }
    CHECK(amounts[1] > 0.0f);
    CHECK(amounts[1] < amounts[0] * 0.7f);
}

TEST_CASE("destroying the root drops its chain") {
    Rig rig;
    rig.frame();
    CHECK(rig.system.chain(rig.root) != nullptr);
    rig.registry.destroy(rig.root);
    CHECK(rig.system.chain(rig.root) == nullptr);
}

TEST_CASE("a collider entity keeps the simulated bones out") {
    Rig rig;
    auto& sb = rig.registry.get<ecs::SpringBone>(rig.root);
    const Entity ball = rig.registry.create();
    rig.registry.emplace<ecs::Transform>(ball).position = {15.0f, -10.0f, 0.0f};
    auto& shape = rig.registry.emplace<ecs::SpringBoneCollider>(ball);
    shape.radius = 8.0f;
    sb.colliders.push_back(ball);
    rig.transforms.ensureComposed(rig.registry);
    rig.frame();
    rig.moveRoot({40.0f, 0.0f, 0.0f});
    for (int i = 0; i < 20; ++i) rig.frame();
    const auto* chain = rig.system.chain(rig.root);
    REQUIRE(chain != nullptr);
    for (size_t i = 1; i < chain->size(); ++i) CHECK(glm::length((*chain)[i].position - glm::vec3(15.0f, -10.0f, 0.0f)) >= 7.9f);
}

TEST_CASE("a steady wind holds a chain out downwind of its pose") {
    auto chain = hanging(5, 10.0f);
    StepParams params;
    params.gravity = glm::vec3(0.0f);
    params.stiffness = 0.05f;
    params.wind = glm::vec3(600.0f, 0.0f, 0.0f);
    for (int i = 0; i < 240; ++i) {
        params.time = static_cast<f32>(i) / 60.0f;
        step(chain, params, {}, 1.0f / 60.0f);
    }
    CHECK(chain.back().position.x > 3.0f);
    CHECK(std::abs(chain.back().position.z) < 1e-3f);
    CHECK(stretch(chain) < 1e-2f);
    // The root is what the body drives and the wind never moves it.
    CHECK(chain[0].position.x == doctest::Approx(0.0f));
}

TEST_CASE("without a wind the chain is as it was, gusts or not") {
    auto still = hanging(4, 10.0f);
    auto gusty = hanging(4, 10.0f);
    StepParams a;
    StepParams b;
    b.windGust = 1.0f;
    for (int i = 0; i < 60; ++i) {
        a.time = b.time = static_cast<f32>(i) / 60.0f;
        step(still, a, {}, 1.0f / 60.0f);
        step(gusty, b, {}, 1.0f / 60.0f);
    }
    for (size_t i = 0; i < still.size(); ++i) CHECK(glm::length(still[i].position - gusty[i].position) < 1e-5f);
}

TEST_CASE("gusts swing the wind's strength, within bounds and reproducibly") {
    CHECK(gustFactor(1.7f, 0.5f, 0.0f, 3) == doctest::Approx(1.0f));
    f32 lo = 10.0f, hi = -10.0f;
    for (int i = 0; i < 400; ++i) {
        const f32 f = gustFactor(static_cast<f32>(i) * 0.05f, 0.5f, 1.0f, 0);
        lo = std::min(lo, f);
        hi = std::max(hi, f);
        CHECK(f >= 0.0f);
        CHECK(f <= 2.0f);
    }
    CHECK(lo < 0.5f);
    CHECK(hi > 1.5f);
    CHECK(gustFactor(2.5f, 0.5f, 0.6f, 2) == gustFactor(2.5f, 0.5f, 0.6f, 2));
    // A bone further down meets the same gust later: the strand ripples.
    CHECK(gustFactor(2.5f, 0.5f, 1.0f, 0) != doctest::Approx(gustFactor(2.5f, 0.5f, 1.0f, 4)));
}

TEST_CASE("the chain's own clock makes a gusting chain repeatable") {
    auto run = [] {
        auto chain = hanging(5, 10.0f);
        StepParams p;
        p.gravity = glm::vec3(0.0f);
        p.wind = glm::vec3(400.0f, 0.0f, 100.0f);
        p.windGust = 0.8f;
        for (int i = 0; i < 180; ++i) {
            p.time = static_cast<f32>(i) / 60.0f;
            step(chain, p, {}, 1.0f / 60.0f);
        }
        return chain.back().position;
    };
    const glm::vec3 first = run();
    const glm::vec3 second = run();
    CHECK(first.x == second.x);
    CHECK(first.z == second.z);
}