vault backup: 2024-10-12 17:19:45

2024-10-12 17:19:46 +08:00
parent ff94ddca61
commit 244c0c52f6
960 changed files with 31348 additions and 10 deletions
--- a/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/CppFromBpEvent.md
+++ b/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/CppFromBpEvent.md
@@ -0,0 +1,25 @@
+# CppFromBpEvent
+
+- **使用位置：** Todo
+- **引擎模块：** UHT
+- **元数据类型：** bool
+- **常用程度：** 0
+
+指定这是个在C++中定义的蓝图事件。
+
+早期的UHT会使用这个元数据，不过现在的引擎版本已经不用这个了。
+
+## 原理代码：
+
+```cpp
+public static class UhtFunctionParser
+{
+	private static UhtParseResult ParseUFunction(UhtParsingScope parentScope, UhtToken token)
+	{
+		if (function.MetaData.ContainsKey(UhtNames.CppFromBpEvent))
+		{
+						function.FunctionFlags |= EFunctionFlags.Event;
+		}
+	}
+}
+```
--- a/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/CustomThunk.md
+++ b/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/CustomThunk.md
@@ -0,0 +1,15 @@
+# CustomThunk
+
+- **功能描述：** 指定UHT不为该函数生成蓝图调用的辅助函数，而需要用户自定义编写。
+
+- **使用位置：** UFUNCTION
+
+- **引擎模块：** UHT
+
+- **元数据类型：** bool
+
+- **关联项：** 
+
+  UFUNCTION：[ServiceRequest](../../Specifier/UFUNCTION/Network/ServiceRequest.md), [CustomThunk](../../Specifier/UFUNCTION/UHT/CustomThunk/CustomThunk.md)
+
+- **常用程度：** ★★★★★
--- a/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/DocumentationPolicy.md
+++ b/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/DocumentationPolicy.md
@@ -0,0 +1,149 @@
+# DocumentationPolicy
+
+- **功能描述：** 指定文档验证的规则，当前只能设为Strict
+- **使用位置：** Any
+- **引擎模块：** UHT
+- **元数据类型：** string="abc"
+- **常用程度：** ★
+
+在UHT的ValidateDocumentationPolicy函数里，会发现这个值主要是用来判断类型或字段上是否有提供Comment或Tooltip，或者Float变量是否配了对应的“UIMin / UIMax”，以便提取出来这些信息生成对应的文档。
+
+当前只有一个配置是Strict，里面默认是开启了所有的检查。所有可以理解为在C++源码里配置上DocumentationPolicy=Strict，就意味着想要引擎来检查文档配置。
+
+```cpp
+_documentationPolicies["Strict"] = new()
+{
+	ClassOrStructCommentRequired = true,
+	FunctionToolTipsRequired = true,
+	MemberToolTipsRequired = true,
+	ParameterToolTipsRequired = true,
+	FloatRangesRequired = true,
+};
+
+protected override void ValidateDocumentationPolicy(UhtDocumentationPolicy policy)
+	{
+		if (policy.ClassOrStructCommentRequired)
+		{
+			string classTooltip = MetaData.GetValueOrDefault(UhtNames.ToolTip);
+			if (classTooltip.Length == 0 || classTooltip.Equals(EngineName, StringComparison.OrdinalIgnoreCase))
+			{
+				this.LogError($"{EngineType.CapitalizedText()} '{SourceName}' does not provide a tooltip / comment (DocumentationPolicy).");
+			}
+		}
+//。。。
+}
+```
+
+## 源码中的类似例子：
+
+```cpp
+USTRUCT(meta=(DisplayName="Set Transform", Category="Transforms", TemplateName = "Set Transform", DocumentationPolicy = "Strict", Keywords="SetBoneTransform,SetControlTransform,SetInitialTransform,SetSpaceTransform", NodeColor="0, 0.364706, 1.0", Varying))
+struct CONTROLRIG_API FRigUnit_SetTransform : public FRigUnitMutable
+{
+}
+```
+
+## 自己的测试代码：
+
+```cpp
+UCLASS(BlueprintType, meta = (DocumentationPolicy=Strict))
+class INSIDER_API UMyClass_DocumentationPolicy :public UObject
+{
+	GENERATED_BODY()
+public:
+	UPROPERTY(BlueprintReadWrite, EditAnywhere)
+	float MyFloat;
+	UPROPERTY(BlueprintReadWrite, EditAnywhere)
+	FString MyString;
+
+	//This is a float
+	UPROPERTY(BlueprintReadWrite, EditAnywhere, meta = (UIMin = "0.0", UIMax = "100.0"))
+	float MyFloat_WithValidate;
+
+	
+	UFUNCTION(meta = (DocumentationPolicy=Strict))
+	void MyFunc(){}
+
+	/**
+	 *	Test Func for validate param
+	 * 	@param keyOtherName The name of Key
+	 *	@param keyValue
+	 */
+	UFUNCTION(BlueprintCallable, meta = (DocumentationPolicy=Strict))
+		int MyFunc_ValidateParamFailed(FString keyName,int keyValue){return 0;}//必须至少有一个@param才会开启参数注释的验证
+
+	/**
+	 *	Test Func for validate param
+	 *
+	 *	@param keyName The name of key
+	 *	@param keyValue The value of key
+	 *	@return Return operation result
+	 */
+	UFUNCTION(meta = (DocumentationPolicy=Strict))
+	int MyFunc_ValidateParam(FString keyName,int keyValue){return 0;}
+};
+
+USTRUCT(BlueprintType, meta = (DocumentationPolicy=Strict))
+struct INSIDER_API FMyStruct_DocumentationPolicy 
+{
+	GENERATED_BODY()
+public:
+	UPROPERTY(BlueprintReadWrite, EditAnywhere)
+	float MyFloat;
+	UPROPERTY(BlueprintReadWrite, EditAnywhere)
+	FString MyString;
+};
+
+UENUM(BlueprintType, meta = (DocumentationPolicy=Strict))
+enum class EMyEnum_DocumentationPolicy :uint8
+{
+	First,
+	Second,
+	Third,
+};
+
+// This a tooltip / comment
+UCLASS(BlueprintType, meta = (DocumentationPolicy = Strict))
+class INSIDER_API UMyClass_DocumentationPolicy_TypeA :public UObject
+{
+	GENERATED_BODY()
+};
+
+/**
+*	This a tooltip / comment
+*
+*/
+UCLASS(BlueprintType, meta = (DocumentationPolicy = Strict))
+class INSIDER_API UMyClass_DocumentationPolicy_TypeB :public UObject
+{
+	GENERATED_BODY()
+};
+
+UCLASS(BlueprintType, meta = (DocumentationPolicy = Strict,ToolTip="This a tooltip"))	//Cannot use ShortToolTip
+class INSIDER_API UMyClass_DocumentationPolicy_TypeC :public UObject
+{
+	GENERATED_BODY()
+};
+```
+
+## 产生的UHT编译报错：
+
+```cpp
+error : Class 'UMyClass_DocumentationPolicy' does not provide a tooltip / comment(DocumentationPolicy).
+error : Property 'UMyClass_DocumentationPolicy::MyFloat' does not provide a tooltip / comment(DocumentationPolicy).
+error : Property 'UMyClass_DocumentationPolicy::MyString' does not provide a tooltip / comment(DocumentationPolicy).
+error : Property 'UMyClass_DocumentationPolicy::MyFloat' does not provide a valid UIMin / UIMax(DocumentationPolicy).
+error : Function 'UMyClass_DocumentationPolicy::MyFunc' does not provide a tooltip / comment(DocumentationPolicy).
+error : Function 'UMyClass_DocumentationPolicy::MyFunc' does not provide a comment(DocumentationPolicy).
+error : Function 'UMyClass_DocumentationPolicy::MyFunc_ValidateParamFailed' doesn't provide a tooltip for parameter 'keyName' (DocumentationPolicy).
+error : Function 'UMyClass_DocumentationPolicy::MyFunc_ValidateParamFailed' doesn't provide a tooltip for parameter 'keyValue' (DocumentationPolicy).
+error : Function 'UMyClass_DocumentationPolicy::MyFunc_ValidateParamFailed' provides a tooltip for an unknown parameter 'keyOtherName'
+error : Struct 'FMyStruct_DocumentationPolicy' does not provide a tooltip / comment(DocumentationPolicy).
+error : Property 'FMyStruct_DocumentationPolicy::MyFloat' does not provide a tooltip / comment(DocumentationPolicy).
+error : Property 'FMyStruct_DocumentationPolicy::MyString' does not provide a tooltip / comment(DocumentationPolicy).
+error : Property 'FMyStruct_DocumentationPolicy::MyFloat' does not provide a valid UIMin / UIMax(DocumentationPolicy).
+error : Enum 'EMyEnum_DocumentationPolicy' does not provide a tooltip / comment(DocumentationPolicy)
+error : Enum entry 'EMyEnum_DocumentationPolicy::EMyEnum_DocumentationPolicy::First' does not provide a tooltip / comment(DocumentationPolicy)
+error : Enum entry 'EMyEnum_DocumentationPolicy::EMyEnum_DocumentationPolicy::Second' does not provide a tooltip / comment(DocumentationPolicy)
+error: Enum entry 'EMyEnum_DocumentationPolicy::EMyEnum_DocumentationPolicy::Third' does not provide a tooltip / comment(DocumentationPolicy)
+```
--- a/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/FieldNotifyInterfaceParam/FieldNotifyInterfaceParam.md
+++ b/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/FieldNotifyInterfaceParam/FieldNotifyInterfaceParam.md
@@ -0,0 +1,53 @@
+# FieldNotifyInterfaceParam
+
+- **功能描述：** 指定函数的某个参数提供FieldNotify的ViewModel信息。
+- **使用位置：** UFUNCTION
+- **引擎模块：** FieldNotify
+- **元数据类型：** string="abc"
+- **限制类型：** 函数里有其他FFieldNotificationId 参数
+- **常用程度：** ★★★
+
+指定函数的某个参数提供FieldNotify的ViewModel信息。
+
+该参数为之后的FFieldNotificationId参数的提供上下文信息，这样FieldId的选项框才知道有哪些可选值。
+
+## 源码例子：
+
+```cpp
+	/** Broadcast that the Field value changed. */
+	UFUNCTION(BlueprintCallable, Category = "FieldNotification", meta = (FieldNotifyInterfaceParam="Object", DisplayName = "Broadcast Field Value Changed"))
+	static void BroadcastFieldValueChanged(UObject* Object, FFieldNotificationId FieldId);
+
+```
+
+## 蓝图效果：
+
+在UserWidget里测试，可见没有连接到参数的Target默认为当前的UserWidget，则FieldId是3个值。而连接到我们自定义的ViewModel后，则改变为我们下面定义的值。
+
+![Untitled](Untitled.png)
+
+## 原理：
+
+```cpp
+TSharedRef<SWidget> SFieldNotificationGraphPin::GetDefaultValueWidget()
+{
+	UEdGraphPin* SelfPin = GraphPinObj->GetOwningNode()->FindPin(UEdGraphSchema_K2::PSC_Self);
+	if (UK2Node_CallFunction* CallFunction = Cast<UK2Node_CallFunction>(GraphPinObj->GetOwningNode()))
+	{
+		if (UFunction* Function = CallFunction->GetTargetFunction())
+		{
+			const FString& PinName = Function->GetMetaData("FieldNotifyInterfaceParam");
+			if (PinName.Len() != 0)
+			{
+				SelfPin = GraphPinObj->GetOwningNode()->FindPin(*PinName);
+			}
+		}
+	}
+
+	return SNew(SFieldNotificationPicker)
+		.Value(this, &SFieldNotificationGraphPin::GetValue)
+		.OnValueChanged(this, &SFieldNotificationGraphPin::SetValue)
+		.FromClass_Static(Private::GetPinClass, SelfPin)
+		.Visibility(this, &SGraphPin::GetDefaultValueVisibility);
+}
+```
--- a/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/FieldNotifyInterfaceParam/Untitled.png
+++ b/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/FieldNotifyInterfaceParam/Untitled.png
--- a/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/IncludePath.md
+++ b/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/IncludePath.md
@@ -0,0 +1,92 @@
+# IncludePath
+
+- **功能描述：** 记录UClass的引用路径
+- **使用位置：** UCLASS
+- **引擎模块：** UHT
+- **元数据类型：** string="abc"
+- **限制类型：** UCLASS上的信息
+- **常用程度：** 0
+
+记录UClass的引用路径。
+
+开发者一般也不用管这个值。
+
+有一个作用是在UHT生成.gen.cpp的时候，在头文件部分方便引用到该类的头文件。
+
+## 测试代码：
+
+```cpp
+UCLASS(BlueprintType)
+class INSIDER_API UMyProperty_Template :public UObject
+{
+	GENERATED_BODY()
+public:
+	UFUNCTION(BlueprintCallable)
+	int32 MyFunc(FString str){return 0;}
+	UPROPERTY(EditAnywhere, BlueprintReadWrite)
+	int32 MyProperty = 123;
+};
+```
+
+## 其类型信息：
+
+```cpp
+[class MyProperty_Template	Class->Struct->Field->Object	/Script/Insider.MyProperty_Template]
+(BlueprintType = true, IncludePath = Property/MyProperty_Template.h, ModuleRelativePath = Property/MyProperty_Template.h)
+	ObjectFlags:	RF_Public | RF_Standalone | RF_Transient 
+	Outer:	Package /Script/Insider
+	ClassHierarchy:	MyProperty_Template:Object
+	ClassFlags:	CLASS_MatchedSerializers | CLASS_Native | CLASS_RequiredAPI | CLASS_TokenStreamAssembled | CLASS_Intrinsic | CLASS_Constructed 
+	Size:	56
+	Within:	Object
+	ClassConfigName:	Engine
+{
+	(Category = MyProperty_Template, ModuleRelativePath = Property/MyProperty_Template.h)
+	48-[4] int32 MyProperty;
+		PropertyFlags:	CPF_Edit | CPF_BlueprintVisible | CPF_ZeroConstructor | CPF_IsPlainOldData | CPF_NoDestructor | CPF_HasGetValueTypeHash | CPF_NativeAccessSpecifierPublic 
+		ObjectFlags:	RF_Public | RF_MarkAsNative | RF_Transient 
+		Outer:	Class /Script/Insider.MyProperty_Template
+		Path:	IntProperty /Script/Insider.MyProperty_Template:MyProperty
+	[func MyFunc	Function->Struct->Field->Object	/Script/Insider.MyProperty_Template:MyFunc]
+	(ModuleRelativePath = Property/MyProperty_Template.h)
+		ObjectFlags:	RF_Public | RF_Transient 
+		Outer:	Class /Script/Insider.MyProperty_Template
+		FunctionFlags:	FUNC_Final | FUNC_Native | FUNC_Public | FUNC_BlueprintCallable 
+		NumParms:	2
+		ParmsSize:	20
+		ReturnValueOffset:	16
+		RPCId:	0
+		RPCResponseId:	0
+		public int32 MyFunc(FString str)final;
+	{
+		0-[16] FString str;
+			PropertyFlags:	CPF_Parm | CPF_ZeroConstructor | CPF_HasGetValueTypeHash | CPF_NativeAccessSpecifierPublic 
+			ObjectFlags:	RF_Public | RF_MarkAsNative | RF_Transient 
+			Outer:	Function /Script/Insider.MyProperty_Template:MyFunc
+			Path:	StrProperty /Script/Insider.MyProperty_Template:MyFunc:str
+		16-[4] int32 ReturnValue;
+			PropertyFlags:	CPF_Parm | CPF_OutParm | CPF_ZeroConstructor | CPF_ReturnParm | CPF_IsPlainOldData | CPF_NoDestructor | CPF_HasGetValueTypeHash | CPF_NativeAccessSpecifierPublic 
+			ObjectFlags:	RF_Public | RF_MarkAsNative | RF_Transient 
+			Outer:	Function /Script/Insider.MyProperty_Template:MyFunc
+			Path:	IntProperty /Script/Insider.MyProperty_Template:MyFunc:ReturnValue
+	};
+};
+```
+
+## 原理：
+
+同样也是在UHT中分析后添加的。具体的逻辑值请见ModuleRelativePath中的原理代码部分。
+
+```cpp
+protected override void UhtClass::ResolveSuper(UhtResolvePhase resolvePhase)
+{
+	switch (ClassType)
+	{
+				case UhtClassType.Class:
+					{
+							MetaData.Add(UhtNames.IncludePath, HeaderFile.IncludeFilePath);
+					}
+	}
+}
+
+```
--- a/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/ModuleRelativePath.md
+++ b/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/ModuleRelativePath.md
@@ -0,0 +1,130 @@
+# ModuleRelativePath
+
+- **功能描述：** 记录类型定义的的头文件路径，为其处于模块的内部相对路径。
+- **使用位置：** Any
+- **引擎模块：** UHT
+- **元数据类型：** string="abc"
+- **常用程度：** 0
+
+记录当前元类型定义的的头文件路径，为相对模块的相对路径。
+
+对于开发者来说一般不用管，但是引擎编辑器会用它来定位某个类型是在哪个.h里定义的，从而在你双击类型的时候，可以为你在VS里打开相应的头文件。具体的逻辑可以去FSourceCodeNavigation里查看。
+
+和IncludePath的区别是，ModuleRelativePath 在各种类型信息上都有，而IncludePath只用于UCLASS上。另外ModuleRelativePath 的值可以包含“Classes/Public/Internal/Private”这4个以开头，我们一般也确实会建议把.h.cpp划分到这4个文件夹里。而IncludeFilePath 的值就会去掉这个头。
+
+## 测试代码：
+
+```cpp
+UCLASS(BlueprintType)
+class INSIDER_API UMyProperty_Template :public UObject
+{
+	GENERATED_BODY()
+public:
+	UFUNCTION(BlueprintCallable)
+	int32 MyFunc(FString str){return 0;}
+	UPROPERTY(EditAnywhere, BlueprintReadWrite)
+	int32 MyProperty = 123;
+};
+```
+
+## 其元类型信息打印：
+
+可以发现ModuleRelativePath 在类，属性和函数上都有该信息。
+
+而IncludePath只有在UCLASS上才有。
+
+```cpp
+[class MyProperty_Template	Class->Struct->Field->Object	/Script/Insider.MyProperty_Template]
+(BlueprintType = true, IncludePath = Property/MyProperty_Template.h, ModuleRelativePath = Property/MyProperty_Template.h)
+	ObjectFlags:	RF_Public | RF_Standalone | RF_Transient 
+	Outer:	Package /Script/Insider
+	ClassHierarchy:	MyProperty_Template:Object
+	ClassFlags:	CLASS_MatchedSerializers | CLASS_Native | CLASS_RequiredAPI | CLASS_TokenStreamAssembled | CLASS_Intrinsic | CLASS_Constructed 
+	Size:	56
+	Within:	Object
+	ClassConfigName:	Engine
+{
+	(Category = MyProperty_Template, ModuleRelativePath = Property/MyProperty_Template.h)
+	48-[4] int32 MyProperty;
+		PropertyFlags:	CPF_Edit | CPF_BlueprintVisible | CPF_ZeroConstructor | CPF_IsPlainOldData | CPF_NoDestructor | CPF_HasGetValueTypeHash | CPF_NativeAccessSpecifierPublic 
+		ObjectFlags:	RF_Public | RF_MarkAsNative | RF_Transient 
+		Outer:	Class /Script/Insider.MyProperty_Template
+		Path:	IntProperty /Script/Insider.MyProperty_Template:MyProperty
+	[func MyFunc	Function->Struct->Field->Object	/Script/Insider.MyProperty_Template:MyFunc]
+	(ModuleRelativePath = Property/MyProperty_Template.h)
+		ObjectFlags:	RF_Public | RF_Transient 
+		Outer:	Class /Script/Insider.MyProperty_Template
+		FunctionFlags:	FUNC_Final | FUNC_Native | FUNC_Public | FUNC_BlueprintCallable 
+		NumParms:	2
+		ParmsSize:	20
+		ReturnValueOffset:	16
+		RPCId:	0
+		RPCResponseId:	0
+		public int32 MyFunc(FString str)final;
+	{
+		0-[16] FString str;
+			PropertyFlags:	CPF_Parm | CPF_ZeroConstructor | CPF_HasGetValueTypeHash | CPF_NativeAccessSpecifierPublic 
+			ObjectFlags:	RF_Public | RF_MarkAsNative | RF_Transient 
+			Outer:	Function /Script/Insider.MyProperty_Template:MyFunc
+			Path:	StrProperty /Script/Insider.MyProperty_Template:MyFunc:str
+		16-[4] int32 ReturnValue;
+			PropertyFlags:	CPF_Parm | CPF_OutParm | CPF_ZeroConstructor | CPF_ReturnParm | CPF_IsPlainOldData | CPF_NoDestructor | CPF_HasGetValueTypeHash | CPF_NativeAccessSpecifierPublic 
+			ObjectFlags:	RF_Public | RF_MarkAsNative | RF_Transient 
+			Outer:	Function /Script/Insider.MyProperty_Template:MyFunc
+			Path:	IntProperty /Script/Insider.MyProperty_Template:MyFunc:ReturnValue
+	};
+};
+
+```
+
+## 原理：
+
+在UHT分析的时候，自动的为类型加上头文件的路径信息。
+
+从源码逻辑可以看出，ModuleRelativePath 的值可以包含“Classes/Public/Internal/Private”这4个以开头，我们一般也确实会建议把.h.cpp划分到这4个文件夹里。而IncludeFilePath 的值就会去掉这个头。
+
+```cpp
+
+public enum UhtHeaderFileType
+{
+
+	/// <summary>
+	/// Classes folder
+	/// </summary>
+	Classes,
+
+	/// <summary>
+	/// Public folder
+	/// </summary>
+	Public,
+
+	/// <summary>
+	/// Internal folder
+	/// </summary>
+	Internal,
+
+	/// <summary>
+	/// Private folder
+	/// </summary>
+	Private,
+}
+
+public static void AddModuleRelativePathToMetaData(UhtMetaData metaData, UhtHeaderFile headerFile)
+{
+	metaData.Add(UhtNames.ModuleRelativePath, headerFile.ModuleRelativeFilePath);
+}
+
+//分析文件路径
+private void StepPrepareHeaders(UhtPackage package, IEnumerable<string> headerFiles, UhtHeaderFileType headerFileType)
+{
+	string typeDirectory = headerFileType.ToString() + '/';
+	
+	headerFile.ModuleRelativeFilePath = normalizedFullFilePath[stripLength..];
+	if (normalizedFullFilePath[stripLength..].StartsWith(typeDirectory, true, null))
+	{
+					stripLength += typeDirectory.Length;
+	}
+	headerFile.IncludeFilePath = normalizedFullFilePath[stripLength..];
+}	
+
+```
--- a/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/NativeConstTemplateArg.md
+++ b/03-UnrealEngine/Gameplay/UObject/UnrealSpecifiers/Meta/UHT/NativeConstTemplateArg.md
@@ -0,0 +1,13 @@
+# NativeConstTemplateArg
+
+- **功能描述：** 指定该属性是一个const的模板参数。
+- **使用位置：** UPROPERTY
+- **引擎模块：** UHT
+- **元数据类型：** bool
+- **常用程度：** 0
+
+指定该属性是一个const的模板参数。
+
+在源码里并没有找到使用的地方。只有在UHT中用到。
+
+在UHT中查看主要是UhtArrayProperty和UhtObjectPropertyBase，UhtOptionalProperty。