Ado/ProjectEleri
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update directive utilities plugin

Browse Source
This commit is contained in:
adnan.mujkic
2026-08-15 21:06:43 +02:00
parent 2fe7f83a38
commit a06fed1cba
103 changed files with 18211 additions and 1071 deletions
Download Patch File Download Diff File Expand all files Collapse all files

431
Plugins/DirectiveUtilities/Source/DirectiveUtilitiesRuntime/Public/Libraries/DirectiveUtilArrayFunctionLibrary.h
View File

@@ -51,7 +51,25 @@ public:
* @param TargetArray - The array to remove duplicates from.
*/
UFUNCTION(BlueprintCallable, CustomThunk, meta=(DisplayName = "Remove Duplicates", CompactNodeTitle = "REMOVE DUPLICATES", ArrayParm = "TargetArray"), Category="Directive Utilities|Array")
static void Array_RemoveDuplicates(const TArray<int32>& TargetArray);
static void Array_RemoveDuplicates(UPARAM(ref) TArray<int32>& TargetArray);
/**
* Appends every source element to the target array.
* @param TargetArray - The array to append to.
* @param SourceArray - The array to append.
*/
UFUNCTION(BlueprintCallable, CustomThunk, meta=(DisplayName = "Append Array Optimized", CompactNodeTitle = "APPEND", Keywords = "append merge concatenate bulk", ArrayParm = "TargetArray,SourceArray", ArrayTypeDependentParams = "SourceArray"), Category="Directive Utilities|Array")
static void Array_AppendOptimized(UPARAM(ref) TArray<int32>& TargetArray, const TArray<int32>& SourceArray);
/**
* Inserts every source element into the target array at the given index.
* @param TargetArray - The array to insert into.
* @param SourceArray - The array to insert.
* @param Index - The index at which to insert the source array.
* @returns True if one or more elements were inserted.
*/
UFUNCTION(BlueprintCallable, CustomThunk, meta=(DisplayName = "Insert Array Optimized", CompactNodeTitle = "INSERT ARRAY", Keywords = "insert splice merge bulk", ArrayParm = "TargetArray,SourceArray", ArrayTypeDependentParams = "SourceArray"), Category="Directive Utilities|Array")
static bool Array_InsertOptimized(UPARAM(ref) TArray<int32>& TargetArray, const TArray<int32>& SourceArray, const int32 Index);
/**
* Returns a copy of the first element of the array.
@@ -106,7 +124,7 @@ public:
* @returns True if an element was removed.
*/
UFUNCTION(BlueprintCallable, CustomThunk, meta=(DisplayName = "Pop", ArrayParm = "TargetArray", ArrayTypeDependentParams = "OutItem"), Category="Directive Utilities|Array")
static bool Array_Pop(const TArray<int32>& TargetArray, int32& OutItem);
static bool Array_Pop(UPARAM(ref) TArray<int32>& TargetArray, int32& OutItem);
/**
* Removes the first element of the array and returns a copy of it.
@@ -115,7 +133,7 @@ public:
* @returns True if an element was removed.
*/
UFUNCTION(BlueprintCallable, CustomThunk, meta=(DisplayName = "Pop First", ArrayParm = "TargetArray", ArrayTypeDependentParams = "OutItem"), Category="Directive Utilities|Array")
static bool Array_PopFirst(const TArray<int32>& TargetArray, int32& OutItem);
static bool Array_PopFirst(UPARAM(ref) TArray<int32>& TargetArray, int32& OutItem);
/**
* Removes the element at the given index by swapping it with the last element (does not preserve order).
@@ -125,7 +143,26 @@ public:
* @returns True if the index was valid and an element was removed.
*/
UFUNCTION(BlueprintCallable, CustomThunk, meta=(DisplayName = "Remove At Swap", ArrayParm = "TargetArray"), Category="Directive Utilities|Array")
static bool Array_RemoveAtSwap(const TArray<int32>& TargetArray, const int32 Index);
static bool Array_RemoveAtSwap(UPARAM(ref) TArray<int32>& TargetArray, const int32 Index);
/**
* Removes the elements at the given indices while preserving the order of the remaining elements.
* Duplicate and invalid indices are ignored.
* @param TargetArray - The array to remove from.
* @param Indices - The indices to remove.
* @returns The number of elements removed.
*/
UFUNCTION(BlueprintCallable, CustomThunk, meta=(DisplayName = "Remove At Indices", CompactNodeTitle = "REMOVE INDICES", Keywords = "remove delete batch multiple", ArrayParm = "TargetArray"), Category="Directive Utilities|Array")
static int32 Array_RemoveAtIndices(UPARAM(ref) TArray<int32>& TargetArray, const TArray<int32>& Indices);
/**
* Removes every matching item while preserving the order of the remaining elements.
* @param TargetArray - The array to remove matching items from.
* @param Item - The item to remove.
* @returns True if one or more items were removed.
*/
UFUNCTION(BlueprintCallable, CustomThunk, meta=(DisplayName = "Remove All Occurrences", CompactNodeTitle = "REMOVE ALL", Keywords = "remove item delete matching", ArrayParm = "TargetArray", ArrayTypeDependentParams = "Item", AutoCreateRefTerm = "Item"), Category="Directive Utilities|Array")
static bool Array_RemoveAllOccurrences(UPARAM(ref) TArray<int32>& TargetArray, const int32& Item);
/**
* Returns a copy of a contiguous range of the array. The range is clamped to the array bounds.
@@ -143,7 +180,7 @@ public:
* @param Shift - The number of positions to rotate. Positive rotates toward the end; negative toward the start.
*/
UFUNCTION(BlueprintCallable, CustomThunk, meta=(DisplayName = "Rotate", ArrayParm = "TargetArray"), Category="Directive Utilities|Array")
static void Array_Rotate(const TArray<int32>& TargetArray, const int32 Shift);
static void Array_Rotate(UPARAM(ref) TArray<int32>& TargetArray, const int32 Shift);
/**
* Returns a copy of the array with duplicates removed, keeping the first occurrence and preserving order.
@@ -173,6 +210,72 @@ public:
UFUNCTION(BlueprintPure, CustomThunk, meta=(DisplayName = "Get Most Common", ArrayParm = "TargetArray", ArrayTypeDependentParams = "OutItem", BlueprintThreadSafe), Category="Directive Utilities|Array")
static bool Array_GetMostCommon(const TArray<int32>& TargetArray, int32& OutItem, int32& OutCount);
/**
* Returns randomly selected elements from the array.
* @param TargetArray The array to sample.
* @param Count The requested number of elements, up to 1,000,000.
* @param bWithReplacement Whether the same source element can be selected more than once.
* @param OutArray The sampled elements.
*/
UFUNCTION(BlueprintCallable, CustomThunk, meta=(DisplayName = "Sample Array", ArrayParm = "TargetArray,OutArray", ArrayTypeDependentParams = "OutArray"), Category="Directive Utilities|Array")
static void Array_Sample(const TArray<int32>& TargetArray, int32 Count, bool bWithReplacement, TArray<int32>& OutArray);
/**
* Returns randomly selected elements using a random stream.
* @param TargetArray The array to sample.
* @param Count The requested number of elements, up to 1,000,000.
* @param bWithReplacement Whether the same source element can be selected more than once.
* @param RandomStream The stream used to select elements.
* @param OutArray The sampled elements.
*/
UFUNCTION(BlueprintCallable, CustomThunk, meta=(DisplayName = "Sample Array from Stream", ArrayParm = "TargetArray,OutArray", ArrayTypeDependentParams = "OutArray"), Category="Directive Utilities|Array")
static void Array_SampleFromStream(const TArray<int32>& TargetArray, int32 Count, bool bWithReplacement, UPARAM(ref) FRandomStream& RandomStream, TArray<int32>& OutArray);
/**
* Returns randomly selected elements using per-element weights.
* @param TargetArray The array to sample.
* @param Weights The selection weight for each source element.
* @param Count The requested number of elements, up to 1,000,000.
* @param bWithReplacement Whether the same source element can be selected more than once.
* @param OutArray The sampled elements.
* @returns True when the inputs were valid and the sample was produced.
*/
UFUNCTION(BlueprintCallable, CustomThunk, meta=(DisplayName = "Sample Weighted Array", ArrayParm = "TargetArray,OutArray", ArrayTypeDependentParams = "OutArray"), Category="Directive Utilities|Array")
static bool Array_SampleWeighted(const TArray<int32>& TargetArray, const TArray<float>& Weights, int32 Count, bool bWithReplacement, TArray<int32>& OutArray);
/**
* Returns randomly selected elements using per-element weights and a random stream.
* @param TargetArray The array to sample.
* @param Weights The selection weight for each source element.
* @param Count The requested number of elements, up to 1,000,000.
* @param bWithReplacement Whether the same source element can be selected more than once.
* @param RandomStream The stream used to select elements.
* @param OutArray The sampled elements.
* @returns True when the inputs were valid and the sample was produced.
*/
UFUNCTION(BlueprintCallable, CustomThunk, meta=(DisplayName = "Sample Weighted Array from Stream", ArrayParm = "TargetArray,OutArray", ArrayTypeDependentParams = "OutArray"), Category="Directive Utilities|Array")
static bool Array_SampleWeightedFromStream(const TArray<int32>& TargetArray, const TArray<float>& Weights, int32 Count, bool bWithReplacement, UPARAM(ref) FRandomStream& RandomStream, TArray<int32>& OutArray);
/**
* Returns one zero-based page from the array.
* @param TargetArray The array to read.
* @param PageIndex The zero-based page index.
* @param PageSize The maximum number of elements per page.
* @param OutArray The requested page.
* @param OutPageCount The total number of pages.
* @returns True when the page index and size are valid.
*/
UFUNCTION(BlueprintPure, CustomThunk, meta=(DisplayName = "Get Array Page", ArrayParm = "TargetArray,OutArray", ArrayTypeDependentParams = "OutArray", BlueprintThreadSafe), Category="Directive Utilities|Array")
static bool Array_GetPage(const TArray<int32>& TargetArray, int32 PageIndex, int32 PageSize, TArray<int32>& OutArray, int32& OutPageCount);
/** Sorts strings in natural order so embedded numbers are compared numerically. */
UFUNCTION(BlueprintCallable, Category="Directive Utilities|Array")
static void NaturalSortStringArray(UPARAM(ref) TArray<FString>& TargetArray, bool bDescending = false);
/** Sorts names in natural order so embedded numbers are compared numerically. */
UFUNCTION(BlueprintCallable, Category="Directive Utilities|Array")
static void NaturalSortNameArray(UPARAM(ref) TArray<FName>& TargetArray, bool bDescending = false);
/*~
* Native functions that will be called by the below custom thunk layers, which read off the property address and call the appropriate native handler.
@@ -182,6 +285,8 @@ public:
static int32 GenericArray_NextIndex(const void* TargetArray, const FArrayProperty* ArrayProperty, int32 Index, bool bLoop);
static int32 GenericArray_PreviousIndex(const void* TargetArray, const FArrayProperty* ArrayProperty, int32 Index, bool bLoop);
static void GenericArray_RemoveDuplicates(void* TargetArray, const FArrayProperty* ArrayProperty);
static void GenericArray_AppendOptimized(void* TargetArray, const FArrayProperty* TargetArrayProperty, const void* SourceArray, const FArrayProperty* SourceArrayProperty);
static bool GenericArray_InsertOptimized(void* TargetArray, const FArrayProperty* TargetArrayProperty, const void* SourceArray, const FArrayProperty* SourceArrayProperty, int32 Index);
static bool GenericArray_GetItemAtIndex(const void* TargetArray, const FArrayProperty* ArrayProperty, int32 Index, void* OutItemPtr);
static bool GenericArray_GetFirstItem(const void* TargetArray, const FArrayProperty* ArrayProperty, void* OutItemPtr);
static bool GenericArray_GetLastItem(const void* TargetArray, const FArrayProperty* ArrayProperty, void* OutItemPtr);
@@ -189,11 +294,16 @@ public:
static bool GenericArray_Pop(void* TargetArray, const FArrayProperty* ArrayProperty, void* OutItemPtr);
static bool GenericArray_PopFirst(void* TargetArray, const FArrayProperty* ArrayProperty, void* OutItemPtr);
static bool GenericArray_RemoveAtSwap(void* TargetArray, const FArrayProperty* ArrayProperty, int32 Index);
static int32 GenericArray_RemoveAtIndices(void* TargetArray, const FArrayProperty* ArrayProperty, const TArray<int32>& Indices);
static bool GenericArray_RemoveAllOccurrences(void* TargetArray, const FArrayProperty* ArrayProperty, const void* Item);
static void GenericArray_Slice(const void* TargetArray, const FArrayProperty* TargetArrayProperty, int32 StartIndex, int32 Count, void* OutArray, const FArrayProperty* OutArrayProperty);
static void GenericArray_Rotate(void* TargetArray, const FArrayProperty* ArrayProperty, int32 Shift);
static void GenericArray_GetDistinct(const void* TargetArray, const FArrayProperty* TargetArrayProperty, void* OutArray, const FArrayProperty* OutArrayProperty);
static int32 GenericArray_CountOccurrences(const void* TargetArray, const FArrayProperty* ArrayProperty, const void* ItemToCount);
static bool GenericArray_GetMostCommon(const void* TargetArray, const FArrayProperty* ArrayProperty, void* OutItemPtr, int32* OutCount);
static void GenericArray_Sample(const void* TargetArray, const FArrayProperty* TargetArrayProperty, int32 Count, bool bWithReplacement, FRandomStream* RandomStream, void* OutArray, const FArrayProperty* OutArrayProperty);
static bool GenericArray_SampleWeighted(const void* TargetArray, const FArrayProperty* TargetArrayProperty, const TArray<float>& Weights, int32 Count, bool bWithReplacement, FRandomStream* RandomStream, void* OutArray, const FArrayProperty* OutArrayProperty);
static bool GenericArray_GetPage(const void* TargetArray, const FArrayProperty* TargetArrayProperty, int32 PageIndex, int32 PageSize, void* OutArray, const FArrayProperty* OutArrayProperty, int32* OutPageCount);
/*~
* Custom thunk layers that read off the property address and call the appropriate native handler.
@@ -258,6 +368,78 @@ public:
P_NATIVE_END;
}
DECLARE_FUNCTION(execArray_AppendOptimized)
{
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
void* TargetArrayAddr = Stack.MostRecentPropertyAddress;
FArrayProperty* TargetArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!TargetArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
const void* SourceArrayAddr = Stack.MostRecentPropertyAddress;
const FArrayProperty* SourceArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!SourceArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
P_FINISH;
P_NATIVE_BEGIN;
MARK_PROPERTY_DIRTY(Stack.Object, TargetArrayProperty);
GenericArray_AppendOptimized(
TargetArrayAddr,
TargetArrayProperty,
SourceArrayAddr,
SourceArrayProperty);
P_NATIVE_END;
}
DECLARE_FUNCTION(execArray_InsertOptimized)
{
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
void* TargetArrayAddr = Stack.MostRecentPropertyAddress;
FArrayProperty* TargetArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!TargetArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
const void* SourceArrayAddr = Stack.MostRecentPropertyAddress;
const FArrayProperty* SourceArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!SourceArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
P_GET_PROPERTY(FIntProperty, Index);
P_FINISH;
P_NATIVE_BEGIN;
const bool bInserted = GenericArray_InsertOptimized(
TargetArrayAddr,
TargetArrayProperty,
SourceArrayAddr,
SourceArrayProperty,
Index);
if (bInserted)
{
MARK_PROPERTY_DIRTY(Stack.Object, TargetArrayProperty);
}
*static_cast<bool*>(RESULT_PARAM) = bInserted;
P_NATIVE_END;
}
DECLARE_FUNCTION(execArray_GetValidFirstItemCopy)
{
Stack.MostRecentProperty = nullptr;
@@ -565,6 +747,70 @@ public:
P_NATIVE_END;
}
DECLARE_FUNCTION(execArray_RemoveAtIndices)
{
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
void* ArrayAddr = Stack.MostRecentPropertyAddress;
FArrayProperty* ArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!ArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
P_GET_TARRAY_REF(int32, Indices);
P_FINISH;
P_NATIVE_BEGIN;
const int32 RemovedCount = GenericArray_RemoveAtIndices(ArrayAddr, ArrayProperty, Indices);
if (RemovedCount > 0)
{
MARK_PROPERTY_DIRTY(Stack.Object, ArrayProperty);
}
*static_cast<int32*>(RESULT_PARAM) = RemovedCount;
P_NATIVE_END;
}
DECLARE_FUNCTION(execArray_RemoveAllOccurrences)
{
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
void* ArrayAddr = Stack.MostRecentPropertyAddress;
FArrayProperty* ArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!ArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
const FProperty* InnerProp = ArrayProperty->Inner;
const int32 PropertySize = InnerProp->GetElementSize() * InnerProp->ArrayDim;
void* StorageSpace = FMemory_Alloca(PropertySize);
InnerProp->InitializeValue(StorageSpace);
Stack.MostRecentPropertyAddress = nullptr;
Stack.MostRecentPropertyContainer = nullptr;
Stack.StepCompiledIn<FProperty>(StorageSpace);
P_FINISH;
if (const FBoolProperty* BoolProperty = CastField<const FBoolProperty>(InnerProp))
{
ensure(PropertySize == sizeof(uint8));
BoolProperty->SetPropertyValue(StorageSpace, *static_cast<uint8*>(StorageSpace) != 0);
}
P_NATIVE_BEGIN;
const bool bRemoved = GenericArray_RemoveAllOccurrences(ArrayAddr, ArrayProperty, StorageSpace);
if (bRemoved)
{
MARK_PROPERTY_DIRTY(Stack.Object, ArrayProperty);
}
*static_cast<bool*>(RESULT_PARAM) = bRemoved;
P_NATIVE_END;
InnerProp->DestroyValue(StorageSpace);
}
DECLARE_FUNCTION(execArray_Slice)
{
Stack.MostRecentProperty = nullptr;
@@ -713,4 +959,179 @@ public:
P_NATIVE_END;
InnerProp->DestroyValue(StorageSpace);
}
DECLARE_FUNCTION(execArray_Sample)
{
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
const void* SourceArrayAddr = Stack.MostRecentPropertyAddress;
const FArrayProperty* SourceArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!SourceArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
P_GET_PROPERTY(FIntProperty, Count);
P_GET_UBOOL(bWithReplacement);
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
void* OutArrayAddr = Stack.MostRecentPropertyAddress;
const FArrayProperty* OutArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!OutArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
P_FINISH;
P_NATIVE_BEGIN;
GenericArray_Sample(SourceArrayAddr, SourceArrayProperty, Count, bWithReplacement, nullptr, OutArrayAddr, OutArrayProperty);
P_NATIVE_END;
}
DECLARE_FUNCTION(execArray_SampleFromStream)
{
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
const void* SourceArrayAddr = Stack.MostRecentPropertyAddress;
const FArrayProperty* SourceArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!SourceArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
P_GET_PROPERTY(FIntProperty, Count);
P_GET_UBOOL(bWithReplacement);
P_GET_STRUCT_REF(FRandomStream, RandomStream);
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
void* OutArrayAddr = Stack.MostRecentPropertyAddress;
const FArrayProperty* OutArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!OutArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
P_FINISH;
P_NATIVE_BEGIN;
GenericArray_Sample(SourceArrayAddr, SourceArrayProperty, Count, bWithReplacement, &RandomStream, OutArrayAddr, OutArrayProperty);
P_NATIVE_END;
}
DECLARE_FUNCTION(execArray_SampleWeighted)
{
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
const void* SourceArrayAddr = Stack.MostRecentPropertyAddress;
const FArrayProperty* SourceArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!SourceArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
P_GET_TARRAY_REF(float, Weights);
P_GET_PROPERTY(FIntProperty, Count);
P_GET_UBOOL(bWithReplacement);
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
void* OutArrayAddr = Stack.MostRecentPropertyAddress;
const FArrayProperty* OutArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!OutArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
P_FINISH;
P_NATIVE_BEGIN;
*static_cast<bool*>(RESULT_PARAM) = GenericArray_SampleWeighted(
SourceArrayAddr,
SourceArrayProperty,
Weights,
Count,
bWithReplacement,
nullptr,
OutArrayAddr,
OutArrayProperty);
P_NATIVE_END;
}
DECLARE_FUNCTION(execArray_SampleWeightedFromStream)
{
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
const void* SourceArrayAddr = Stack.MostRecentPropertyAddress;
const FArrayProperty* SourceArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!SourceArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
P_GET_TARRAY_REF(float, Weights);
P_GET_PROPERTY(FIntProperty, Count);
P_GET_UBOOL(bWithReplacement);
P_GET_STRUCT_REF(FRandomStream, RandomStream);
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
void* OutArrayAddr = Stack.MostRecentPropertyAddress;
const FArrayProperty* OutArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!OutArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
P_FINISH;
P_NATIVE_BEGIN;
*static_cast<bool*>(RESULT_PARAM) = GenericArray_SampleWeighted(
SourceArrayAddr,
SourceArrayProperty,
Weights,
Count,
bWithReplacement,
&RandomStream,
OutArrayAddr,
OutArrayProperty);
P_NATIVE_END;
}
DECLARE_FUNCTION(execArray_GetPage)
{
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
const void* SourceArrayAddr = Stack.MostRecentPropertyAddress;
const FArrayProperty* SourceArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!SourceArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
P_GET_PROPERTY(FIntProperty, PageIndex);
P_GET_PROPERTY(FIntProperty, PageSize);
Stack.MostRecentProperty = nullptr;
Stack.StepCompiledIn<FArrayProperty>(nullptr);
void* OutArrayAddr = Stack.MostRecentPropertyAddress;
const FArrayProperty* OutArrayProperty = CastField<FArrayProperty>(Stack.MostRecentProperty);
if (!OutArrayProperty)
{
Stack.bArrayContextFailed = true;
return;
}
Stack.MostRecentProperty = nullptr;
Stack.MostRecentPropertyAddress = nullptr;
Stack.StepCompiledIn<FProperty>(nullptr);
int32* OutPageCount = reinterpret_cast<int32*>(Stack.MostRecentPropertyAddress);
P_FINISH;
P_NATIVE_BEGIN;
*static_cast<bool*>(RESULT_PARAM) = GenericArray_GetPage(SourceArrayAddr, SourceArrayProperty, PageIndex, PageSize, OutArrayAddr, OutArrayProperty, OutPageCount);
P_NATIVE_END;
}
};

45
Plugins/DirectiveUtilities/Source/DirectiveUtilitiesRuntime/Public/Libraries/DirectiveUtilFunctionLibrary.h
View File

@@ -4,6 +4,7 @@
#include "CoreMinimal.h"
#include "Kismet/BlueprintFunctionLibrary.h"
#include "Types/DirectiveUtilTypes.h"
#include "DirectiveUtilFunctionLibrary.generated.h"
/**
@@ -46,14 +47,14 @@ public:
* Get the content from the clipboard as FText.
* @returns The text from the clipboard.
*/
UFUNCTION(BlueprintPure, Category = "Directive Utilities|Clipboard" )
UFUNCTION(BlueprintCallable, Category = "Directive Utilities|Clipboard" )
static FText GetTextFromClipboard();
/**
* Get the content from the clipboard as an FString.
* @returns The content from the clipboard as a string.
*/
UFUNCTION(BlueprintPure, Category = "Directive Utilities|Clipboard" )
UFUNCTION(BlueprintCallable, Category = "Directive Utilities|Clipboard" )
static FString GetStringFromClipboard();
/**
@@ -77,6 +78,28 @@ public:
UFUNCTION(BlueprintPure, Category = "Directive Utilities|Utility")
static bool IsRunningInEditor();
/**
* Gets the type of world associated with the supplied context.
* @param WorldContextObject Object used to resolve the current world.
* @returns The resolved world type, or Unknown when the context has no world.
*/
UFUNCTION(BlueprintPure, Category = "Directive Utilities|Utility", meta = (WorldContext = "WorldContextObject"))
static EDirectiveUtilWorldType GetWorldType(const UObject* WorldContextObject);
/**
* Gets the build configuration of the running application.
* @returns The active build configuration.
*/
UFUNCTION(BlueprintPure, Category = "Directive Utilities|Utility", meta = (BlueprintThreadSafe))
static EDirectiveUtilBuildConfiguration GetBuildConfigurationType();
/**
* Gets the build target type of the running application.
* @returns The active build target type.
*/
UFUNCTION(BlueprintPure, Category = "Directive Utilities|Utility", meta = (BlueprintThreadSafe))
static EDirectiveUtilBuildTargetType GetBuildTargetType();
/**
* Checks whether a switch (e.g. "MySwitch" matching "-MySwitch") was passed on the
* process command line. Matching is case-insensitive.
@@ -96,6 +119,24 @@ public:
UFUNCTION(BlueprintPure, Category = "Directive Utilities|Utility")
static bool GetCommandLineOption(const FString& Key, FString& OutValue);
/**
* Starts a keyed stopwatch using monotonic real time.
* @param Key The name used to stop this stopwatch.
* @param bRestartIfRunning Whether to replace an active stopwatch with the same key.
* @returns True when the stopwatch was started.
*/
UFUNCTION(BlueprintCallable, Category = "Directive Utilities|Utility|Profiling", meta = (DisplayName = "Start Stopwatch", Keywords = "timer profiling benchmark elapsed milliseconds"))
static bool StartStopwatch(FName Key, bool bRestartIfRunning = false);
/**
* Stops a keyed stopwatch and returns its elapsed real time.
* @param Key The name passed to Start Stopwatch.
* @param ElapsedMilliseconds The elapsed time in milliseconds, or zero when the key is not active.
* @returns True when an active stopwatch was found.
*/
UFUNCTION(BlueprintCallable, Category = "Directive Utilities|Utility|Profiling", meta = (DisplayName = "Stop Stopwatch", Keywords = "timer profiling benchmark elapsed milliseconds"))
static bool StopStopwatch(FName Key, double& ElapsedMilliseconds);
/** Core of Has Command Line Switch that checks an explicit command line. */
static bool HasCommandLineSwitch(const TCHAR* CommandLine, const FString& Switch);

