GH-22: Add support for walking from one mesh to another.

.gitignore

@@ -3,7 +3,7 @@
 
 bin
 build
-res/data
+res/antkeeper-data
 .~lock*
 .cache
 .vs

CMakeLists.txt

@@ -619,9 +619,9 @@ add_subdirectory(${PROJECT_SOURCE_DIR}/res/localization)
 add_subdirectory(${PROJECT_SOURCE_DIR}/docs)
 
 # Build antkeeper-data module (if exists)
-if(EXISTS ${PROJECT_SOURCE_DIR}/res/data/CMakeLists.txt)
+if(EXISTS ${PROJECT_SOURCE_DIR}/res/antkeeper-data/CMakeLists.txt)
 
-	add_subdirectory(${PROJECT_SOURCE_DIR}/res/data)
+	add_subdirectory(${PROJECT_SOURCE_DIR}/res/antkeeper-data)
 
 #	ExternalProject_Add(antkeeper-data
 #		SOURCE_DIR ${PROJECT_SOURCE_DIR}/res/data

src/engine/animation/ik/ik-goal.hpp

@@ -3,7 +3,7 @@
 
 #pragma once
 
-#include <engine/animation/ik-solver.hpp>
+#include <engine/animation/ik/ik-solver.hpp>
 #include <engine/math/vector.hpp>
 #include <memory>
 

src/engine/animation/ik/ik-solver.hpp

@@ -14,6 +14,6 @@ namespace engine::animation
 		virtual ~ik_solver() = default;
 
 		/// Transforms bones to find an inverse kinematic solution for an end effector.
-		virtual void solve() = 0;
+		virtual bool solve() = 0;
 	};
 }

src/engine/animation/ik/solvers/ccd-ik-solver.cpp

@@ -36,7 +36,7 @@ namespace engine::animation
 		}
 	}
 
-	void ccd_ik_solver::solve()
+	bool ccd_ik_solver::solve()
 	{
 		// Get reference to skeletal mesh and its pose from the parent IK rig
 		auto& skeletal_mesh = m_ik_rig->get_skeletal_mesh();
@@ -59,7 +59,7 @@ namespace engine::animation
 				const auto sqr_distance = math::sqr_distance(ps_effector_position, ps_goal_center);
 				if (sqr_distance <= m_sqr_goal_radius)
 				{
-					return;
+					return true; // Solved
 				}
 
 				// Get index of current bone
@@ -88,5 +88,7 @@ namespace engine::animation
 				pose.set_relative_rotation(bone_index, bone_rotation);
 			}
 		}
+
+		return false; // Not solved
 	}
 }

src/engine/animation/ik/solvers/ccd-ik-solver.hpp

@@ -28,7 +28,7 @@ namespace engine::animation
 		/// @{
 
 		/// Solves the IK chain using the Cyclic Coordinate Descent algorithm.
-		void solve() override;
+		bool solve() override;
 
 		/// Sets the maximum number of solving iterations.
 		/// @param iterations Maximum number of solving iterations.

src/engine/animation/animation-context.hpp → src/engine/animation/sequence/context.hpp

