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 SpringBoneSystem.hpp
* @brief Per-App secondary motion: runs every SpringBone chain after the animation has posed the
* skeleton and before the frame is drawn.
* @details The runtime state (each chain's simulated points) lives HERE, keyed by the chain's root
* entity, not on the component — the split TrailSystem and ParticleSystem make, so the
* component stays configuration and serialization never sees the transient state.
*
* Per chain, per frame: read the pose the animation gave the bones (world transforms
* composed from their local ones), step the simulation toward it, then write back, for each
* bone, the local rotation that aims it at where its child has got to. Positions of bones are
* never written, so a bone cannot leave its parent; only rotations change, which is what
* skinning needs.
*/
#pragma once
#include "../core/Types.hpp"
#include "../math/Math.hpp"
#include "../ecs/Registry.hpp"
#include "../ecs/TransformSystem.hpp"
#include "SpringBoneSolver.hpp"
#include <unordered_map>
#include <vector>
namespace esengine::springbone {
class SpringBoneSystem {
public:
SpringBoneSystem() = default;
/** @brief Advance every enabled chain by `dt` seconds. Composes world transforms first if the animation moved any. */
void update(ecs::Registry& registry, ecs::TransformSystem* transforms, f32 dt);
/**
* @brief Give a chain's bones back as the animation had them and forget its state: what stops a preview in the editor, where nothing animates the bones
* and a chain left as the simulation last turned it would stay that way.
*/
void release(ecs::Registry& registry, Entity root);
/** @brief Forget a chain's state: it starts again from the animated pose on its next frame (a teleport, a respawn). */
void reset(Entity root);
/** @brief How many chains the last update simulated. */
u32 simulated() const { return simulated_; }
/** @brief The simulated world positions of a chain, root first, in the order its bones were found (tips last); null if it has no state. */
const std::vector<Particle>* chain(Entity root) const;
/**
* @brief A chain's particles as flat floats for the editor to draw: seven a particle, the simulated position, the position the animation gives, then
* the index of its parent (-1 for the root). Empty when the chain has no state.
*/
void snapshot(Entity root, std::vector<f32>& out) const;
private:
/** @brief One bone (or a virtual tip) of a chain, beside its particle. */
struct Node {
Entity entity = INVALID_ENTITY; ///< INVALID_ENTITY for a virtual tip.
i32 firstChild = -1; ///< The child this bone aims at; -1 for a tip.
};
/** @brief What a bone's pose was this frame, as the animation left it. */
struct Pose {
glm::vec3 animPos{0.0f}; ///< World position, rotation and scale the animation gives the bone.
glm::quat animRot{1.0f, 0.0f, 0.0f, 0.0f};
glm::vec3 animScale{1.0f};
glm::vec3 localPosition{0.0f};
glm::quat localRotation{1.0f, 0.0f, 0.0f, 0.0f};
};
struct State {
std::vector<Entity> entities; ///< The bones in the order they were found, to notice a hierarchy that changed.
std::vector<Particle> particles;
std::vector<Node> nodes;
glm::vec3 rootPosition{0.0f};
bool primed = false;
f32 clock = 0.0f; ///< Seconds this chain has been simulated, which the wind's gusts are a function of.
/// The animation's local rotation of each bone, the one this system last wrote there, and whether it has written one. A bone
/// still holding what was written was not animated this frame, so the animation's own value is the one kept from before.
std::vector<glm::quat> animated;
std::vector<glm::quat> written;
std::vector<bool> hasWritten;
};
std::unordered_map<Entity, State> states_;
// Scratch for one chain's frame, kept so a frame allocates nothing once the chains exist.
std::vector<Collider> colliders_;
std::vector<Entity> found_;
std::vector<Entity> stack_;
std::vector<Pose> poses_;
std::vector<glm::vec3> tipOffsets_;
std::vector<glm::vec3> fkPosition_;
std::vector<glm::quat> fkRotation_;
std::vector<i32> childCount_;
std::vector<i32> parentOf_;
u32 simulated_ = 0;
// RAII: unregisters from the registry's onDestroy when this system is torn down.
Connection destroyConn_;
void restoreBones(ecs::Registry& registry, State& state);
void collectBones(ecs::Registry& registry, Entity root, std::vector<Entity>& out);
bool gatherColliders(ecs::Registry& registry, const std::vector<Entity>& entities, std::vector<Collider>& out);
};
} // namespace esengine::springbone