feat(stancer): auto-reload on wheel change

Author: xesdoog

README.md

@@ -43,6 +43,9 @@ A modular GTA V Lua framework focused on enhancing the player's experience throu
 - Type `!ls` or `!dump` to dump all available commands.
 - All default commands are prefixed with an exclamation mark `<!>`.
 
+>[!Important]
+> **Do not use this in YimMenuV2. It will not work.**
+
 ## Contributing
 
 Contributions are what make the open source community a great place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
@@ -74,14 +77,33 @@ This project was rewritten from scratch using [SmallBase](https://github.com/xes
   </a>
 </div>
 
+## FAQ
+
+- **Q:** Does this support Enhanced?
+- **A:** Prtially. You can use [YimLuaAPI](github.com/TupoyeMenu/YimLuaAPI) to test it but stability is not guaranteed as of now.
+
+- **Q:** What is YimLuaAPI and how do I use it?
+- **A:**
+  - **What is it:** [YimLuaAPI](github.com/TupoyeMenu/YimLuaAPI) is a universal Lua API that works for both Legacy and Enhanced.
+  - **How to use it:** Right now there is no release because it's still in development. If you want to try it, you have to compile it yourself. Once you have `YimLuaAPI.dll`, inject it into any GTA branch (Legacy/Enhanced), it will create a folder on first injection: `%AppData%\YimLuaAPI`. Simply place the script there and you're done. You can still use YimMenu/YimMenuV2 but the script has to only exist in YimLuaAPI.
+
+- **Q:** Why can't-I run this in YimMenuV2?
+- **A:** There are several reasons why:
+  - YimMenuV2 doesn't have a finished Lua API. `require` isn't even present, let alone custom bindings.
+  - There are several versions and flavors of the Lua programming language. This project is written in [Lua 5.4](https://www.lua.org/manual/5.4/) and YimMenuV2's API uses [LuaJIT](https://luajit.org/). Explaining the difference here is not ideal but it's not only the language difference, it's also how they are embedded in each menu.
+
+- **Q:** Can this be made compatible with YimMenuV2 once its API is finished?
+- **Short Answer:** No.
+- **Long Answer:** Yes, a compatibility layer can be added to accomodate for all language and API differences but is it worth the trouble and code bloat? Absolutely not. We would be better off rewriting this for V2's API.
+
 ## Acknowledgments
 
-| | |
+| Name | Contribution |
 | :---: | :---: |
 | <a href="https://github.com/harmless05"><img height="40" width="40" src="https://avatars.githubusercontent.com/harmless05"><br/>Harmless</a> | Shift-Drift |
 | <a href="https://github.com/NiiV3AU"><img height="40" width="40" src="https://avatars.githubusercontent.com/NiiV3AU"><br/>NiiV3AU</a> | German translations |
 | <a href="https://github.com/gir489returns"><img height="40" width="40" src="https://avatars.githubusercontent.com/gir489returns"><br/>gir489returns</a> | [Casino Pacino](https://github.com/YimMenu-Lua/Casino-Pacino) |
 | <a href="https://github.com/tupoy-ya"><img height="40" width="40" src="https://avatars.githubusercontent.com/tupoy-ya"><br/>tupoy-ya</a> | Several contributions and shared knowledge |
 | <a href="https://github.com/szalikdev"><img height="40" width="40" src="https://avatars.githubusercontent.com/szalikdev"><br/>szalikdev</a> | Revived the project and joined the cause   |
-| <a href="https://github.com/shinywasabi"><img height="40" width="40" src="https://avatars.githubusercontent.com/shinywasabi"><br/>shinywasabi</a> | Foundational community tooling frequently used as reference |
+| <a href="https://github.com/shinywasabi"><img height="40" width="40" src="https://avatars.githubusercontent.com/shinywasabi"><br/>ShinyWasabi</a> | Foundational community tooling frequently used as reference |
 | <a href="https://unknowncheats.me"><img height="52" width="120" src="https://www.unknowncheats.me/forum/ambience/misc/forum_banner.png"><br/>UnknownCheats</a> | A treasure trove of information |

includes/classes/CVehicle.lua

@@ -433,6 +433,12 @@ function CVehicle:IsWheelBrokenOff(wheelIndex)
 	return (self.m_ptr:add(0xA98):get_dword() >> (wheelIndex & 0x1F) & 1) ~= 0
 end
 
+---@param refresh? boolean
+---@return CWheelDrawData
+function CVehicle:GetWheelDrawData(refresh)
+	return self.m_draw_data:GetWheelDrawData(refresh)
+end
+
 ---@return float -- Wheel width or 0.f if invalid
 function CVehicle:GetWheelWidth()
 	return self.m_draw_data:GetWheelWidth()

includes/classes/CVehicleDrawData.lua

@@ -35,7 +35,12 @@ function CVehicleDrawData:init(ptr)
 	return self
 end
 
-function CVehicleDrawData:GetWheelDrawData()
+---@param refresh? boolean
+function CVehicleDrawData:GetWheelDrawData(refresh)
+	if (refresh) then
+		self.m_wheel_draw_data = nil
+	end
+
 	if not (self.m_wheel_draw_data and self.m_wheel_draw_data:IsValid()) then
 		self.m_wheel_draw_data = CWheelDrawData.new(self.m_ptr:add(0x370):deref())
 	end

includes/features/vehicle/stancer.lua

@@ -25,6 +25,9 @@ end
 ---@field private m_entity PlayerVehicle
 ---@field private m_last_tick milliseconds
 ---@field private m_cached_model hash
+---@field private m_reloading boolean
+---@field private m_last_wheels_mod {type: integer, index: integer, var: integer}
+---@field private m_last_wheel_mod_check_time seconds
 ---@field public m_base_values table<eWheelSide, StanceObject>
 ---@field public m_deltas table<eWheelSide, StanceObject>
 ---@field public m_wheels table<eWheelSide, array<CWheel>>
@@ -153,6 +156,15 @@ end
 
 function Stancer:Init()
 	self.m_last_tick = 0
+	self.m_last_wheel_mod_check_time = 0
+	self.m_reloading = false
+
+	self.m_last_wheels_mod = {
+		index = -1,
+		type = -1,
+		var = -1
+	}
+
 	self.m_suspension_height = {
 		m_current = 0.0,
 		m_last_seen = 0.0
@@ -161,6 +173,7 @@ function Stancer:Init()
 	if (self.m_entity:IsValid()) then
 		self:ReadWheelArray()
 		self.m_cached_model = self.m_entity:GetModelHash()
+		self.m_last_wheels_mod = self.m_entity:GetCustomWheels()
 	end
 end
 
@@ -174,13 +187,13 @@ function Stancer:CanApplyDrawData()
 end
 
 function Stancer:Reset()
+	self.m_suspension_height.m_current   = 0.0
+	self.m_suspension_height.m_last_seen = 0.0
+
 	if (not self.m_wheels) then
 		return
 	end
 
-	self.m_suspension_height.m_current   = 0.0
-	self.m_suspension_height.m_last_seen = 0.0
-
 	for _, v in ipairs(self.decorators) do
 		self.m_deltas[v.wheel_side][v.key] = 0.0
 		local wheel_array = self:GetAllWheelsForSide(v.wheel_side)
@@ -207,10 +220,6 @@ function Stancer:Reset()
 end
 
 function Stancer:Cleanup()
-	if (not self.m_wheels) then
-		return
-	end
-
 	self:Reset()
 	Decorator:RemoveEntity(self.m_entity:GetHandle())
 	self.m_cached_model = nil
@@ -222,8 +231,10 @@ function Stancer:OnNewVehicle()
 		return
 	end
 
-	self.m_cached_model = self.m_entity:GetModelHash()
+	self.m_cached_model    = self.m_entity:GetModelHash()
+	self.m_last_wheels_mod = self.m_entity:GetCustomWheels()
 	self:ReadDefaults()
+
 	if (self:IsVehicleModelSaved() and GVars.features.vehicle.stancer.auto_apply_saved) then
 		self:LoadSavedDeltas()
 	end
@@ -340,6 +351,39 @@ function Stancer:GetNthWheelForSide(side, wheel_n)
 	return self.m_wheels[side][wheel_n]
 end
 
+function Stancer:OnWheelsChanged()
+	if (not self.m_entity or not self.m_entity:IsValid()) then
+		return
+	end
+
+	if (Time.now() - self.m_last_wheel_mod_check_time < 1) then
+		return
+	end
+
+	local current = self.m_entity:GetCustomWheels()
+	if (not table.is_equal(self.m_last_wheels_mod, current)) then
+		self.m_reloading = true
+		local prev_sup = self.m_suspension_height.m_current
+		local prev_deltas_f = table.copy(self.m_deltas[self.eWheelSide.FRONT])
+		local prev_deltas_r = table.copy(self.m_deltas[self.eWheelSide.BACK])
+		self:Cleanup()
+		self:OnNewVehicle()
+		self.m_last_wheels_mod = self.m_entity:GetCustomWheels()
+
+		for k, v in pairs(prev_deltas_f) do
+			self.m_deltas[self.eWheelSide.FRONT][k] = v
+		end
+		for k, v in pairs(prev_deltas_r) do
+			self.m_deltas[self.eWheelSide.BACK][k] = v
+		end
+
+		self.m_suspension_height.m_current = prev_sup
+		self.m_reloading = false
+	end
+
+	self.m_last_wheel_mod_check_time = Time.now()
+end
+
 ---@return boolean
 function Stancer:AreSavedDeltasLoaded()
 	if (not self.m_entity or not self.m_entity:IsValid()) then
@@ -481,6 +525,7 @@ function Stancer:ReadDefaults()
 		return
 	end
 
+	self.m_entity:GetWheelDrawData(true)
 	local queued_decors_loaded = self:RestoreQueueFromDecors()
 
 	if (self:AreDefaultsRegistered()) then
@@ -523,7 +568,7 @@ function Stancer:Update()
 	-- possible RAGE engine PTSD involved
 	self.m_is_model_saved = self:IsVehicleModelSaved()
 
-	if (not self.m_is_active or not self.m_wheels) then
+	if (not self.m_is_active or not self.m_wheels or self.m_reloading) then
 		return
 	end
 
@@ -533,6 +578,8 @@ function Stancer:Update()
 		return
 	end
 
+	self:OnWheelsChanged()
+
 	-- must have high frequency updates, otherwise wheels will flicker
 	-- when the game tries to force-reset them
 	if (Game.GetGameTimer() - self.m_last_tick < 5) then

includes/lib/utils.lua

@@ -818,28 +818,28 @@ function table.is_equal(a, b, seen)
 		return true
 	end
 
-	if type(a) ~= type(b) then
+	if (type(a) ~= type(b)) then
 		return false
 	end
 
-	if type(a) ~= "table" then
+	if (type(a) ~= "table") then
 		return false
 	end
 
 	seen = seen or {}
-	if seen[a] and seen[b] then
+	if (seen[a] and seen[b]) then
 		return true
 	end
 	seen[a], seen[b] = true, true
 
 	for k, v in pairs(a) do
-		if not table.is_equal(v, b[k], seen) then
+		if (not table.is_equal(v, b[k], seen)) then
 			return false
 		end
 	end
 
 	for k in pairs(b) do
-		if a[k] == nil then
+		if (a[k] == nil) then
 			return false
 		end
 	end

includes/modules/Vehicle.lua

@@ -550,6 +550,12 @@ function Vehicle:IsWheelBrokenOff(wheelIndex)
 	return self:Resolve():IsWheelBrokenOff(wheelIndex)
 end
 
+---@param refresh? boolean
+---@return CWheelDrawData
+function Vehicle:GetWheelDrawData(refresh)
+	return self:Resolve():GetWheelDrawData(refresh)
+end
+
 ---@return float -- Wheel width or 0.f if invalid
 function Vehicle:GetVisualWheelWidth()
 	return self:Resolve():GetWheelWidth()
@@ -829,7 +835,7 @@ function Vehicle:GetColors()
 	return col1, col2
 end
 
----@return table
+---@return { type: integer, index: integer, var: integer }
 function Vehicle:GetCustomWheels()
 	if not self:IsValid() then
 		return {}