docs: UEHelpers: Added annoations to CacheDefaultObject function and …

…annotated ForceInvalidateCache parameter as optional

feat: UEHelpers: Added functions GetGameModeBase() and GetGameStateBase()
docs: Added changes from GH-650 to the Changelog

assets/Changelog.md

@@ -21,6 +21,17 @@ Added search filter: `IncludeClassNames`. ([UE4SS #472](https://github.com/UE4SS
 ### UHT Dumper
 
 ### Lua API
+#### UEHelpers [PR #650](https://github.com/UE4SS-RE/RE-UE4SS/pull/650)
+- Added local class `RemoteObject` with method `IsValid`. A new instance of the class should be used as return value in all UEHelpers functions instead of nil
+- Added function `GetPlayer` which is just a fast way to get player controlled Pawn (the majority of the time it will be the player character)
+- Added functions: `GetEngine`, `GetGameInstance`, `GetGameViewportClient`,  `GetGameModeBase`, `GetGameStateBase`,`GetPersistentLevel` and `GetWorldSettings`
+- Added functions to get static objects: `GetKismetStringLibrary`, `GetKismetTextLibrary`
+- Added function `GetActorFromHitResult` which extracts the hit actor from a `FHitResult` struct based on UE's version
+- Added FName utility functions:
+  - `FName_None`: returns a `None` FName (FName with ComparisonIndex = 0)
+  - `FindFName`: wrapper for `FName(Name, EFindName.FNAME_Find)`
+  - `AddFName`: wrapper for  `FName(Name, EFindName.FNAME_Add)`
+- Added [Lua Server Annotations](https://luals.github.io/wiki/annotations/) to all UEHelpers functions
 
 ### C++ API
 Key binds created with `UE4SSProgram::register_keydown_event` end up being duplicated upon mod hot-reload.  
@@ -63,6 +74,14 @@ The following search filters now allow multiple values, with each value separate
 
 The callback of `NotifyOnNewObject` can now optionally return `true` to unregister itself ([UE4SS #432](https://github.com/UE4SS-RE/RE-UE4SS/pull/432)) - Lyrth
 
+#### UEHelpers [UE4SS #650](https://github.com/UE4SS-RE/RE-UE4SS/pull/650)
+- Increased version to 3
+- Reworked all UEHelpers functions to ensure that they always return an object which can be checked with the function `IsValid` for validation
+- Reworked `UEHelpers.GetPlayerController` to return first valid player controller (It will now return a player controller even if it doesn't control a pawn at the time)
+- Reworked `UEHelpers.GetWorld` function to use UWorld cache (UWorld usually never changes)
+- Change `UEHelpers.GetWorldContextObject` function annotation to return `UObject`. (Any UObject with a GetWorld() function is a valid WorldContext)
+- Removed duplicate function `UEHelpers.GetKismetMathLibrary`
+
 ### C++ API
 
 ### BPModLoader
@@ -110,6 +129,8 @@ Fixed crash when calling UFunctions that take one or more 'out' params of type T
 
 Fixed `RegisterProcessConsoleExecPostHook`. ([UE4SS #631](https://github.com/UE4SS-RE/RE-UE4SS/pull/631))
 
+Fixed `FindFirstOf` return type annotation in `Types.lua` to signal that the return value will never be nil. ([UE4SS #650](https://github.com/UE4SS-RE/RE-UE4SS/pull/650))
+
 ### C++ API
 Fixed a crash caused by a race condition enabled by C++ mods using `UE4SS_ENABLE_IMGUI` in their constructor ([UE4SS #481](https://github.com/UE4SS-RE/RE-UE4SS/pull/481))
 

assets/Mods/shared/UEHelpers/UEHelpers.lua

@@ -21,8 +21,13 @@ function RemoteObject:IsValid()
 end
 
 -- Functions local to this module, do not attempt to use!
-local CacheDefaultObject = function(ObjectFullName, VariableName, ForceInvalidateCache)
-    local DefaultObject = nil
+
+---@param ObjectFullName string
+---@param VariableName string
+---@param ForceInvalidateCache boolean?
+---@return UObject
+local function CacheDefaultObject(ObjectFullName, VariableName, ForceInvalidateCache)
+    local DefaultObject = RemoteObject:new()
 
     if not ForceInvalidateCache then
         DefaultObject = ModRef:GetSharedVariable(VariableName)
@@ -127,6 +132,28 @@ function UEHelpers.GetPersistentLevel()
     return RemoteObject:new() ---@type ULevel
 end
 
+---Returns UWorld->AuthorityGameMode<br>
+---The function doesn't guarantee to be an AGameMode, as many games derive their own game states directly from AGameModeBase!
+---@return AGameModeBase
+function UEHelpers.GetGameModeBase()
+    local World = UEHelpers.GetWorld()
+    if World:IsValid() and World.AuthorityGameMode:IsValid() then
+        return World.AuthorityGameMode
+    end
+    return RemoteObject:new() ---@type AGameModeBase
+end
+
+---Returns UWorld->GameState<br>
+---The function doesn't guarantee to be an AGameState, as many games derive their own game states directly from AGameStateBase!
+---@return AGameStateBase
+function UEHelpers.GetGameStateBase()
+    local World = UEHelpers.GetWorld()
+    if World:IsValid() and World.GameState:IsValid() then
+        return World.GameState
+    end
+    return RemoteObject:new() ---@type AGameStateBase
+end
+
 ---Returns PersistentLevel->WorldSettings
 ---@return AWorldSettings
 function UEHelpers.GetWorldSettings()
@@ -158,42 +185,42 @@ function UEHelpers.GetActorFromHitResult(HitResult)
     return HitResult.HitObjectHandle.Actor:Get()
 end
 
----@param ForceInvalidateCache boolean # Force update the cache
+---@param ForceInvalidateCache boolean? # Force update the cache
 ---@return UGameplayStatics
 function UEHelpers.GetGameplayStatics(ForceInvalidateCache)
     ---@type UGameplayStatics
     return CacheDefaultObject("/Script/Engine.Default__GameplayStatics", "UEHelpers_GameplayStatics", ForceInvalidateCache)
 end
 
----@param ForceInvalidateCache boolean # Force update the cache
+---@param ForceInvalidateCache boolean? # Force update the cache
 ---@return UKismetSystemLibrary
 function UEHelpers.GetKismetSystemLibrary(ForceInvalidateCache)
     ---@type UKismetSystemLibrary
     return CacheDefaultObject("/Script/Engine.Default__KismetSystemLibrary", "UEHelpers_KismetSystemLibrary", ForceInvalidateCache)
 end
 
----@param ForceInvalidateCache boolean # Force update the cache
+---@param ForceInvalidateCache boolean? # Force update the cache
 ---@return UKismetMathLibrary
 function UEHelpers.GetKismetMathLibrary(ForceInvalidateCache)
     ---@type UKismetMathLibrary
     return CacheDefaultObject("/Script/Engine.Default__KismetMathLibrary", "UEHelpers_KismetMathLibrary", ForceInvalidateCache)
 end
 
----@param ForceInvalidateCache boolean # Force update the cache
+---@param ForceInvalidateCache boolean? # Force update the cache
 ---@return UKismetStringLibrary
 function UEHelpers.GetKismetStringLibrary(ForceInvalidateCache)
     ---@type UKismetStringLibrary
     return CacheDefaultObject("/Script/Engine.Default__KismetStringLibrary", "UEHelpers_KismetStringLibrary", ForceInvalidateCache)
 end
 
----@param ForceInvalidateCache boolean # Force update the cache
+---@param ForceInvalidateCache boolean? # Force update the cache
 ---@return UKismetTextLibrary
 function UEHelpers.GetKismetTextLibrary(ForceInvalidateCache)
     ---@type UKismetTextLibrary
     return CacheDefaultObject("/Script/Engine.Default__KismetTextLibrary", "UEHelpers_KismetTextLibrary", ForceInvalidateCache)
 end
 
----@param ForceInvalidateCache boolean # Force update the cache
+---@param ForceInvalidateCache boolean? # Force update the cache
 ---@return UGameMapsSettings
 function UEHelpers.GetGameMapsSettings(ForceInvalidateCache)
     ---@type UGameMapsSettings