Added functions to get flyby sequence parameters at a specified time point

CHANGELOG.md

@@ -29,10 +29,11 @@ TombEngine releases are located in this repository (alongside with Tomb Editor):
   - You must use this version: https://github.com/TombEngine/Resources/raw/refs/heads/main/Wad2%20Objects/Interactables/TEN_Waterfall_Emitter.wad2
 
 ### Lua API changes
-* Added Lerp() function to the Rotation object to allow linear interpolation between rotations.
 * Added diary module.
+* Added View.GetFlyByPosition() and View.GetFlyByRotation() functions to get flyby sequence parameters at a specified time point.
 * Added Effects.EmitAirBubble() function to spawn air bubbles.
 * Added additional arguments for Sprite object slot and starting rotation value for EmitParticle function.
+* Added Lerp() function to the Rotation object to allow linear interpolation between rotations.
 * Added various Translate() methods to Vec2 and Vec3 script objects.
   
 ## [Version 1.7.1](https://github.com/TombEngine/TombEditorReleases/releases/tag/v1.7.4) - 2025-04-01

TombEngine/Game/spotcam.cpp

@@ -837,3 +837,59 @@ int Spline(int x, int* knots, int nk)
 
 	return ((__int64)x * (((__int64)x * (((__int64)x * c1 >> 16) + c2) >> 16) + (k[2] >> 1) + ((-k[0] - 1) >> 1)) >> 16) + k[1];
 }
+
+Pose GetCameraTransform(int sequence, float progress)
+{
+	progress = std::clamp(progress, 0.0f, 1.0f);
+
+	// Retrieve total number of cameras in the sequence.
+	int totalCameras = CameraCnt[SpotCamRemap[sequence]];
+	if (totalCameras < 2)
+		return Pose::Zero; // Not enough cameras to interpolate.
+
+	// Find the starting index for the sequence.
+	int firstIndex = 0;
+	for (int i = 0; i < SpotCamRemap[sequence]; i++)
+		firstIndex += CameraCnt[i];
+
+	// Determine number of spline points and spline position.
+	int splinePoints = totalCameras + 2;
+	int splinePosition = (int)(progress * (float)USHRT_MAX);
+
+	std::vector<int> posX, posY, posZ, tarX, tarY, tarZ, roll;
+
+	// Extract camera properties into separate vectors for interpolation.
+	for (int i = -1; i < totalCameras + 1; i++)
+	{
+		int idx = std::clamp(firstIndex + i, firstIndex, firstIndex + totalCameras - 1);
+
+		posX.push_back(SpotCam[idx].x);
+		posY.push_back(SpotCam[idx].y);
+		posZ.push_back(SpotCam[idx].z);
+		tarX.push_back(SpotCam[idx].tx);
+		tarY.push_back(SpotCam[idx].ty);
+		tarZ.push_back(SpotCam[idx].tz);
+		roll.push_back(SpotCam[idx].roll);
+	}
+
+	// Compute spline interpolation of main flyby camera parameters.
+
+	auto position = Vector3(Spline(splinePosition, posX.data(), splinePoints),
+							Spline(splinePosition, posY.data(), splinePoints),
+							Spline(splinePosition, posZ.data(), splinePoints));
+
+	auto target = Vector3(Spline(splinePosition, tarX.data(), splinePoints),
+						  Spline(splinePosition, tarY.data(), splinePoints),
+						  Spline(splinePosition, tarZ.data(), splinePoints));
+
+	short orientZ = Spline(splinePosition, roll.data(), splinePoints);
+
+	Pose result;
+
+	result.Position = position;
+	result.Orientation = EulerAngles(target - position);
+	result.Orientation.z = orientZ;
+
+	return result;
+}
+

TombEngine/Game/spotcam.h

@@ -6,6 +6,8 @@ constexpr auto MAX_SPOTCAMS = 256;
 constexpr auto SPOTCAM_CINEMATIC_BARS_HEIGHT = 1.0f / 16;
 constexpr auto SPOTCAM_CINEMATIC_BARS_SPEED = 1.0f / FPS;
 
