add View.GetAspectRatio() function (#1243)

* add GetScreenAspectRatio() function
* Add Moveable:GetEndFrame() lua function
* Update Util.cpp
* Update ReservedScriptNames.h
* Update Changes.txt
* Update Changes.txt
* Update MoveableObject.cpp
* Update MoveableObject.cpp
* update of the function GetDisplayAspectRatio()
* Update Changes.txt
* Revert newlines
* Update ViewHandler.cpp
* Update Changes.txt
* Correct naming, remove misleading usage example
* Update Changes.txt
* Update Changes.txt

---------

Co-authored-by: Sezz <sezzary@outlook.com>
Co-authored-by: Lwmte <3331699+Lwmte@users.noreply.github.com>

Documentation/Changes.txt

@@ -47,20 +47,23 @@ Lua API changes:
 * Add DisplaySprite object.
 * Add Flow:EnableLoadSave() function to disable savegames.
 * Add Flow:EnablePointFilter() function to disable bilinear filtering.
-* Add Lara:GetAmmoType() function to read the ammo that Lara is using.
+* Add Lara:GetAmmoType() function to read the ammo that player is using.
 * Add Lara:GetControlLock() and Lara:SetControlLock() functions to handle controls locking.
+* Add Moveable:GetEndFrame() function to get the end frame number of a moveable's active animation.
+* Add View.GetAspectRatio() function to get the screen resolution's aspect ratio.
 * Add Logic.HandleEvent() function to call node events.
-* Add Input.GetCursorDisplayPosition() function to get the position of the cursor.
+* Add Input.GetCursorDisplayPosition() function to get the cursor's position.
 * Add functions to load, save, delete and check existence of savegames.
 * Add DisplayStringOption.RIGHT and DisplayStringOption.BLINK flags for DisplayString.
 * Make Vec2 and Vec3 objects float-based instead of integer-based.
 * Split and organize functions in `Misc` namespace to appropriate new namespaces.
 * Add Vec2/Vec3 arithmetic for division with a number and multiplication with another Vec2/Vec3.
-* Add various Vec2/Vec3 operations such as Normalize() or Lerp().
+* Add various Vec2/Vec3 operators and methods, such as Normalize() and Lerp().
 * Add log messages warnings to functions AddCallback and RemoveCallback.
 * Fix InventoryItem constructor, now it will accept compound values in Item Action parameter.
 * Fix Moveable constructor forcing initial animation to 0 and hit points to 10, even if not specified.
 * Fix activation of a flipped room when using SetPos() script command or position change node.
+* Fix Sound:PlaySoundEffect() function when used without optional position argument.
 * Add extra parameter to GiveItem() function to optionally display an inventory item given to the player in the pickup summary.
 * Update DisplayString constructor to take a "scale" parameter, allowing for the resizing of text.
 * The DisplayString constructor's "color" parameter is now optional.

TombEngine/Scripting/Internal/ReservedScriptNames.h

@@ -134,6 +134,7 @@ static constexpr char ScriptReserved_GetSlotHP[]			= "GetSlotHP";
 static constexpr char ScriptReserved_GetVelocity[]			= "GetVelocity";
 static constexpr char ScriptReserved_SetVelocity[]			= "SetVelocity";
 static constexpr char ScriptReserved_GetFrameNumber[]		= "GetFrame";
+static constexpr char ScriptReserved_GetEndFrame[]			= "GetEndFrame";
 static constexpr char ScriptReserved_SetFrameNumber[]		= "SetFrame";
 static constexpr char ScriptReserved_GetAnimNumber[]		= "GetAnim";
 static constexpr char ScriptReserved_SetAnimNumber[]		= "SetAnim";
@@ -260,6 +261,7 @@ static constexpr char ScriptReserved_CalculateDistance[]			= "CalculateDistance"
 static constexpr char ScriptReserved_CalculateHorizontalDistance[]	= "CalculateHorizontalDistance";
 static constexpr char ScriptReserved_PercentToScreen[]				= "PercentToScreen";
 static constexpr char ScriptReserved_ScreenToPercent[]				= "ScreenToPercent";
+static constexpr char ScriptReserved_GetAspectRatio[]				= "GetAspectRatio";
 static constexpr char ScriptReserved_HasLineOfSight[]				= "HasLineOfSight";
 
 static constexpr char ScriptReserved_AddCallback[]					= "AddCallback";

TombEngine/Scripting/Internal/TEN/Objects/Moveable/MoveableObject.cpp

@@ -265,6 +265,8 @@ void Moveable::Register(sol::table& parent)
 // @treturn int the current frame of the active animation
 	ScriptReserved_GetFrameNumber, &Moveable::GetFrameNumber,
 
+	ScriptReserved_GetEndFrame, &Moveable::GetEndFrame,
+
 /// Set the object's velocity to specified value.
 // In most cases, only Z and Y components are used as forward and vertical velocity.
 // In some cases, primarily NPCs, X component is used as side velocity.
@@ -866,6 +868,16 @@ void Moveable::SetFrameNumber(int frameNumber)
 	}
 }
 