@@ -8,7 +8,7 @@
 namespace engine::animation
 {
 	/// Context for animation track output functions.
-	struct animation_context
+	struct context
 	{
 		/// Handle to the entity being animated.
 		entt::handle handle;

src/engine/animation/animation-curve.cpp → src/engine/animation/sequence/curve.cpp

@@ -1,13 +1,13 @@
 // SPDX-FileCopyrightText: 2025 C. J. Howard
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-#include <engine/animation/animation-curve.hpp>
+#include <engine/animation/sequence/curve.hpp>
 #include <engine/math/functions.hpp>
 #include <iterator>
 
 namespace engine::animation
 {
-	float animation_curve::evaluate(float time) const
+	float curve::evaluate(float time) const
 	{
 		// Check if time is outside keyframe range
 		if (m_keyframes.empty() || time < m_keyframes.begin()->time || time > m_keyframes.rbegin()->time)
@@ -32,7 +32,7 @@ namespace engine::animation
 		return m_interpolator(*previous, *next, time);
 	}
 
-	float animation_curve::duration() const
+	float curve::duration() const noexcept
 	{
 		if (m_keyframes.empty())
 		{

src/engine/animation/animation-curve.hpp → src/engine/animation/sequence/curve.hpp

@@ -3,13 +3,13 @@
 
 #pragma once
 
-#include <engine/animation/keyframe.hpp>
+#include <engine/animation/sequence/keyframe.hpp>
 #include <functional>
 
 namespace engine::animation
 {
 	/// Keyframe animation curve.
-	class animation_curve
+	class curve
 	{
 	public:
 		/// Keyframe interpolator function type.
@@ -63,8 +63,8 @@ namespace engine::animation
 			return m_extrapolator;
 		}
 
-		/// Returns the non-negative duration of the curve, in seconds.
-		[[nodiscard]] float duration() const;
+		/// Returns the non-negative duration of the curve.
+		[[nodiscard]] float duration() const noexcept;
 
 	private:
 		keyframe_container m_keyframes;

src/engine/animation/keyframe.cpp → src/engine/animation/sequence/keyframe.cpp

@@ -1,9 +1,9 @@
 // SPDX-FileCopyrightText: 2025 C. J. Howard
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-#include <engine/animation/keyframe.hpp>
+#include <engine/animation/sequence/keyframe.hpp>
 #include <engine/math/functions.hpp>
-#include <stdexcept>
+#include <engine/debug/contract.hpp>
 
 namespace engine::animation
 {
@@ -18,11 +18,13 @@ namespace engine::animation
 		return a.value;
 	}
 
-	float extrapolate_keyframes_clamp(const keyframe_container& keyframes, float time)
+	float extrapolate_keyframes_clamp(const keyframe_container& keyframes, float time) noexcept
 	{
+		debug::precondition(!keyframes.empty());
+
 		if (keyframes.empty())
 		{
-			throw std::runtime_error("Failed clamp extrapolation of keyframes: no keyframes provided.");
+			return 0.0f;
 		}
 
 		if (time < keyframes.begin()->time)

src/engine/animation/keyframe.hpp → src/engine/animation/sequence/keyframe.hpp

@@ -10,14 +10,11 @@ namespace engine::animation
 	/// Keyframe in an animation curve.
 	struct keyframe
 	{
-		/// Time at the keyframe.
-		const float time;
-
-		/// Value at the keyframe.
-		float value;
+		const float time; /// Time at the keyframe.
+		float value;      /// Value at the keyframe.
 	};
 
-	/// Keyframe time comparator.
+	/// Comparator for sorting keyframes by time.
 	struct keyframe_time_comparator
 	{
 		/// Compares the times of two keyframes.
@@ -51,6 +48,6 @@ namespace engine::animation
 	/// @param keyframes Keyframes.
 	/// @param time Extrapolation time.
 	/// @return Extrapolated value.
-	/// @exception std::runtime_error Failed clamp extrapolation of keyframes: no keyframes provided.
-	[[nodiscard]] float extrapolate_keyframes_clamp(const keyframe_container& keyframes, float time);
+	/// @warning @p keyframes must not be empty.
+	[[nodiscard]] float extrapolate_keyframes_clamp(const keyframe_container& keyframes, float time) noexcept;
 }

src/engine/animation/animation-player.cpp → src/engine/animation/sequence/player.cpp

@@ -1,31 +1,31 @@
 // SPDX-FileCopyrightText: 2025 C. J. Howard
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-#include <engine/animation/animation-player.hpp>
+#include <engine/animation/sequence/player.hpp>
 #include <engine/math/functions.hpp>
 #include <engine/utility/sized-types.hpp>
 #include <utility>
 #include <vector>
 
 namespace engine::animation
 {
-	void animation_player::advance(float seconds)
+	void player::advance(float timestep)
 	{
 		// Prevent negative timesteps
-		seconds = math::max(0.0f, seconds);
+		timestep = math::max(0.0f, timestep);
 
 		if (!m_sequence)
 		{
 			// No active animation sequence, advance position and return
-			m_position += seconds;
+			m_position += timestep;
 			return;
 		}
 
 		// Remember previous playback position
 		const auto previous_position = m_position;
 
 		// Advance playback position
-		m_position += seconds;
+		m_position += timestep;
 
 		// Loop
 		usize loop_count = 0;
@@ -52,7 +52,7 @@ namespace engine::animation
 			}
 			else if (m_autostop && m_position > m_sequence_duration)
 			{
-				m_state = animation_player_state::stopped;
+				m_state = player_state::stopped;
 			}
 		}
 
@@ -98,7 +98,7 @@ namespace engine::animation
 		}
 	}
 
-	void animation_player::play(std::shared_ptr<animation_sequence> sequence)
+	void player::play(std::shared_ptr<sequence> sequence)
 	{
 		m_sequence = std::move(sequence);
 
@@ -112,36 +112,36 @@ namespace engine::animation
 			m_sequence_duration = 0.0f;
 		}
 
-		m_state = animation_player_state::playing;
+		m_state = player_state::playing;
 	}
 
-	void animation_player::play()
+	void player::play()
 	{
-		m_state = animation_player_state::playing;
+		m_state = player_state::playing;
 	}
 
-	void animation_player::stop()
+	void player::stop()
 	{
-		m_state = animation_player_state::stopped;
+		m_state = player_state::stopped;
 		m_position = 0.0f;
 	}
 
-	void animation_player::rewind()
+	void player::rewind()
 	{
 		m_position = 0.0f;
 	}
 
-	void animation_player::pause()
+	void player::pause()
 	{
-		m_state = animation_player_state::paused;
+		m_state = player_state::paused;
 	}
 
-	void animation_player::seek(float seconds)
+	void player::seek(float seconds)
 	{
 		m_position = seconds;
 	}
 
-	void animation_player::loop(bool enabled)
+	void player::loop(bool enabled)
 	{
 		m_looping = enabled;
 	}