Unreal Engine 4：学习笔记（十四）Console Variables

矫情吗；* 2022-03-19 09:24 719阅读 0赞

**目录**

一、打开控制台

二、创建控制台变量

三、获取控制台变量的值

四、跟踪控制台变量值的变化

--------------------

为了方便开发，可以通过控制台设置变量。

### 一、打开控制台 ###

当运行后，可通过点出（\`）或（~）键来控制：  
一次点击，显示控制台输入框；  
二次点击，除显示控制台输入框外，还显示命令回显；  
三次点击，输入框和命令回显全部消失；

### 二、创建控制台变量 ###

创建控制台变量可以使用如下几种方式：

1、使用TAutoConsoleVariable，其部分源代码如下

template <class T>
    class TAutoConsoleVariable : public FAutoConsoleObject
    {
    public:
    	TAutoConsoleVariable(const TCHAR* Name, const T& DefaultValue, const TCHAR* Help, uint32 Flags = ECVF_Default);
    }

其中T只能是int32、float、FString  
Name：变量名  
DefaultValue：变量的默认值  
Help：如何输入“<变量名> ?”，将要显示的帮助信息  
Flags：可选值是从ECVF\_Default到ECVF\_ScalabilityGroup的值

/**
     * Bitmask 0x1, 0x2, 0x4, ..
     */
    enum EConsoleVariableFlags
    {
    	/**
    	 * Default, no flags are set, the value is set by the constructor 
    	 */
    	ECVF_Default = 0x0,
    	/**
    	 * Console variables marked with this flag behave differently in a final release build.
    	 * Then they are are hidden in the console and cannot be changed by the user.
    	 */
    	ECVF_Cheat = 0x1,
    	/**
    	 * Console variables cannot be changed by the user (from console).
    	 * Changing from C++ or ini is still possible.
    	 */
    	ECVF_ReadOnly = 0x4,
    	/**
    	 * UnregisterConsoleObject() was called on this one.
    	 * If the variable is registered again with the same type this object is reactivated. This is good for DLL unloading.
    	 */
    	ECVF_Unregistered = 0x8,
    	/**
    	 * This flag is set by the ini loading code when the variable wasn't registered yet.
    	 * Once the variable is registered later the value is copied over and the variable is destructed.
    	 */
    	ECVF_CreatedFromIni = 0x10,
    	/**
    	 * Maintains another shadow copy and updates the copy with render thread commands to maintain proper ordering.
    	 * Could be extended for more/other thread.
     	 * Note: On console variable references it assumes the reference is accessed on the render thread only
    	 * (Don't use in any other thread or better don't use references to avoid the potential pitfall).
    	 */
    	ECVF_RenderThreadSafe = 0x20,
    
    	/* ApplyCVarSettingsGroupFromIni will complain if this wasn't set, should not be combined with ECVF_Cheat */
    	ECVF_Scalability = 0x40,
    
    	/* those cvars control other cvars with the flag ECVF_Scalability, names should start with "sg." */
    	ECVF_ScalabilityGroup = 0x80,
    
    	// ------------------------------------------------
    
    	/* to get some history of where the last value was set by ( useful for track down why a cvar is in a specific state */
    	ECVF_SetByMask =				0xff000000,
    	
    	// the ECVF_SetBy are sorted in override order (weak to strong), the value is not serialized, it only affects it's override behavior when calling Set()
    
    	// lowest priority (default after console variable creation)
    	ECVF_SetByConstructor =			0x00000000,
    	// from Scalability.ini (lower priority than game settings so it's easier to override partially)
    	ECVF_SetByScalability =			0x01000000,
    	// (in game UI or from file)
    	ECVF_SetByGameSetting =			0x02000000,
    	// project settings (editor UI or from file, higher priority than game setting to allow to enforce some setting fro this project)
    	ECVF_SetByProjectSetting =		0x03000000,
    	// per device setting (e.g. specific iOS device, higher priority than per project to do device specific settings)
    	ECVF_SetByDeviceProfile =		0x04000000,
    	// per project setting (ini file e.g. Engine.ini or Game.ini)
    	ECVF_SetBySystemSettingsIni =	0x05000000,
    	// consolevariables.ini (for multiple projects)
    	ECVF_SetByConsoleVariablesIni = 0x06000000,
    	// a minus command e.g. -VSync (very high priority to enforce the setting for the application)
    	ECVF_SetByCommandline =			0x07000000,
    	// least useful, likely a hack, maybe better to find the correct SetBy...
    	ECVF_SetByCode =				0x08000000,
    	// editor UI or console in game or editor
    	ECVF_SetByConsole =				0x09000000,
    
    	// ------------------------------------------------
    };

其中，ECVF\_Cheat表示此变量会在正式版本中隐藏。从ECVF\_SetByConstructor到ECVF\_SetByConstructor是表示优先级。

2、使用FAutoConsoleVariableRef，其部分源代码如下

class CORE_API FAutoConsoleVariableRef : private FAutoConsoleObject
    {
    public:
    	/**
    	 * Create a reference to a int console variable
    	 * @param Name must not be 0
    	 * @param Help must not be 0
    	 * @param Flags bitmask combined from EConsoleVariableFlags
    	 */
    	FAutoConsoleVariableRef(const TCHAR* Name, int32& RefValue, const TCHAR* Help, uint32 Flags = ECVF_Default);
    	/**
    	 * Create a reference to a float console variable
    	 * @param Name must not be 0
    	 * @param Help must not be 0
    	 * @param Flags bitmask combined from EConsoleVariableFlags
    	 */
    	FAutoConsoleVariableRef(const TCHAR* Name, float& RefValue, const TCHAR* Help, uint32 Flags = ECVF_Default);
    }

3、直接使用IConsoleManager，其部分源代码如下

/**
     * handles console commands and variables, registered console variables are released on destruction
     */
    struct CORE_API IConsoleManager
    {
    	/**
    	 * Create a int console variable
    	 * @param Name must not be 0
    	 * @param Help must not be 0
    	 * @param Flags bitmask combined from EConsoleVariableFlags
    	 */
    	virtual IConsoleVariable* RegisterConsoleVariable(const TCHAR* Name, int32 DefaultValue, const TCHAR* Help, uint32 Flags = ECVF_Default) = 0;
    	/**
    	 * Create a float console variable
    	 * @param Name must not be 0
    	 * @param Help must not be 0
    	 * @param Flags bitmask combined from EConsoleVariableFlags
    	 */
    	virtual IConsoleVariable* RegisterConsoleVariable(const TCHAR* Name, float DefaultValue, const TCHAR* Help, uint32 Flags = ECVF_Default) = 0;
    	/**
    	 * Create a string console variable
    	 * @param Name must not be 0
    	 * @param Help must not be 0
    	 * @param Flags bitmask combined from EConsoleVariableFlags
    	 */
    	virtual IConsoleVariable* RegisterConsoleVariable(const TCHAR* Name, const FString& DefaultValue, const TCHAR* Help, uint32 Flags = ECVF_Default) = 0;
    	/**
    	 * Create a reference to a int console variable
    	 * @param Name must not be 0
    	 * @param Help must not be 0
    	 * @param Flags bitmask combined from EConsoleVariableFlags
    	 */
    	virtual IConsoleVariable* RegisterConsoleVariableRef(const TCHAR* Name, int32& RefValue, const TCHAR* Help, uint32 Flags = ECVF_Default) = 0;
    	/**
    	 * Create a reference to a float console variable
    	 * @param Name must not be 0
    	 * @param Help must not be 0
    	 * @param Flags bitmask combined from EConsoleVariableFlags
    	 */
    	virtual IConsoleVariable* RegisterConsoleVariableRef(const TCHAR* Name, float& RefValue, const TCHAR* Help, uint32 Flags = ECVF_Default) = 0;
    	/**
    	* Create a reference to a bool console variable
    	* @param Name must not be 0
    	* @param Help must not be 0
    	* @param Flags bitmask combined from EConsoleVariableFlags
    	*/
    	virtual IConsoleVariable* RegisterConsoleVariableRef(const TCHAR* Name, bool& RefValue, const TCHAR* Help, uint32 Flags = ECVF_Default) = 0;
    
    
    	/** Returns the singleton for the console manager **/
    	FORCEINLINE static IConsoleManager& Get()
    	{
    		if (!Singleton)
    		{
    			SetupSingleton();
    			check(Singleton != nullptr);
    		}
    		return *Singleton;
    	}
    
    protected:
    	virtual ~IConsoleManager() { }
    
    private:
    	/** Singleton for the console manager **/
    	static IConsoleManager* Singleton;
    
    	/** Function to create the singleton **/
    	static void SetupSingleton();
    };

例如，

IConsoleManager::Get().RegisterConsoleVariable(TEXT("r.RefractionQuality"),
       2,
       TEXT("Defines the distortion/refraction quality, adjust for quality or performance.\n")
        TEXT("<=0: off (fastest)\n")
        TEXT("  1: low quality (not yet implemented)\n")
        TEXT("  2: normal quality (default)\n")
        TEXT("  3: high quality (e.g. color fringe, not yet implemented)"),
       ECVF_Scalability | ECVF_RenderThreadSafe);

实际上，1和2两种方式内部都是调用的第3种方式的代码实现的。

### 三、获取控制台变量的值 ###

FAutoConsoleVariableRef CVarVisualizeGPUSimulation(...);
    int32 = CVarVisualizeGPUSimulation->GetInt();
    
    TAutoConsoleVariable<int32> CVarRefractionQuality(...)
    int32 VisualizeGPUSimulation = CVarVisualizeGPUSimulation->GetInt();

也可以直接使用IConsoleManager

auto CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("TonemapperType")); 
    int32 Value = CVar->GetInt();

### 四、跟踪控制台变量值的变化 ###

可以使用FAutoConsoleVariableSink，也可以使用FAutoConsoleVariableRef和TAutoConsoleVariable的SetOnChangedCallback

void OnChangeResQuality(IConsoleVariable* Var)
    {
    }
    CVarResQuality->SetOnChangedCallback(FConsoleVariableDelegate::CreateStatic(&OnChangeResQuality));

void ATestProjectGameModeBase::OnChange(IConsoleVariable* Var)
    {
    	FString info1 = FString::Printf(TEXT("tmp1=%d"), Var->GetInt());
    	GEngine->AddOnScreenDebugMessage(-1, 60.f, FColor::Red, info1);
    };
    
    
    TAutoConsoleVariable<int32> CVarRefractionQuality(...);
    
    CVarRefractionQuality->SetOnChangedCallback(FConsoleVariableDelegate::CreateUObject(this, &ATestProjectGameModeBase::OnChange));

static void MySinkFunction()
    {
    }
    FAutoConsoleVariableSink CMyVarSink(FConsoleCommandDelegate::CreateStatic(&MySinkFunction));

## ##

参考文档  
[Development Setup -> Programming Tools -> Console Variables in C++][Development Setup -_ Programming Tools -_ Console Variables in C]  
Command-Line Arguments

[Development Setup -_ Programming Tools -_ Console Variables in C]: https://docs.unrealengine.com/en-us/Programming/Development/Tools/ConsoleManager