feat(Translator): add string formatting

- The `Translate` method and the `_T` wrapper now both support optional string formatting.
- Fix Stancer camber issue.

Author: xesdoog

SSV2/includes/classes/gta/CWheel.lua

@@ -42,16 +42,16 @@ local VEC3_ZERO <const> = vec3:zero()
 ---@field m_suspension_raise pointer<float>
 ---@field m_unk_suspension_raise pointer<float>
 ---@field m_suspension_fwd_offset pointer<float>
----@field m_hydraulic_state pointer<int32_t> some enum related to hydraulic state. can't find any refs online. where's Yimura when you need to skid from him? :(
----@field m_hydraulic_state_2 pointer<int32_t> -- ??
+---@field m_hydraulic_state pointer<uint32_t> some enum related to hydraulic state. can't find any refs online. where's Yimura when you need to skid from him? :(
+---@field m_hydraulic_state_2 pointer<uint32_t> -- ??
 ---@field m_suspension_compression pointer<float>
 ---@field m_suspension_compression_2 pointer<float>
 ---@field m_wheel_compression pointer<float>
----@field m_rotation_angle pointer -- radians?
----@field m_rotation_speed pointer -- velocity
----@field m_unk_0174 pointer -- ??
+---@field m_rotation_angle pointer<float> -- radians?
+---@field m_rotation_speed pointer<float> -- velocity
+---@field m_unk_0174 pointer<float> -- ?? don't know what this is. using float to keep the 4 byte alignment
 ---@field m_tyre_temperature pointer<float> -- don't want to admit how long it took to figure out what this little shit is. are we playing Assetto Corsa now? it seems to only be relevant for F1 vehicles
----@field m_unk_0194 pointer -- ??
+---@field m_unk_0194 pointer<float> -- ??
 ---@field m_tire_drag_coeff pointer<float>
 ---@field m_top_speed_mult pointer<float>
 ---@field m_steering_angle pointer<float>
@@ -61,7 +61,7 @@ local VEC3_ZERO <const> = vec3:zero()
 ---@field m_suspension_health pointer<float> -- 100.0f: car gets slammed (old method of shooting your suspension to stance your car) // 0.0f: wheel should fall off but doesn't. Something else must be set to trigger wheel detachment
 ---@field m_tyre_health pointer<float> -- <= 500.0f: flat tyre // 0.0f: no tyre
 ---@field m_tyre_wear_mult pointer<float> -- 0.0f: tyres won't burst from long burnout
----@field m_tyre_wear_unk pointer<float> -- similar? // looks like a wear rate not current tyre wear
+---@field m_tyre_wear_unk pointer<float> -- similar? // looks like rate rather than a multiplier
 ---@field m_wheel_dynamic_flags pointer<eWheelDynamicFlags>
 ---@field m_wheel_config_flags pointer<eWheelConfigFlags>
 ---@field m_tyre_is_burst pointer<bool>
@@ -75,8 +75,8 @@ local CWheel = CStructView("CWheel", 0x020E)
 function CWheel.new(ptr)
 	return setmetatable({
 		m_ptr                      = ptr,
-		m_rotation                 = fVector3(ptr:add(0x0004)),
-		m_rotation_inv             = fVector3(ptr:add(0x000A)),
+		m_rotation                 = fVector3(ptr:add(0x0000)),
+		m_rotation_inv             = fVector3(ptr:add(0x000C)),
 		m_offset_from_body         = ptr:add(0x0020),
 		m_x_offset                 = ptr:add(0x0030),
 		m_last_ground_pos          = fVector3(ptr:add(0x003C)),

SSV2/includes/data/stancer_data.lua

@@ -7,7 +7,7 @@
 --	* Provide a copy of or a link to the original license (GPL-3.0 or later); see LICENSE.md or <https://www.gnu.org/licenses/>.
 
 
----@alias ptr_read fun(w: CWheel): anyval
+---@alias ptr_read fun(w: CWheel, veh?: PlayerVehicle): float
 
 ---@enum eWheelAxle
 Enums.eWheelAxle = {
@@ -16,23 +16,20 @@ Enums.eWheelAxle = {
 }
 
 return {
-	---@type array<{ key: string, axle: eWheelAxle, read: ptr_read, write: fun(w: CWheel, v: anyval, veh?: PlayerVehicle), side_dont_care?: boolean}>
+	---@type array<{ key: string, axle: eWheelAxle, read: ptr_read, write: fun(w: CWheel, v: float, veh?: PlayerVehicle), side_dont_care?: boolean}>
 	decorators = {
 		{
 			key   = "m_toe",
 			axle  = Enums.eWheelAxle.FRONT,
-			read  = function(w) return w.m_rotation.x end,
-			write = function(w, v)
-				w.m_rotation.x     = v
-				w.m_rotation_inv.x = -v
-			end
+			read  = function(w) return w.m_rotation.y end,
+			write = function(w, v) w.m_rotation.y = v end
 		},
 		{
 			key   = "m_camber",
 			axle  = Enums.eWheelAxle.FRONT,
 			read  = function(w) return w.m_rotation.y end,
 			write = function(w, v)
-				w.m_rotation.y     = v
+				w.m_rotation.z = v
 				w.m_rotation_inv.y = -v
 			end
 		},
@@ -53,9 +50,9 @@ return {
 			key            = "m_wheel_width",
 			axle           = Enums.eWheelAxle.FRONT, -- doesn't matter
 			side_dont_care = true,
-			read           = function(w) return w.m_tyre_width:get_float() end,
-			write          = function(w, v, veh)
-				w.m_tyre_width:set_float(v)
+			read           = function() return 0 end,
+			write          = function(_, v, veh)
+				---@type float?
 				local cached = Decorator:GetDecor(veh:GetHandle(), "m_visual_width")
 				if (cached and cached > 0 and veh:GetVisualWheelWidth() ~= cached + v) then
 					veh:SetVisualWheelWidth(cached + v)
@@ -66,9 +63,9 @@ return {
 			key            = "m_wheel_size",
 			axle           = Enums.eWheelAxle.FRONT, -- doesn't matter
 			side_dont_care = true,
-			read           = function(w) return w.m_tyre_radius:get_float() end,
-			write          = function(w, v, veh)
-				w.m_tyre_radius:set_float(v)
+			read           = function() return 0 end,
+			write          = function(_, v, veh)
+				---@type float?
 				local cached = Decorator:GetDecor(veh:GetHandle(), "m_visual_size")
 				if (cached and cached > 0 and veh:GetVisualWheelSize() ~= cached + v) then
 					veh:SetVisualWheelSize(cached + v)
@@ -78,18 +75,15 @@ return {
 		{
 			key   = "m_toe",
 			axle  = Enums.eWheelAxle.REAR,
-			read  = function(w) return w.m_rotation.x end,
-			write = function(w, v)
-				w.m_rotation.x     = v
-				w.m_rotation_inv.x = -v
-			end
+			read  = function(w) return w.m_rotation.y end,
+			write = function(w, v) w.m_rotation.y = v end
 		},
 		{
 			key   = "m_camber",
 			axle  = Enums.eWheelAxle.REAR,
-			read  = function(w) return w.m_rotation.y end,
+			read  = function(w) return w.m_rotation.z end,
 			write = function(w, v)
-				w.m_rotation.y     = v
+				w.m_rotation.z     = v
 				w.m_rotation_inv.y = -v
 			end
 		},

SSV2/includes/features/extra/billionaire_services/BillionaireServicesV2.lua

@@ -647,10 +647,7 @@ function BillionaireServices:CallPrivateJet(model, airportData)
 		self:RegisterEntity(jet:GetHandle())
 		self:RegisterEntity(jet.pilot)
 		self:RegisterEntity(jet.copilot)
-
-		Notifier:ShowMessage("Billionaire Services",
-			_F(_T("BSV2_JET_SPAWN_SUCCESS"), jet.name, airportData.name)
-		)
+		Notifier:ShowMessage("Billionaire Services", _T("BSV2_JET_SPAWN_SUCCESS", jet.name, airportData.name))
 	end)
 end
 

SSV2/includes/features/extra/entity_forge/EntityForge.lua

@@ -1355,7 +1355,7 @@ function EntityForge:AddModelToFavorites(model, name, _type)
 
 	self.FavoriteModels[model] = { name = name, entityType = _type }
 	self:ParseFavorites()
-	Notifier:ShowSuccess("EntityForge", _F(_T("EF_FAV_SAVE_SUCCESS"), name))
+	Notifier:ShowSuccess("EntityForge", _T("EF_FAV_SAVE_SUCCESS", name))
 end
 
 ---@param modelHash hash

SSV2/includes/features/online/CasinoPacino.lua

@@ -380,7 +380,7 @@ function CasinoPacino:GetCooldownString()
 	local max_chip_wins = tunables.get_int("VC_CASINO_CHIP_MAX_WIN_DAILY")
 
 	return (chipswon_gd >= max_chip_wins)
-		and _F(_T("CP_COOLDOWN_BYPASS_STATUS_FORMAT"), minutes_left)
+		and _T("CP_COOLDOWN_BYPASS_STATUS_FORMAT", minutes_left)
 		or _T("CP_COOLDOWN_BYPASS_STATUS_OFF")
 end
 

SSV2/includes/features/vehicle/stancer.lua

@@ -521,7 +521,7 @@ function Stancer:RestoreDeltasFromQueue()
 
 	for _, v in ipairs(StancerData.decorators) do
 		local queued_key = _F("%s_%d_queue", v.key, v.axle)
-		local val = Decorator:GetDecor(handle, queued_key)
+		local val        = Decorator:GetDecor(handle, queued_key)
 		if (type(val) == "number") then
 			self.m_deltas[v.axle][v.key] = val
 		end
@@ -549,7 +549,7 @@ function Stancer:ReadDefaultValues()
 		self:ForEach(wheel_array, function(i, cwheel)
 			local decor       = _F("%s_%d_%d", v.key, v.axle, i)
 			local existsOn    = Decorator:ExistsOn(handle, decor)
-			local default_val = existsOn and Decorator:GetDecor(handle, decor) or v.read(cwheel)
+			local default_val = existsOn and Decorator:GetDecor(handle, decor) or v.read(cwheel, self.m_entity)
 			if (not existsOn) then
 				Decorator:Register(handle, decor, default_val)
 			end
@@ -652,7 +652,7 @@ function Stancer:Update()
 		local base = self.m_base_values[v.axle][v.key]
 		local sum  = base + delta
 		self:ForEach(wheel_array, function(_, cwheel)
-			local current = v.read(cwheel)
+			local current = v.read(cwheel, self.m_entity)
 			local desired = v.side_dont_care and sum or self:GetValueBySideLR(cwheel, sum)
 			if (math.abs(desired) ~= math.abs(current)) then
 				v.write(cwheel, desired, self.m_entity)

SSV2/includes/frontend/billionaire_services/escort_groups_ui.lua

@@ -370,7 +370,7 @@ local function drawGroupCreatorStep1()
 	local groups  = BSV2:GetEscortGroupList()
 	local exists  = groups[newGroup.nameBuffer] ~= nil
 	local isValid = string.isvalid(newGroup.buffer.name) and not exists
-	local text    = isValid and _F(_T("BSV2_ES_NEW_GROUP_NEXT"), "[ > ]") or _T("BSV2_ES_NEW_GROUP_NAME")
+	local text    = isValid and _T("BSV2_ES_NEW_GROUP_NEXT", "[ > ]") or _T("BSV2_ES_NEW_GROUP_NAME")
 	ImGui.Text(text)
 
 	ImGui.Spacing()
@@ -389,7 +389,7 @@ end
 local function drawGroupCreatorStep2()
 	ImGui.Dummy(0, 15)
 	local isValid = newGroup.buffer.vehicleModel ~= nil
-	local text    = isValid and _F(_T("BSV2_ES_NEW_GROUP_NEXT"), "[ > ]") or _T("BSV2_ES_NEW_GROUP_VEH")
+	local text    = isValid and _T("BSV2_ES_NEW_GROUP_NEXT", "[ > ]") or _T("BSV2_ES_NEW_GROUP_VEH")
 	ImGui.Text(text)
 
 	ImGui.Spacing()
@@ -420,7 +420,7 @@ local function drawGroupCreatorStep3()
 	local infoText = membersFull and "BSV2_ES_NEW_GROUP_MEMBERS_DONE" or "BSV2_ES_NEW_GROUP_MEMBERS"
 	ImGui.Text(_T(infoText))
 	ImGui.Spacing()
-	ImGui.BulletText(_F(_T("BSV2_ES_NEW_GROUP_MEMBERS_COUNT"), count))
+	ImGui.BulletText(_T("BSV2_ES_NEW_GROUP_MEMBERS_COUNT", count))
 
 	local removeDisabled = not math.is_inrange(count, 1, 3)
 	ImGui.SameLine()
@@ -495,7 +495,7 @@ local function drawGroupCreator()
 		stage / 3.0,
 		vec2:new(ImGui.GetContentRegionAvail() - btnSize.x - style.ItemSpacing.x, btnSize.y),
 		ImGuiValueBarFlags.NONE,
-		{ fmt = _F(_T("BSV2_ES_NEW_GROUP_STEP_LABEL"), stage) }
+		{ fmt = _T("BSV2_ES_NEW_GROUP_STEP_LABEL", stage) }
 	)
 
 	ImGui.SameLine()
@@ -520,7 +520,7 @@ local function drawGroupCreator()
 			GUI:Tooltip(_T("GENERIC_CONFIRM"))
 		end
 
-		if (ImGui.DialogBox("##confirmNewGroup", _F(_T("BSV2_ES_NEW_GROUP_PROMPT"), newGroup.buffer.name), ImGuiDialogBoxStyle.INFO)) then
+		if (ImGui.DialogBox("##confirmNewGroup", _T("BSV2_ES_NEW_GROUP_PROMPT", newGroup.buffer.name), ImGuiDialogBoxStyle.INFO)) then
 			BSV2:AddNewEscortGroup(table.copy(newGroup.buffer))
 			clearNewGroupBuffer()
 		end

SSV2/includes/frontend/billionaire_services/jet_ui.lua

@@ -142,12 +142,12 @@ local function drawSpawnedJet(jet)
 		if (GUI:Button(_T("GENERIC_GO"))) then
 			ThreadManager:Run(function(s)
 				if (jet.departureAirport and (jet.departureAirport.name == selectedAirport.name)) then
-					Notifier:ShowError("Private Jet", _F(_T("BSV2_JET_LANDING_SAME_AP_ERR"), selectedAirport.name))
+					Notifier:ShowError("Private Jet", _T("BSV2_JET_LANDING_SAME_AP_ERR", selectedAirport.name))
 					return
 				end
 
 				jet.arrivalAirport = selectedAirport
-				Notifier:ShowMessage("Private Jet", _F(_T("BSV2_JET_FLY_CONFIRM"), selectedAirport.name))
+				Notifier:ShowMessage("Private Jet", _T("BSV2_JET_FLY_CONFIRM", selectedAirport.name))
 				jet:FlyTo(selectedAirport.landingApproach.pos, s)
 			end)
 		end

SSV2/includes/frontend/entity_forge/forge_creator_ui.lua

@@ -389,7 +389,7 @@ local function DrawChildStuff()
 
 				EntityForge.SavedForges[new_creation.name] = new_creation
 				EntityForge:ParseForges()
-				Notifier:ShowSuccess("EntityForge", _F(_T("EF_NEW_FORGE_SUCCESS"), newEntityNameBuffer))
+				Notifier:ShowSuccess("EntityForge", _T("EF_NEW_FORGE_SUCCESS", newEntityNameBuffer))
 
 				s:sleep(300)
 				newEntityNameBuffer = ""
@@ -467,7 +467,7 @@ local function DrawLowerSection()
 end
 
 local function ControlMouseCursor()
-	ImGui.Text(_F(_T("EF_MOUSE_CURSOR_HINT"), "I", gui.mouse_override() and _T("GENERIC_DISABLE") or _T("GENERIC_ENABLE")))
+	ImGui.Text(_T("EF_MOUSE_CURSOR_HINT", "I", gui.mouse_override() and _T("GENERIC_DISABLE") or _T("GENERIC_ENABLE")))
 	if (KeyManager:IsKeyJustPressed(eVirtualKeyCodes.I)) then
 		gui.override_mouse(not gui.mouse_override())
 	end

SSV2/includes/frontend/mastermind_ui.lua

@@ -120,7 +120,7 @@ local function drawBasicTab()
 		if (heist.opt_info and not is_done) then
 			GUI:Tooltip(heist.opt_info)
 		elseif (on_cooldown) then
-			GUI:Tooltip(_F(_T("CP_COOLDOWN_BYPASS_STATUS_FORMAT"), seconds_left / 60))
+			GUI:Tooltip(_T("CP_COOLDOWN_BYPASS_STATUS_FORMAT", seconds_left / 60))
 		end
 		ImGui.EndDisabled()
 
@@ -193,7 +193,7 @@ local function drawCayoTab()
 
 	if (on_cooldown) then
 		local minutes_left = (cooldown_seconds_left > 0 and cooldown_seconds_left or cooldown_hard_seconds_left) / 60
-		GUI:HeaderText(_F(_T("CP_COOLDOWN_BYPASS_STATUS_FORMAT"), minutes_left),
+		GUI:HeaderText(_T("CP_COOLDOWN_BYPASS_STATUS_FORMAT", minutes_left),
 			{ separator = false, spacing = true, color = Color.RED })
 	end
 
@@ -340,7 +340,7 @@ local function drawDDayTab()
 
 	if (on_cooldown) then
 		local minutes_left = cooldown_seconds_left / 60
-		GUI:HeaderText(_F(_T("CP_COOLDOWN_BYPASS_STATUS_FORMAT"), minutes_left),
+		GUI:HeaderText(_T("CP_COOLDOWN_BYPASS_STATUS_FORMAT", minutes_left),
 			{ separator = false, spacing = true, color = Color.RED })
 	end
 
@@ -351,7 +351,7 @@ local function drawDDayTab()
 	if (GUI:Button(button_label)) then
 		stats.set_int("MPX_GANGOPS_HEIST_STATUS", 9999)
 	end
-	GUI:HelpMarker(_F(_T("YH_DDAY_HELP2_FMT"), button_label))
+	GUI:HelpMarker(_T("YH_DDAY_HELP2_FMT", button_label))
 
 	GUI:HeaderText(_T("CP_HEIST_SETUP"), { separator = true, spacing = true })