+class Pose;
+
 struct SPOTCAM
 {
 	int x;
@@ -61,3 +63,4 @@ void InitializeSpotCamSequences(bool startFirstSequence);
 void InitializeSpotCam(short sequence);
 void CalculateSpotCameras();
 int Spline(int x, int* knots, int nk);
+Pose GetCameraTransform(int sequence, float progress);

TombEngine/Scripting/Internal/ReservedScriptNames.h

@@ -348,6 +348,8 @@ static constexpr char ScriptReserved_KeyClearAll[]					= "KeyClearAll";
 static constexpr char ScriptReserved_FlipMap[]						= "FlipMap";
 static constexpr char ScriptReserved_GetFlipMapStatus[]				= "GetFlipMapStatus";
 static constexpr char ScriptReserved_PlayFlyBy[]					= "PlayFlyBy";
+static constexpr char ScriptReserved_GetFlyByPosition[]				= "GetFlyByPosition";
+static constexpr char ScriptReserved_GetFlyByRotation[]				= "GetFlyByRotation";
 
 static constexpr char ScriptReserved_PlayCamera[]					= "PlayCamera";
 static constexpr char ScriptReserved_ResetObjCamera[]				= "ResetObjCamera";

TombEngine/Scripting/Internal/TEN/View/ViewHandler.cpp

@@ -11,6 +11,7 @@
 #include "Scripting/Internal/ScriptUtil.h"
 #include "Scripting/Internal/TEN/Objects/Room/RoomObject.h"
 #include "Scripting/Internal/TEN/Types/Color/Color.h"
+#include "Scripting/Internal/TEN/Types/Rotation/Rotation.h"
 #include "Scripting/Internal/TEN/Types/Vec3/Vec3.h"
 #include "Scripting/Internal/TEN/View/AlignModes.h"
 #include "Scripting/Internal/TEN/View/CameraTypes.h"
@@ -110,6 +111,24 @@ namespace TEN::Scripting::View
 		InitializeSpotCam(flyby);
 	}
 
+	static Vec3 GetFlyByPosition(short flyby, float progress)
+	{
+		auto& result = GetCameraTransform(flyby, progress / 100.0f);
+		return Vec3(result.Position);
+	}
+
+	static Rotation GetFlyByRotation(short flyby, float progress)
+	{
+		auto& result = GetCameraTransform(flyby, progress / 100.0f);
+
+		return
+		{
+			TO_DEGREES(result.Orientation.x),
+			TO_DEGREES(result.Orientation.y),
+			TO_DEGREES(result.Orientation.z)
+		};
+	}
+
 	static void FlashScreen(TypeOrNil<ScriptColor> col, TypeOrNil<float> speed)
 	{
 		auto color = ValueOr<ScriptColor>(col, ScriptColor(255, 255, 255));
@@ -220,11 +239,25 @@ namespace TEN::Scripting::View
 		//@tparam Color tint value to use.
 		tableView.set_function(ScriptReserved_SetPostProcessTint, &SetPostProcessTint);
 
-		///Enable FlyBy with specific ID
+		///Play flyby sequence with specific ID
 		//@function PlayFlyBy
 		//@tparam short flyby (ID of flyby)
 		tableView.set_function(ScriptReserved_PlayFlyBy, &PlayFlyBy);
 
+		///Get flyby sequence's position at a specified point in time
+		//@function GetFlyByPosition
+		//@tparam short flyby (ID of flyby)
+		//@tparam float time point in time of a flyby in percent. Clamped to [0, 100].
+		//@treturn Vec3 flyby position at a specified point in time
+		tableView.set_function(ScriptReserved_GetFlyByPosition, &GetFlyByPosition);
+
+		///Get flyby sequence's rotation at a specified point in time
+		//@function GetFlyByRotation
+		//@tparam short flyby (ID of flyby)
+		//@tparam float time point in time of a flyby in percent. Clamped to [0, 100].
+		//@treturn Rotation flyby rotation at a specified point in time
+		tableView.set_function(ScriptReserved_GetFlyByRotation, &GetFlyByRotation);
+
 		/// Reset object camera back to Lara and deactivate object camera.
 		//@function ResetObjCamera
 		tableView.set_function(ScriptReserved_ResetObjCamera, &ResetObjCamera);