8
Plugins/DirectiveUtilities/Source/DirectiveUtilitiesRuntime/Public/Libraries/DirectiveUtilGameplayTagFunctionLibrary.h
View File

@@ -32,7 +32,7 @@ public:
* @param Tag - The tag to read.
* @returns A container of the tag's ancestors.
*/
UFUNCTION(BlueprintPure, Category = "Directive Utilities|GameplayTags", meta = (BlueprintThreadSafe))
UFUNCTION(BlueprintPure, Category = "Directive Utilities|GameplayTags")
static FGameplayTagContainer GetTagParents(const FGameplayTag& Tag);
/**
@@ -65,7 +65,7 @@ public:
* @param Tag - The tag to read.
* @returns A container of the tag's descendants, or an empty container for an invalid tag.
*/
UFUNCTION(BlueprintPure, Category = "Directive Utilities|GameplayTags", meta = (BlueprintThreadSafe))
UFUNCTION(BlueprintPure, Category = "Directive Utilities|GameplayTags")
static FGameplayTagContainer GetTagChildren(const FGameplayTag& Tag);
/**
@@ -73,7 +73,7 @@ public:
* @param Tag - The tag to read.
* @returns A container of the tag's direct children, or an empty container for an invalid tag.
*/
UFUNCTION(BlueprintPure, Category = "Directive Utilities|GameplayTags", meta = (BlueprintThreadSafe))
UFUNCTION(BlueprintPure, Category = "Directive Utilities|GameplayTags")
static FGameplayTagContainer GetTagDirectChildren(const FGameplayTag& Tag);
/**
@@ -110,7 +110,7 @@ public:
* @param Tag - The tag to test.
* @returns True if the tag is valid and has no registered descendants; false for an invalid tag.
*/
UFUNCTION(BlueprintPure, Category = "Directive Utilities|GameplayTags", meta = (BlueprintThreadSafe))
UFUNCTION(BlueprintPure, Category = "Directive Utilities|GameplayTags")
static bool IsLeafTag(const FGameplayTag& Tag);
/**

26
Plugins/DirectiveUtilities/Source/DirectiveUtilitiesRuntime/Public/Libraries/DirectiveUtilInputFunctionLibrary.h
View File

@@ -36,7 +36,7 @@ public:
/**
* Remove multiple Input Mapping Contexts.
* @param PlayerController The player controller to remove the contexts from. Will attempt to get the LocalPlayer from the controller.
* @param Contexts The contexts to remove.
* @param Contexts Loaded contexts to remove. This function does not load missing assets.
* @returns Returns Success if the contexts were successfully removed.
*/
UFUNCTION(BlueprintCallable, Category = "Directive Utilities|Input", meta=(ExpandEnumAsExecs="ReturnValue", DefaultToSelf="PlayerController"))
@@ -45,17 +45,17 @@ public:
const TArray<TSoftObjectPtr<UInputMappingContext>>& Contexts);
/**
* Swap a designated Input Mapping Context with a new one.
* If the previous context is found, it will be removed and the new context will be added.
* If the previous context is not found, the new context will be added at the specified priority.
* @param PlayerController The player controller to swap the contexts on. Will attempt to get the LocalPlayer from the controller.
* @param PreviousContext The context to swap out.
* @param NewContext The context to swap in.
* @param Priority The priority to set the new context to.
* @param bUsePreviousPriority Whether to use the previous context's priority when adding the new context.
* @returns Returns Success if the contexts were successfully swapped.
*/
UFUNCTION(BlueprintCallable, Category = "Directive Utilities|Input", meta=(ExpandEnumAsExecs="ReturnValue", DefaultToSelf="PlayerController"))
* Swap a designated Input Mapping Context with a new one.
* If the previous context is found, it will be removed and the new context will be added.
* If the previous context is not found, the new context will be added at the specified priority.
* @param PlayerController The player controller to swap the contexts on. Will attempt to get the LocalPlayer from the controller.
* @param PreviousContext The context to swap out.
* @param NewContext The context to swap in. This asset is loaded synchronously when needed.
* @param Priority The priority to set the new context to.
* @param bUsePreviousPriority Whether to use the previous context's priority when adding the new context.
* @returns Returns Success if the contexts were successfully swapped.
*/
UFUNCTION(BlueprintCallable, Category = "Directive Utilities|Input", meta=(ExpandEnumAsExecs="ReturnValue", DefaultToSelf="PlayerController"))
static EDirectiveUtilSuccessStatus SwapInputMappingContexts(
AController* PlayerController,
TSoftObjectPtr<UInputMappingContext> PreviousContext,
@@ -74,7 +74,7 @@ public:
/**
* Returns whether the given input mapping context is currently active on the controller.
* @param PlayerController - The player controller to query.
* @param Context - The input mapping context to check.
* @param Context - The loaded input mapping context to check. This function does not load missing assets.
* @returns True if the context is currently applied.
*/
UFUNCTION(BlueprintPure, Category = "Directive Utilities|Input", meta=(DefaultToSelf="PlayerController"))

2
Plugins/DirectiveUtilities/Source/DirectiveUtilitiesRuntime/Public/Libraries/DirectiveUtilMapFunctionLibrary.h
View File

@@ -67,7 +67,7 @@ public:
* @param SourceMap - The map to copy from.
* @param bOverwriteExisting - If true, keys already present in TargetMap are overwritten with SourceMap's values.
*/
UFUNCTION(BlueprintCallable, CustomThunk, meta=(DisplayName = "Append", CompactNodeTitle = "APPEND", MapParam = "TargetMap|SourceMap"), Category="Directive Utilities|Map")
UFUNCTION(BlueprintCallable, CustomThunk, meta=(BlueprintInternalUseOnly = "true", DisplayName = "Append", CompactNodeTitle = "APPEND", MapParam = "TargetMap|SourceMap"), Category="Directive Utilities|Map")
static void Map_Append(const TMap<int32, int32>& TargetMap, const TMap<int32, int32>& SourceMap, bool bOverwriteExisting = true);
/*~

608
Plugins/DirectiveUtilities/Source/DirectiveUtilitiesRuntime/Public/Libraries/DirectiveUtilMathFunctionLibrary.h
View File

@@ -3,6 +3,7 @@
#pragma once
#include "CoreMinimal.h"
#include "Components/SplineComponent.h"
#include "Kismet/BlueprintFunctionLibrary.h"
#include "Types/DirectiveUtilMathTypes.h"
#include "DirectiveUtilMathFunctionLibrary.generated.h"
@@ -18,6 +19,7 @@ class DIRECTIVEUTILITIESRUNTIME_API UDirectiveUtilMathFunctionLibrary : public U
GENERATED_BODY()
public:
static constexpr int32 MaximumGeneratedElementCount = 1000000;
/**
* Returns a perlin noise value between -1 and 1 at the given position.
@@ -41,18 +43,507 @@ public:
* Returns the angle in degrees between two vectors.
* @param A - The first vector.
* @param B - The second vector.
* @returns The angle between the two vectors in degrees.
* @returns The angle between the two vectors in degrees, or 0 if either
* vector is zero or non-finite.
*/
UFUNCTION(BlueprintPure, meta = (BlueprintThreadSafe), Category = "Directive Utilities|Math|Vector")
static float AngleBetweenVectors(const FVector& A, const FVector& B);
/**
* Returns the signed angle in degrees from one vector to another around an axis.
* The vectors are projected onto the plane perpendicular to the axis before measuring.
* @param From - The starting direction.
* @param To - The target direction.
* @param Axis - The axis that defines the rotation plane and positive direction.
* @returns The signed angle in the [-180, 180] range, or 0 if an input cannot define a direction.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Signed Angle Between Vectors", BlueprintThreadSafe), Category = "Directive Utilities|Math|Vector")
static float SignedAngleBetweenVectors(const FVector& From, const FVector& To, const FVector& Axis);
/**
* Returns the shortest signed difference in degrees from one angle to another.
* Exactly opposite angles always return +180, regardless of how the inputs are spelled.
* @param From - The starting angle in degrees.
* @param To - The target angle in degrees.
* @returns The signed difference in the (-180, 180] range, or 0 for non-finite input.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Delta Angle (Degrees)", BlueprintThreadSafe), Category = "Directive Utilities|Math|Float")
static float DeltaAngle(float From, float To);
/**
* Interpolates between two angles along the shortest path.
* Alpha 0 returns A. Values outside [0, 1] extrapolate along that same
* shortest-path direction without wrapping, so a timeline past the end
* does not jump the seam.
* @param A - The starting angle in degrees.
* @param B - The target angle in degrees.
* @param Alpha - The interpolation alpha. Values outside [0, 1] extrapolate.
* @returns A plus the shortest signed delta to B, scaled by Alpha, or 0 for non-finite input.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Lerp Angle (Degrees)", BlueprintThreadSafe), Category = "Directive Utilities|Math|Float")
static float LerpAngle(float A, float B, float Alpha);
/**
* Repeats a value between two bounds, reversing direction at each bound.
* @param Value - The value to repeat.
* @param Minimum - One range bound.
* @param Maximum - The other range bound.
* @returns The ping-ponged value, the shared bound for a zero-sized range, or 0 for non-finite input.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Ping Pong (Float)", BlueprintThreadSafe), Category = "Directive Utilities|Math|Float")
static float PingPong(float Value, float Minimum = 0.0f, float Maximum = 1.0f);
/**
* Applies cubic smoothing to a value between two bounds.
* @returns A value in the [0, 1] range, or 0 for non-finite input.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Smooth Step", BlueprintThreadSafe), Category = "Directive Utilities|Math|Float")
static float SmoothStep(float Value, float Minimum = 0.0f, float Maximum = 1.0f);
/**
* Applies quintic smoothing to a value between two bounds.
* @returns A value in the [0, 1] range, or 0 for non-finite input.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Smoother Step", BlueprintThreadSafe), Category = "Directive Utilities|Math|Float")
static float SmootherStep(float Value, float Minimum = 0.0f, float Maximum = 1.0f);
/**
* Returns a normalized falloff between an inner and outer radius.
* @returns 1 at or inside the inner radius, 0 beyond the outer radius, or 0 for non-finite input.
* Equal radii are a step: 1 at or inside the shared radius, 0 outside.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Range Falloff", BlueprintThreadSafe), Category = "Directive Utilities|Math|Float")
static float RangeFalloff(float Distance, float InnerRadius, float OuterRadius, float FalloffExponent = 1.0f);
/**
* Tests whether a direction lies within a cone centered on another direction.
* @param Direction - The direction to test.
* @param ConeDirection - The center direction of the cone.
* @param ConeHalfAngleDegrees - The angle from the cone center to its edge. Clamped to [0, 180].
* @returns True when the direction lies inside or on the cone, or false for an invalid direction or angle.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Is Direction Within Cone", BlueprintThreadSafe), Category = "Directive Utilities|Math|Vector")
static bool IsDirectionWithinCone(const FVector& Direction, const FVector& ConeDirection, float ConeHalfAngleDegrees);
/**
* Calculates the normalized direction and distance from one point to another.
* @returns False when the points are equal or an input is non-finite.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Get Direction And Distance", BlueprintThreadSafe), Category = "Directive Utilities|Math|Vector")
static bool GetDirectionAndDistance(const FVector& From, const FVector& To, FVector& Direction, double& Distance);
/**
* Rotates a 2D point around a pivot in degrees.
* @returns The rotated point, or zero for non-finite input.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Rotate Point Around Pivot 2D", BlueprintThreadSafe), Category = "Directive Utilities|Math|Vector")
static FVector2D RotatePointAroundPivot2D(const FVector2D& Point, const FVector2D& Pivot, float AngleDegrees);
/**
* Calculates the signed distance from a point to a plane.
* @returns The signed distance, or 0 when the plane normal is zero or an input is non-finite.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Signed Distance To Plane", BlueprintThreadSafe), Category = "Directive Utilities|Math|Vector")
static double SignedDistanceToPlane(const FVector& Point, const FVector& PlanePoint, const FVector& PlaneNormal);
/**
* Tests whether a point lies within a cone and optional maximum distance.
* @returns True when the point lies inside or on the cone and within the distance limit.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Is Point Within Cone", BlueprintThreadSafe), Category = "Directive Utilities|Math|Vector")
static bool IsPointWithinCone(const FVector& Point, const FVector& ConeOrigin, const FVector& ConeDirection,
float ConeHalfAngleDegrees, double MaximumDistance = 0.0);
/**
* Samples a location along the polyline through an array, with Alpha 0 at the first point and 1 at the last.
* Progress is distance-weighted, so equal alpha steps cover equal distance.
* A closed loop adds the segment from the last point back to the first and wraps Alpha instead of clamping it.
* @returns The sampled location, or the zero vector for an empty array or non-finite input.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Sample Location Array", BlueprintThreadSafe), Category = "Directive Utilities|Math|Vector")
static FVector SampleLocationArray(const TArray<FVector>& Locations, float Alpha, bool bClosedLoop = false);
/** Creates one transform per location using a shared rotation and scale. */
UFUNCTION(BlueprintPure, meta = (DisplayName = "Locations To Transforms", BlueprintThreadSafe), Category = "Directive Utilities|Math|Transform")
static TArray<FTransform> LocationsToTransforms(const TArray<FVector>& Locations,
FRotator Rotation = FRotator(0.0, 0.0, 0.0), FVector Scale = FVector(1.0, 1.0, 1.0));
/**
* Creates one transform per location with its local X axis facing toward or away from a target.
* A location equal to Target uses Rotation Offset without a facing rotation.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Locations To Facing Transforms", BlueprintThreadSafe, AdvancedDisplay = "UpDirection,RotationOffset,Scale,bFaceAway"), Category = "Directive Utilities|Math|Transform")
static TArray<FTransform> LocationsToFacingTransforms(const TArray<FVector>& Locations,
FVector Target, FVector UpDirection = FVector(0.0, 0.0, 1.0),
FRotator RotationOffset = FRotator(0.0, 0.0, 0.0), FVector Scale = FVector(1.0, 1.0, 1.0),
bool bFaceAway = false);
/**
* Creates transforms from location, rotation, and scale arrays.
* Rotation and scale arrays may be empty, contain one value to broadcast, or match the location count.
* @returns True when the attribute-array lengths and values are valid.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Make Transforms From Arrays", AutoCreateRefTerm = "Rotations,Scales", BlueprintThreadSafe), Category = "Directive Utilities|Math|Transform")
static bool MakeTransformsFromArrays(const TArray<FVector>& Locations, const TArray<FRotator>& Rotations,
const TArray<FVector>& Scales, TArray<FTransform>& Transforms);
/**
* Samples a transform along the path through an array, with Alpha 0 at the first transform and 1 at the last.
* Progress is distance-weighted by location. Rotation takes the shortest path and scale interpolates linearly.
* A closed loop adds the segment from the last transform back to the first and wraps Alpha instead of clamping it.
* @returns The sampled transform, or the identity for an empty array or non-finite input.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Sample Transform Array", BlueprintThreadSafe), Category = "Directive Utilities|Math|Transform")
static FTransform SampleTransformArray(const TArray<FTransform>& Transforms, float Alpha, bool bClosedLoop = false);
/**
* Generates a rectangular grid on the local XY plane.
* @param Origin - The first point, or the grid center when Centered is true.
* @param Rotation - The grid plane rotation.
* @param Dimensions - The number of points along the local X and Y axes.
* @param Spacing - The signed center-to-center spacing along the local X and Y axes.
* @param bCentered - Whether to center the grid on Origin.
* @returns Points ordered by X, then Y, or an empty array for invalid input or an unsupported point count.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Grid Points 2D"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FVector> GenerateGridPoints2D(const FVector& Origin, const FRotator& Rotation,
FIntPoint Dimensions, const FVector2D& Spacing, bool bCentered = true);
/**
* Generates a rectangular 3D grid.
* @param Origin - The first point, or the grid center when Centered is true.
* @param Rotation - The grid rotation.
* @param Dimensions - The number of points along the local X, Y, and Z axes.
* @param Spacing - The signed center-to-center spacing along the local X, Y, and Z axes.
* @param bCentered - Whether to center the grid on Origin.
* @returns Points ordered by X, then Y, then Z, or an empty array for invalid input or an unsupported point count.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Grid Points 3D"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FVector> GenerateGridPoints3D(const FVector& Origin, const FRotator& Rotation,
FIntVector Dimensions, const FVector& Spacing, bool bCentered = true);
/**
* Generates transforms on a rectangular grid on the local XY plane.
* @param Origin - The first location, or the grid center when Centered is true.
* @param Rotation - The grid plane rotation.
* @param Dimensions - The number of points along the local X and Y axes.
* @param Spacing - The signed center-to-center spacing along the local X and Y axes.
* @param bCentered - Whether to center the grid on Origin.
* @param InstanceRotation - Shared rotation applied to every transform.
* @param Scale - Shared scale applied to every transform.
* @returns Transforms ordered by X, then Y, or an empty array for invalid input or an unsupported count.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Grid Transforms 2D", AdvancedDisplay = "InstanceRotation,Scale"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FTransform> GenerateGridTransforms2D(const FVector& Origin, const FRotator& Rotation,
FIntPoint Dimensions, const FVector2D& Spacing, bool bCentered = true,
FRotator InstanceRotation = FRotator(0.0, 0.0, 0.0), FVector Scale = FVector(1.0, 1.0, 1.0));
/**
* Generates transforms on a rectangular 3D grid.
* @param Origin - The first location, or the grid center when Centered is true.
* @param Rotation - The grid rotation.
* @param Dimensions - The number of points along the local X, Y, and Z axes.
* @param Spacing - The signed center-to-center spacing along the local X, Y, and Z axes.
* @param bCentered - Whether to center the grid on Origin.
* @param InstanceRotation - Shared rotation applied to every transform.
* @param Scale - Shared scale applied to every transform.
* @returns Transforms ordered by X, then Y, then Z, or an empty array for invalid input or an unsupported count.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Grid Transforms 3D", AdvancedDisplay = "InstanceRotation,Scale"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FTransform> GenerateGridTransforms3D(const FVector& Origin, const FRotator& Rotation,
FIntVector Dimensions, const FVector& Spacing, bool bCentered = true,
FRotator InstanceRotation = FRotator(0.0, 0.0, 0.0), FVector Scale = FVector(1.0, 1.0, 1.0));
/**
* Generates a rectangular hex grid on the rotated local XY plane.
* @param Origin - The first cell center, or the grid bounds center when Centered is true.
* @param Rotation - The grid plane rotation.
* @param Dimensions - The number of columns and rows.
* @param CellRadius - The distance from a cell center to a corner. Must be positive.
* @param Orientation - Whether the hex cells have pointy or flat tops.
* @param Gap - The signed edge-to-edge gap between adjacent cells. Negative values overlap cells.
* @param bCentered - Whether to center the grid bounds on Origin.
* @returns Points ordered by row, then column, or an empty array for invalid input or an unsupported point count.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Rectangular Hex Grid"), Category = "Directive Utilities|Math|Hex Grid")
static TArray<FVector> GenerateRectangularHexGrid(const FVector& Origin, const FRotator& Rotation,
FIntPoint Dimensions, double CellRadius,
EDirectiveUtilHexOrientation Orientation = EDirectiveUtilHexOrientation::PointyTop,
double Gap = 0.0, bool bCentered = true);
/**
* Generates transforms for a rectangular hex grid with a shared instance rotation and scale.
* Cell order matches Generate Rectangular Hex Grid.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Rectangular Hex Grid Transforms", AdvancedDisplay = "InstanceRotation,Scale"), Category = "Directive Utilities|Math|Hex Grid")
static TArray<FTransform> GenerateRectangularHexGridTransforms(const FVector& Origin, const FRotator& Rotation,
FIntPoint Dimensions, double CellRadius,
EDirectiveUtilHexOrientation Orientation = EDirectiveUtilHexOrientation::PointyTop,
double Gap = 0.0, bool bCentered = true,
FRotator InstanceRotation = FRotator(0.0, 0.0, 0.0), FVector Scale = FVector(1.0, 1.0, 1.0));
/**
* Returns the axial coordinate of every cell of a rectangular hex grid, in the same cell order as
* Generate Rectangular Hex Grid.
* @returns The coordinates, or an empty array for invalid input or an unsupported count.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Get Rectangular Hex Grid Coordinates"), Category = "Directive Utilities|Math|Hex Grid")
static TArray<FIntPoint> GetRectangularHexGridCoordinates(FIntPoint Dimensions,
EDirectiveUtilHexOrientation Orientation = EDirectiveUtilHexOrientation::PointyTop);
/**
* Generates a hexagon-shaped grid on the rotated local XY plane.
* @param Origin - The center cell location.
* @param Rotation - The grid plane rotation.
* @param GridRadius - The number of cell rings around the center cell.
* @param CellRadius - The distance from a cell center to a corner. Must be positive.
* @param Orientation - Whether the hex cells have pointy or flat tops.
* @param Gap - The signed edge-to-edge gap between adjacent cells. Negative values overlap cells.
* @returns Points ordered by axial R, then Q, or an empty array for invalid input or an unsupported point count.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Hexagonal Hex Grid"), Category = "Directive Utilities|Math|Hex Grid")
static TArray<FVector> GenerateHexagonalHexGrid(const FVector& Origin, const FRotator& Rotation,
int32 GridRadius, double CellRadius,
EDirectiveUtilHexOrientation Orientation = EDirectiveUtilHexOrientation::PointyTop,
double Gap = 0.0);
/**
* Generates transforms for a hexagon-shaped grid with a shared instance rotation and scale.
* Cell order matches Generate Hexagonal Hex Grid.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Hexagonal Hex Grid Transforms", AdvancedDisplay = "InstanceRotation,Scale"), Category = "Directive Utilities|Math|Hex Grid")
static TArray<FTransform> GenerateHexagonalHexGridTransforms(const FVector& Origin, const FRotator& Rotation,
int32 GridRadius, double CellRadius,
EDirectiveUtilHexOrientation Orientation = EDirectiveUtilHexOrientation::PointyTop,
double Gap = 0.0,
FRotator InstanceRotation = FRotator(0.0, 0.0, 0.0), FVector Scale = FVector(1.0, 1.0, 1.0));
/**
* Converts an axial hex coordinate to a location on the rotated local XY plane.
* @returns The cell center, or the zero vector for invalid layout input or coordinate overflow.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Hex Coordinate To Location", BlueprintThreadSafe), Category = "Directive Utilities|Math|Hex Grid")
static FVector HexCoordinateToLocation(FIntPoint Coordinate, const FVector& Origin, const FRotator& Rotation,
double CellRadius, EDirectiveUtilHexOrientation Orientation = EDirectiveUtilHexOrientation::PointyTop,
double Gap = 0.0);
/**
* Finds the axial coordinate of the nearest hex after projecting a location onto the rotated local XY plane.
* @returns The nearest axial coordinate, or (0, 0) for invalid layout input or an unrepresentable coordinate.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Location To Hex Coordinate", BlueprintThreadSafe), Category = "Directive Utilities|Math|Hex Grid")
static FIntPoint LocationToHexCoordinate(const FVector& Location, const FVector& Origin,
const FRotator& Rotation, double CellRadius,
EDirectiveUtilHexOrientation Orientation = EDirectiveUtilHexOrientation::PointyTop,
double Gap = 0.0);
/**
* Returns the six adjacent axial coordinates in a stable direction order.
* @returns Six neighbors, or an empty array when a neighbor would exceed the FIntPoint range.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Get Hex Neighbors", BlueprintThreadSafe), Category = "Directive Utilities|Math|Hex Grid")
static TArray<FIntPoint> GetHexNeighbors(FIntPoint Coordinate);
/** Returns the number of hex-grid steps between two axial coordinates. */
UFUNCTION(BlueprintPure, meta = (DisplayName = "Get Hex Distance", BlueprintThreadSafe), Category = "Directive Utilities|Math|Hex Grid")
static int64 GetHexDistance(FIntPoint A, FIntPoint B);
/**
* Returns every axial coordinate within a number of steps of a center cell, ordered by axial R, then Q.
* With a zero center the order matches the cells of Generate Hexagonal Hex Grid.
* @returns The coordinates, or an empty array for a negative range, coordinate overflow, or an unsupported count.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Get Hexes In Range"), Category = "Directive Utilities|Math|Hex Grid")
static TArray<FIntPoint> GetHexesInRange(FIntPoint Center, int32 Range);
/**
* Returns the axial coordinates exactly Radius steps from a center cell.
* Consecutive entries are adjacent and trace the ring once. A radius of zero returns the center.
* @returns The ring coordinates, or an empty array for a negative radius or coordinate overflow.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Get Hex Ring"), Category = "Directive Utilities|Math|Hex Grid")
static TArray<FIntPoint> GetHexRing(FIntPoint Center, int32 Radius);
/**
* Returns the axial coordinates along the straight line between two cells, including both endpoints.
* @returns The line coordinates, or an empty array for an unsupported length.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Get Hex Line"), Category = "Directive Utilities|Math|Hex Grid")
static TArray<FIntPoint> GetHexLine(FIntPoint Start, FIntPoint End);
/**
* Returns the six corner locations of a hex cell on the rotated local XY plane, ordered counter-clockwise.
* Corners lie at Cell Radius from the cell center; Gap only moves the center.
* @returns The corner locations, or an empty array for invalid layout input or coordinate overflow.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Get Hex Cell Corners", BlueprintThreadSafe), Category = "Directive Utilities|Math|Hex Grid")
static TArray<FVector> GetHexCellCorners(FIntPoint Coordinate, const FVector& Origin, const FRotator& Rotation,
double CellRadius, EDirectiveUtilHexOrientation Orientation = EDirectiveUtilHexOrientation::PointyTop,
double Gap = 0.0);
/**
* Generates points at a fixed spacing along a direction.
* @param Origin - The first point, or the formation center when Centered is true.
* @param Direction - The direction of travel. Its magnitude is ignored.
* @param Count - The number of points to generate.
* @param Spacing - The signed center-to-center distance between points.
* @param bCentered - Whether to center the formation on Origin.
* @returns The generated points, or an empty array for invalid input.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Points Along Direction"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FVector> GeneratePointsAlongDirection(const FVector& Origin, const FVector& Direction,
int32 Count, double Spacing, bool bCentered = false);
/**
* Generates evenly spaced points between two locations.
* @param Start - The start of the segment.
* @param End - The end of the segment.
* @param Count - The number of points to generate.
* @param bIncludeEndpoints - Whether the generated points include Start and End.
* @returns The generated points, or an empty array for invalid input.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Points Between Locations"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FVector> GeneratePointsBetweenLocations(const FVector& Start, const FVector& End,
int32 Count, bool bIncludeEndpoints = true);
/**
* Generates points at fixed distances along a spline.
* @param Spline - The spline to sample.
* @param Spacing - The distance between regular samples. Must be positive.
* @param bIncludeEndpoint - Whether to append the exact end of an open sampling range.
* @param SpacingMode - Fixed samples every Spacing units. Even shrinks the spacing so the samples divide the range evenly.
* @param CoordinateSpace - The space of the returned points.
* @param StartDistance - The distance where sampling starts. Clamped to the spline length.
* @param EndDistance - The distance where sampling ends. Negative means the end of the spline.
* @returns The generated points, or an empty array for invalid input or an unsupported point count.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Points Along Spline", AdvancedDisplay = "SpacingMode,CoordinateSpace,StartDistance,EndDistance"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FVector> GeneratePointsAlongSpline(const USplineComponent* Spline, double Spacing,
bool bIncludeEndpoint = true,
EDirectiveUtilSplineSpacingMode SpacingMode = EDirectiveUtilSplineSpacingMode::Fixed,
ESplineCoordinateSpace::Type CoordinateSpace = ESplineCoordinateSpace::World,
double StartDistance = 0.0, double EndDistance = -1.0);
/**
* Generates a fixed number of evenly spaced points along a spline.
* A closed loop spreads the points around the loop; a count of one on an open range returns its midpoint.
* @param Count - The number of points to generate.
* @param bIncludeEndpoints - Whether the points include both ends of an open sampling range.
* @param StartDistance - The distance where sampling starts. Clamped to the spline length.
* @param EndDistance - The distance where sampling ends. Negative means the end of the spline.
* @returns The generated points, or an empty array for invalid input.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Points Along Spline by Count", AdvancedDisplay = "StartDistance,EndDistance"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FVector> GeneratePointsAlongSplineByCount(const USplineComponent* Spline, int32 Count,
bool bIncludeEndpoints = true,
ESplineCoordinateSpace::Type CoordinateSpace = ESplineCoordinateSpace::World,
double StartDistance = 0.0, double EndDistance = -1.0);
/**
* Generates transforms at fixed distances along a spline.
* Rotation follows the spline tangent and roll. Scale can include the spline scale before applying Scale Multiplier.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Transforms Along Spline", AdvancedDisplay = "SpacingMode,CoordinateSpace,bUseSplineScale,RotationOffset,ScaleMultiplier,StartDistance,EndDistance"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FTransform> GenerateTransformsAlongSpline(const USplineComponent* Spline, double Spacing,
bool bIncludeEndpoint = true,
EDirectiveUtilSplineSpacingMode SpacingMode = EDirectiveUtilSplineSpacingMode::Fixed,
ESplineCoordinateSpace::Type CoordinateSpace = ESplineCoordinateSpace::World,
bool bUseSplineScale = true,
FRotator RotationOffset = FRotator(0.0, 0.0, 0.0), FVector ScaleMultiplier = FVector(1.0, 1.0, 1.0),
double StartDistance = 0.0, double EndDistance = -1.0);
/**
* Generates a fixed number of evenly spaced transforms along a spline.
* Rotation follows the spline tangent and roll. Scale can include the spline scale before applying Scale Multiplier.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Transforms Along Spline by Count", AdvancedDisplay = "bUseSplineScale,RotationOffset,ScaleMultiplier,StartDistance,EndDistance"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FTransform> GenerateTransformsAlongSplineByCount(const USplineComponent* Spline, int32 Count,
bool bIncludeEndpoints = true,
ESplineCoordinateSpace::Type CoordinateSpace = ESplineCoordinateSpace::World,
bool bUseSplineScale = true,
FRotator RotationOffset = FRotator(0.0, 0.0, 0.0), FVector ScaleMultiplier = FVector(1.0, 1.0, 1.0),
double StartDistance = 0.0, double EndDistance = -1.0);
/**
* Generates evenly spaced points around a circle on the rotated local XY plane.
* @returns The generated points without repeating the first point, or an empty array for invalid input.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Points On Circle"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FVector> GeneratePointsOnCircle(const FVector& Center, const FRotator& Rotation,
double Radius, int32 Count, double StartAngleDegrees = 0.0);
/** Generates transforms around a circle with fixed, radial, or path-relative orientation. */
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Transforms On Circle", AdvancedDisplay = "RotationOffset,Scale"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FTransform> GenerateTransformsOnCircle(const FVector& Center, const FRotator& Rotation,
double Radius, int32 Count, double StartAngleDegrees = 0.0,
EDirectiveUtilRadialOrientation Orientation = EDirectiveUtilRadialOrientation::FaceCenter,
FRotator RotationOffset = FRotator(0.0, 0.0, 0.0), FVector Scale = FVector(1.0, 1.0, 1.0));
/**
* Generates evenly spaced points along an arc on the rotated local XY plane.
* @param bIncludeEndpoint - Whether the final point lies at Start Angle plus Arc Angle.
* @returns The generated points, or an empty array for invalid input.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Points On Arc"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FVector> GeneratePointsOnArc(const FVector& Center, const FRotator& Rotation,
double Radius, int32 Count, double StartAngleDegrees = 0.0, double ArcAngleDegrees = 90.0,
bool bIncludeEndpoint = true);
/** Generates transforms along an arc with fixed, radial, or path-relative orientation. */
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Transforms On Arc", AdvancedDisplay = "RotationOffset,Scale"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FTransform> GenerateTransformsOnArc(const FVector& Center, const FRotator& Rotation,
double Radius, int32 Count, double StartAngleDegrees = 0.0, double ArcAngleDegrees = 90.0,
bool bIncludeEndpoint = true,
EDirectiveUtilRadialOrientation Orientation = EDirectiveUtilRadialOrientation::FaceCenter,
FRotator RotationOffset = FRotator(0.0, 0.0, 0.0), FVector Scale = FVector(1.0, 1.0, 1.0));
/**
* Generates a deterministic sunflower distribution across a disc on the rotated local XY plane.
* @returns Approximately even area coverage, or an empty array for invalid input.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Points On Disc"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FVector> GeneratePointsOnDisc(const FVector& Center, const FRotator& Rotation,
double Radius, int32 Count, double AngleOffsetDegrees = 0.0);
/**
* Generates a deterministic Fibonacci distribution across a sphere surface.
* @returns Approximately even surface coverage, or an empty array for invalid input.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Generate Points On Sphere"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FVector> GeneratePointsOnSphere(const FVector& Center, const FRotator& Rotation,
double Radius, int32 Count, double AngleOffsetDegrees = 0.0);
/**
* Offsets each location along a direction by Perlin noise sampled at that location.
* The offset varies smoothly between -Amplitude and Amplitude across the noise field.
* @param Locations - The locations to offset.
* @param NoiseScale - The world-space size of the noise features. Must be positive.
* @param Amplitude - The maximum offset distance along the direction.
* @param Direction - The offset direction. Its magnitude is ignored.
* @param NoiseOffset - World-space shift of the noise field, for varying the pattern between layers.
* @returns The offset locations, or an empty array for invalid input.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Offset Locations By Noise", BlueprintThreadSafe, AdvancedDisplay = "Direction,NoiseOffset"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FVector> OffsetLocationsByNoise(const TArray<FVector>& Locations, double NoiseScale,
double Amplitude, FVector Direction = FVector(0.0, 0.0, 1.0),
FVector NoiseOffset = FVector(0.0, 0.0, 0.0));
/**
* Offsets each transform location along a direction by Perlin noise sampled at that location.
* Rotation and scale are unchanged. Behaves like Offset Locations By Noise.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Offset Transforms By Noise", BlueprintThreadSafe, AdvancedDisplay = "Direction,NoiseOffset"), Category = "Directive Utilities|Math|Point Generation")
static TArray<FTransform> OffsetTransformsByNoise(const TArray<FTransform>& Transforms, double NoiseScale,
double Amplitude, FVector Direction = FVector(0.0, 0.0, 1.0),
FVector NoiseOffset = FVector(0.0, 0.0, 0.0));
/**
* Applies a Back/Elastic/Bounce easing curve to a normalized alpha.
* @note These are the Penner easing curves the engine's built-in "Ease" node (EEasingFunc) does not provide.
* For Sinusoidal/Exponential/Circular/power easings, use the engine's "Ease" node instead.
* @param Alpha - The input alpha. Clamped to the [0, 1] range.
* @param EaseType - The easing curve to apply.
* @returns The eased alpha. Note that Back and Elastic curves intentionally overshoot the [0, 1] range.
* @returns The eased alpha. Endpoints are exact. Back and Elastic curves intentionally overshoot the [0, 1] range between the endpoints.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Ease Alpha", BlueprintThreadSafe), Category = "Directive Utilities|Math|Easing")
static float EaseAlpha(float Alpha, EDirectiveUtilEaseType EaseType);
@@ -101,6 +592,39 @@ public:
UFUNCTION(BlueprintPure, meta = (DisplayName = "Ease (Color)", BlueprintThreadSafe), Category = "Directive Utilities|Math|Easing")
static FLinearColor EaseColor(const FLinearColor& A, const FLinearColor& B, float Alpha, EDirectiveUtilEaseType EaseType);
/**
* Eases a transform from A to B. Rotation takes the shortest path; location and scale interpolate linearly
* before the eased alpha is applied.
* @param A - The start transform (returned at Alpha 0).
* @param B - The target transform (returned at Alpha 1).
* @param Alpha - The input alpha. Clamped to the [0, 1] range.
* @param EaseType - The easing curve to apply.
* @returns The eased transform between A and B.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Ease (Transform)", BlueprintThreadSafe), Category = "Directive Utilities|Math|Easing")
static FTransform EaseTransform(const FTransform& A, const FTransform& B, float Alpha, EDirectiveUtilEaseType EaseType);
/**
* Eases each location in From toward the same index in To. Use with two generated layouts to blend formations.
* @param Alpha - The shared input alpha. Clamped to the [0, 1] range.
* @param PerElementAlphas - When non-empty, one alpha per element replaces Alpha for staggered blends.
* @returns The eased locations, or an empty array for mismatched lengths or non-finite input.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Ease Location Arrays", AutoCreateRefTerm = "PerElementAlphas", BlueprintThreadSafe, AdvancedDisplay = "PerElementAlphas"), Category = "Directive Utilities|Math|Easing")
static TArray<FVector> EaseLocationArrays(const TArray<FVector>& From, const TArray<FVector>& To,
float Alpha, EDirectiveUtilEaseType EaseType, const TArray<float>& PerElementAlphas);
/**
* Eases each transform in From toward the same index in To. Use with two generated layouts to blend formations.
* Rotation takes the shortest path; location and scale interpolate linearly before the eased alpha is applied.
* @param Alpha - The shared input alpha. Clamped to the [0, 1] range.
* @param PerElementAlphas - When non-empty, one alpha per element replaces Alpha for staggered blends.
* @returns The eased transforms, or an empty array for mismatched lengths or non-finite input.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Ease Transform Arrays", AutoCreateRefTerm = "PerElementAlphas", BlueprintThreadSafe, AdvancedDisplay = "PerElementAlphas"), Category = "Directive Utilities|Math|Easing")
static TArray<FTransform> EaseTransformArrays(const TArray<FTransform>& From, const TArray<FTransform>& To,
float Alpha, EDirectiveUtilEaseType EaseType, const TArray<float>& PerElementAlphas);
/**
* Rounds a float to a given number of decimal places. Rounds half away from zero,
* matching "Round To Decimals (Text)".
@@ -138,7 +662,7 @@ public:
* Formats a duration in seconds as d/h/m/s units from the largest nonzero unit down, with
* two-digit padding after the first ("1h 03m 05s", "2d 04h", "45s"). With bIncludeSeconds
* false the seconds unit is dropped and sub-minute durations return "0m". Negative input gets
* a leading minus sign; non-finite input returns "0s". Output is English-only.
* a leading minus sign when a nonzero unit remains; non-finite input returns "0s". Output is English-only.
* @param Seconds - The duration in seconds.
* @param bIncludeSeconds - Whether to include the seconds unit.
* @returns The formatted duration text.
@@ -224,9 +748,59 @@ public:
UFUNCTION(BlueprintPure, meta = (BlueprintThreadSafe), Category = "Directive Utilities|Math|Array")
static float GetFloatArrayStandardDeviation(const TArray<float>& Values);
/**
* Calculates the circular mean of an angle array in degrees.
* @returns False for an empty array, non-finite input, or an undefined or numerically indeterminate circular mean.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Get Angle Array Average", BlueprintThreadSafe), Category = "Directive Utilities|Math|Array")
static bool GetAngleArrayAverage(const TArray<float>& Angles, float& AverageAngle, float& ResultantStrength);
/**
* Calculates the weighted average of a float array.
* @returns False when the arrays differ in size, contain invalid values, or have no positive weight.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Get Weighted Float Array Average", BlueprintThreadSafe), Category = "Directive Utilities|Math|Array")
static bool GetWeightedFloatArrayAverage(const TArray<float>& Values, const TArray<float>& Weights, float& Average);
/**
* Calculates the weighted average of a vector array.
* @returns False when the arrays differ in size, contain invalid values, or have no positive weight.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Get Weighted Vector Array Average", BlueprintThreadSafe), Category = "Directive Utilities|Math|Array")
static bool GetWeightedVectorArrayAverage(const TArray<FVector>& Values, const TArray<float>& Weights, FVector& Average);
/**
* Normalizes a float array to an output range.
* @returns False for an empty array or non-finite input.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Normalize Float Array To Range", BlueprintThreadSafe), Category = "Directive Utilities|Math|Array")
static bool NormalizeFloatArrayToRange(const TArray<float>& Values, float OutputMinimum, float OutputMaximum,
TArray<float>& NormalizedValues);
/**
* Normalizes positive weights so their sum is one. Negative and non-finite weights are treated as zero.
* @returns False for an empty array or when no positive weight remains.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Normalize Weights", BlueprintThreadSafe), Category = "Directive Utilities|Math|Array")
static bool NormalizeWeights(const TArray<float>& Weights, TArray<float>& NormalizedWeights);
/**
* Calculates a percentile using the Type 7 linear method without modifying the input array.
* @returns False for an empty array or non-finite input.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Get Float Array Percentile", BlueprintThreadSafe), Category = "Directive Utilities|Math|Array")
static bool GetFloatArrayPercentile(const TArray<float>& Values, float Percentile, float& Value);
/**
* Calculates the root mean square of a float array.
* @returns False for an empty array or non-finite input.
*/
UFUNCTION(BlueprintPure, meta = (DisplayName = "Get Float Array Root Mean Square", BlueprintThreadSafe), Category = "Directive Utilities|Math|Array")
static bool GetFloatArrayRootMeanSquare(const TArray<float>& Values, float& RootMeanSquare);
/**
* Returns a random index into the Weights array, where each index's probability is proportional to its weight.
* Useful for loot tables and weighted spawning. Negative weights are treated as zero.
* Useful for loot tables and weighted spawning. Negative and non-finite weights are treated as zero.
* @param Weights - The per-index weights.
* @returns The selected index, or INDEX_NONE (-1) if the array is empty or all weights are zero.
*/
@@ -236,9 +810,33 @@ public:
/**
* Deterministic version of Get Random Index From Weights that draws from (and advances) the provided random stream.
* @param Stream - The random stream to draw from.
* @param Weights - The per-index weights. Negative weights are treated as zero.
* @param Weights - The per-index weights. Negative and non-finite weights are treated as zero.
* @returns The selected index, or INDEX_NONE (-1) if the array is empty or all weights are zero.
*/
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Get Random Index From Weights (Stream)"), Category = "Directive Utilities|Math|Random")
static int32 GetRandomIndexFromWeightsFromStream(UPARAM(ref) FRandomStream& Stream, const TArray<float>& Weights);
/** Returns a uniformly distributed random point inside a circle. */
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Random Point In Circle"), Category = "Directive Utilities|Math|Random")
static FVector2D RandomPointInCircle(float Radius);
/** Returns a deterministic uniformly distributed random point inside a circle. Invalid or zero radii do not advance the stream. */
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Random Point In Circle (Stream)"), Category = "Directive Utilities|Math|Random")
static FVector2D RandomPointInCircleFromStream(UPARAM(ref) FRandomStream& Stream, float Radius);
/** Returns a uniformly distributed random point inside a 2D annulus. */
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Random Point In Annulus"), Category = "Directive Utilities|Math|Random")
static FVector2D RandomPointInAnnulus(float InnerRadius, float OuterRadius);
/** Returns a deterministic uniformly distributed random point inside a 2D annulus. Invalid or zero radii do not advance the stream. */
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Random Point In Annulus (Stream)"), Category = "Directive Utilities|Math|Random")
static FVector2D RandomPointInAnnulusFromStream(UPARAM(ref) FRandomStream& Stream, float InnerRadius, float OuterRadius);
/** Returns a uniformly distributed random point inside a sphere. */
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Random Point In Sphere"), Category = "Directive Utilities|Math|Random")
static FVector RandomPointInSphere(float Radius);
/** Returns a deterministic uniformly distributed random point inside a sphere. Invalid or zero radii do not advance the stream. */
UFUNCTION(BlueprintCallable, meta = (DisplayName = "Random Point In Sphere (Stream)"), Category = "Directive Utilities|Math|Random")
static FVector RandomPointInSphereFromStream(UPARAM(ref) FRandomStream& Stream, float Radius);
};