+/// Get the end frame number of the moveable's active animation.
+// This is the "End Frame" set in WADTool for the animation.
+// @function Moveable:GetEndFrame()
+// @treturn int End frame number of the active animation.	
+int Moveable::GetEndFrame() const
+{
+	const auto& anim = GetAnimData(*m_item);
+	return (anim.frameEnd - anim.frameBase);
+}
+
 bool Moveable::GetActive() const
 {
 	return m_item->Active;

TombEngine/Scripting/Internal/TEN/Objects/Moveable/MoveableObject.h

@@ -62,6 +62,7 @@ public:
 	void SetAnimNumber(int animNumber);
 
 	[[nodiscard]] int GetFrameNumber() const;
+	[[nodiscard]] int GetEndFrame() const;
 	void SetFrameNumber(int frameNumber);
 
 	[[nodiscard]] Vec3 GetVelocity() const;

TombEngine/Scripting/Internal/TEN/Sound/SoundHandler.cpp

@@ -62,10 +62,9 @@ namespace Sound
 	//@function PlaySound
 	//@tparam int sound ID to play. Corresponds to the value in the sound XML file or Tomb Editor's "Sound Infos" window.
 	////@tparam[opt] Vec3 position The 3D position of the sound, i.e. where the sound "comes from". If not given, the sound will not be positional.
-	static void PlaySoundEffect(int id, sol::optional<Vec3> p)
+	static void PlaySoundEffect(int soundID, sol::optional<Vec3> pos)
 	{
-		auto pose = Pose(Vector3i(p.value().x, p.value().y, p.value().z));
-		SoundEffect(id, p.has_value() ? &pose : nullptr, SoundEnvironment::Always);
+		SoundEffect(soundID, pos.has_value() ? &Pose(pos->ToVector3i()) : nullptr, SoundEnvironment::Always);
 	}
 
 	/// Stop sound effect

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

@@ -5,6 +5,7 @@
 #include "Game/effects/weather.h"
 #include "Game/Lara/lara.h"
 #include "Game/spotcam.h"
+#include "Renderer/Renderer11.h"
 #include "Scripting/Internal/LuaHandler.h"
 #include "Scripting/Internal/ReservedScriptNames.h"
 #include "Scripting/Internal/ScriptUtil.h"
@@ -13,6 +14,7 @@
 #include "Specific/clock.h"
 
 using namespace TEN::Effects::Environment;
+using TEN::Renderer::g_Renderer;
 
 /***
 Functions to manage camera and game view.
@@ -78,6 +80,15 @@ namespace View
 		Weather.Flash(color.GetR(), color.GetG(), color.GetB(), (USE_IF_HAVE(float, speed, 1.0)) / (float)FPS);
 	}
 
+	/// Get the display resolution's aspect ratio.
+	// @function GetAspectRatio
+	// @treturn float Display resolution's aspect ratio.
+	static float GetAspectRatio()
+	{
+		auto screenRes = g_Renderer.GetScreenResolution().ToVector2();
+		return (screenRes.x / screenRes.y);
+	}
+
 	void Register(sol::state* state, sol::table& parent)
 	{
 		sol::table tableView{ state->lua_state(), sol::create };
@@ -140,6 +151,8 @@ namespace View
 		//@tparam float speed (default 1.0). Speed in "amount" per second. Value of 1 will make flash take one second. Clamped to [0.005, 1.0].
 		tableView.set_function(ScriptReserved_FlashScreen, &FlashScreen);
 
+		tableView.set_function(ScriptReserved_GetAspectRatio, &GetAspectRatio);
+
 		LuaHandler handler{ state };
 		handler.MakeReadOnlyTable(tableView, ScriptReserved_CameraType, CAMERA_TYPE);
 	}