feat: Add global Lua function CreateInvalidObject which returns an in…

…valid UObject (#652)

docs: Add CreateInvalidObject function to Types.lua (#652)
docs: Fix return value of FindFirstOf, it's just UObject, never nil
docs: Add CreateInvalidObject documentation page
docs: Modify Changelog.md for current changes

UE4SS/src/Mod/LuaMod.cpp

@@ -839,6 +839,11 @@ namespace RC
     {
         lua.register_function("print", LuaLibrary::global_print);
 
+        lua.register_function("CreateInvalidObject", [](const LuaMadeSimple::Lua& lua) -> int {
+            LuaType::auto_construct_object(lua, nullptr);
+            return 1;
+        });
+
         lua.register_function("StaticFindObject", [](const LuaMadeSimple::Lua& lua) -> int {
             // Stack size @ the start of the function is the same as the number of params
             int32_t stack_size = lua.get_stack_size();

assets/Changelog.md

@@ -21,6 +21,7 @@ Added search filter: `IncludeClassNames`. ([UE4SS #472](https://github.com/UE4SS
 ### UHT Dumper
 
 ### Lua API
+Added global function `CreateInvalidObject`, which returns an invalid UObject. ([UE4SS #652](https://github.com/UE4SS-RE/RE-UE4SS/issues/652)) 
 
 ### C++ API
 Key binds created with `UE4SSProgram::register_keydown_event` end up being duplicated upon mod hot-reload.  
@@ -110,6 +111,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 #652](https://github.com/UE4SS-RE/RE-UE4SS/issues/652))
+
 ### 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/Types.lua

@@ -280,6 +280,10 @@ EInternalObjectFlags = {
 
 -- # Global Functions
 
+---Creates an blank UObject whose IsValid function always returns false
+---@return UObject
+function CreateInvalidObject() end
+
 ---@param ObjectName string
 ---@return UObject
 function StaticFindObject(ObjectName) end
@@ -294,7 +298,7 @@ function StaticFindObject(Class, InOuter, ObjectName, ExactClass) end
 
 ---Find the first non-default instance of the supplied class name
 ---@param ShortClassName string Should only contains the class name itself without path info
----@return UObject?
+---@return UObject
 function FindFirstOf(ShortClassName) end
 
 ---Find all non-default instances of the supplied class name

docs/SUMMARY.md

@@ -54,6 +54,7 @@
     - [FWeakObjectPtr](./lua-api/classes/fweakobjectptr.md)
   - [Global Functions]()
     - [print](./lua-api/global-functions/print.md)
+    - [CreateInvalidObject](./lua-api/global-functions/createinvalidobject.md)
     - [FName](./lua-api/global-functions/fname.md)
     - [FText](./lua-api/global-functions/ftext.md)
     - [IterateGameDirectories](./lua-api/global-functions/iterategamedirectories.md)

docs/lua-api.md

@@ -110,6 +110,9 @@ This is an overall list of API definitions available in UE4SS. For more readable
     print(any... Message)
         - Does not have the capability to format. Use 'string.format' if you require formatting.
     
+    CreateInvalidObject() -> UObject
+        - Creates an object with an IsValid function that always returns false
+
     StaticFindObject(string ObjectName) -> { UObject | AActor | nil }
     StaticFindObject(UClass Class=nil, UObject InOuter=nil, string ObjectName, bool ExactClass=false)
         - Maps to https://docs.unrealengine.com/4.26/en-US/API/Runtime/CoreUObject/UObject/StaticFindObject/

docs/lua-api/global-functions/createinvalidobject.md

@@ -0,0 +1,20 @@
+# CreateInvalidObject
+
+The function `CreateInvalidObject` always returns an object with an `IsValid` function that returns `flase`.
+
+The sole purpose of the function is to ensure that the mod's Lua code adheres to UE4SS code conventions, where all functions return an invalid `UObject` instead of `nil`.
+
+## Example
+The example code below ensures that you never need to check if `EngineCache` is `nil`, and the same applies to the return value of `GetEngine()`.
+```lua
+local EngineCache = CreateInvalidObject() ---@cast EngineCache UEngine
+---Returns instance of UEngine
+---@return UEngine
+function GetEngine()
+    if EngineCache:IsValid() then return EngineCache end
+
+    EngineCache = FindFirstOf("Engine") ---@type UEngine
+    return EngineCache
+end
+
+```