15
Plugins/DirectiveUtilities/Source/DirectiveUtilitiesRuntime/Public/Libraries/DirectiveUtilSaveGameFunctionLibrary.h
View File

@@ -13,6 +13,7 @@ class USaveGame;
* Save-slot utilities that fill the gaps left by UGameplayStatics: enumerating slots, reading slot
* timestamps, and serializing a save object to/from an in-memory byte array. This is slot/IO QoL only,
* not a save framework: use the engine's SaveGameToSlot/LoadGameFromSlot for the actual slot I/O.
* Slot operations accept flat file names so they behave consistently across platform save backends.
*/
UCLASS()
class DIRECTIVEUTILITIESRUNTIME_API UDirectiveUtilSaveGameFunctionLibrary : public UBlueprintFunctionLibrary
@@ -22,9 +23,10 @@ class DIRECTIVEUTILITIESRUNTIME_API UDirectiveUtilSaveGameFunctionLibrary : publ
public:
/**
* Returns the names of all existing save slots in the project's default save directory.
* @note This enumerates the engine's default file-based save directory (Saved/SaveGames); it does not
* cover platform-specific save systems (e.g. console storage).
* Returns the names of all existing save slots known to the engine save game system.
* Uses ISaveGameSystem::GetSaveGameNames so the result matches DoesSaveSlotExist /
* DeleteSaveSlot / RenameSaveSlot. Falls back to the default Saved/SaveGames directory
* only when the active backend cannot enumerate slots.
* @returns The save slot names (without extension).
*/
UFUNCTION(BlueprintCallable, Category = "Directive Utilities|SaveGame")
@@ -34,7 +36,7 @@ public:
* Returns the last-modified timestamp of a save slot, if it exists.
* @param SlotName - The save slot name.
* @param OutTimestamp - [out] The slot's last-modified time (local), or a default time if it does not exist.
* Converted from the file system's UTC timestamp to local time.
* Converted from the file system's UTC timestamp using the timezone rules for that instant.
* @returns True if the slot exists.
*/
UFUNCTION(BlueprintCallable, Category = "Directive Utilities|SaveGame")
@@ -81,8 +83,9 @@ public:
/**
* Renames a save slot by copying its data to the new name and then deleting the original.
* Fails without mutating anything unless both names are valid, the names differ, the old slot
* exists, and the new slot does not. On failure the original slot is never lost. Goes through
* the engine's save game system, so unlike enumeration it also works on platform save backends.
* exists, and the new slot does not. Case-only renames (Slot -> slot) rewrite the existing
* slot instead of reporting a collision. On failure the original slot is never lost. Goes through
* the engine's save game system so it stays consistent with DoesSaveSlotExist and GetAllSaveSlotNames.
* @param OldSlotName - The existing save slot name.
* @param NewSlotName - The new save slot name.
* @param UserIndex - The platform user index the save belongs to.

6
Plugins/DirectiveUtilities/Source/DirectiveUtilitiesRuntime/Public/Libraries/DirectiveUtilStringFunctionLibrary.h
View File

@@ -305,7 +305,8 @@ public:
/**
* Checks whether the string is safe to use as a bare file name: not empty, no path
* separators or relative segments, and no characters invalid in file names.
* separators or relative segments, no characters invalid in file names, no trailing
* dot or space, and not a reserved device name (CON, PRN, AUX, NUL, COM1-9, LPT1-9).
* @param String - The string to check.
* @returns True if the string is a valid bare file name.
*/
@@ -314,7 +315,8 @@ public:
/**
* Returns the string with path separators and characters invalid in file names removed
* (or replaced when a replacement character is provided). May return an empty string.
* (or replaced when a replacement character is provided). Trailing dots and spaces are
* stripped. Reserved device names are prefixed with an underscore. May return an empty string.
* @param String - The string to sanitize.
* @param Replacement - Optional single-character replacement for stripped characters.
* @returns The sanitized file name.

2
Plugins/DirectiveUtilities/Source/DirectiveUtilitiesRuntime/Public/Libraries/DirectiveUtilTextFunctionLibrary.h
View File

@@ -21,6 +21,6 @@ public:
* Returns true if the provided text is not empty.
* @param Text - The text to check.
*/
UFUNCTION(BlueprintPure, Category = "Directive Utilities|Text" )
UFUNCTION(BlueprintPure, meta = (AutoCreateRefTerm = "Text"), Category = "Directive Utilities|Text")
static bool IsNotEmpty(const FText& Text);
};