博客快捷键

按住 Shift 键查看可用快捷键

ShiftK

开启/关闭快捷键功能

ShiftA

打开/关闭中控台

ShiftD

深色/浅色显示模式

ShiftS

站内搜索

ShiftR

随机访问

ShiftH

返回首页

ShiftL

友链页面

ShiftP

关于本站

ShiftI

原版/本站右键菜单

松开 Shift 键或点击外部区域关闭

文章详情

互动

Unreal Engine FSelfRegisteringExec 完全指南

276214分钟2025-12-13240广东深圳0

Unreal Engine FSelfRegisteringExec 完全指南

概述

FSelfRegisteringExec 是 Unreal Engine 提供的一个自注册控制台命令处理器基类。它允许开发者通过继承该类来创建自定义的控制台命令，无需手动注册到任何管理器中——只需创建一个静态实例，命令就会自动生效。

核心特性

特性	说明
自动注册	构造函数中自动将实例添加到全局注册表
自动注销	析构函数中自动从全局注册表移除
线程安全	使用 `FCriticalSection` 保护注册表操作
多级执行	支持 Runtime、Dev、Editor 三种执行级别
零配置	无需修改其他代码，只需定义类和静态实例

类层次结构

FExec (基类)
    │
    └── FSelfRegisteringExec (自注册执行器)
            │
            ├── FStaticSelfRegisteringExec (静态函数包装器)
            │
            ├── FStaticSelfRegisteringExec_Dev (Dev 模式静态函数包装器)
            │
            └── FStaticSelfRegisteringExec_Editor (Editor 模式静态函数包装器)

源码位置

文件	说明
`Engine/Source/Runtime/Core/Public/Misc/Exec.h`	`FExec` 基类定义
`Engine/Source/Runtime/Core/Public/Misc/CoreMisc.h`	`FSelfRegisteringExec` 及其派生类声明
`Engine/Source/Runtime/Core/Private/Misc/CoreMisc.cpp`	实现代码

FExec 基类

FSelfRegisteringExec 继承自 FExec，了解基类的设计对理解整个机制至关重要。

FExec 定义 (Exec.h)

cpp

// Any object that is capable of taking commands.
class FExec
{
public:
    CORE_API virtual ~FExec();

#if UE_ALLOW_EXEC_COMMANDS
    /**
     * Exec handler
     *
     * @param   InWorld  World context
     * @param   Cmd      Command to parse
     * @param   Ar       Output device to log to
     *
     * @return  true if command was handled, false otherwise
     */
    CORE_API virtual bool Exec( UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar );
#else // UE_ALLOW_EXEC_COMMANDS
    /** final override of Exec that asserts if called */
    CORE_API virtual bool Exec( UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar ) final;
    
    /** final override of Exec to replace overrides where a default value for Ar is provided */
    CORE_API virtual bool Exec( UWorld* InWorld, const TCHAR* Cmd ) final;
#endif // !UE_ALLOW_EXEC_COMMANDS

protected:
    /** Implementation of Exec that is called on all targets where UE_ALLOW_EXEC_COMMANDS is true */
    virtual bool Exec_Runtime( UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar ) { return false; }

    /** Implementation of Exec that is only called in non-shipping targets */
    virtual bool Exec_Dev( UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar ) { return false; }

    /** Implementation of Exec that is only called in editor */
    virtual bool Exec_Editor( UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar ) { return false; }
};

三种执行级别

方法	调用条件	典型用途
`Exec_Runtime()`	`UE_ALLOW_EXEC_COMMANDS` 为 true 时	所有构建版本都需要的命令
`Exec_Dev()`	非 Shipping 构建	开发调试命令
`Exec_Editor()`	仅编辑器模式	编辑器专用工具命令

Exec() vs Exec_Runtime() 的区别

Exec(): 基类的公共入口方法，内部会根据构建类型依次调用 Exec_Runtime()、Exec_Dev()、Exec_Editor()
Exec_Runtime(): 受保护的虚函数，在所有允许执行命令的构建版本中被调用

如果直接重写 Exec()，则绕过了执行级别的自动分发机制。大多数情况下应该重写 Exec_Runtime()、Exec_Dev() 或 Exec_Editor()。

编译条件宏

cpp

#ifndef UE_ALLOW_EXEC_COMMANDS
    #if UE_BUILD_SHIPPING && !WITH_EDITOR
        #define UE_ALLOW_EXEC_COMMANDS UE_ALLOW_EXEC_COMMANDS_IN_SHIPPING
    #else
        #define UE_ALLOW_EXEC_COMMANDS 1
    #endif
#endif

#ifndef UE_ALLOW_EXEC_DEV
    #define UE_ALLOW_EXEC_DEV !UE_BUILD_SHIPPING && UE_ALLOW_EXEC_COMMANDS
#endif

#ifndef UE_ALLOW_EXEC_EDITOR
    #define UE_ALLOW_EXEC_EDITOR WITH_EDITOR && UE_ALLOW_EXEC_COMMANDS
#endif

FSelfRegisteringExec 详解

类定义 (CoreMisc.h)

cpp

/**
 * Exec handler that registers itself and is being routed via StaticExec.
 * Note: Not intended for use with UObjects!
 */
class FSelfRegisteringExec : public FExec
{
public:
    /** Constructor, registering this instance. */
    CORE_API FSelfRegisteringExec();
    
    /** Destructor, unregistering this instance. */
    CORE_API virtual ~FSelfRegisteringExec();

    /** Routes a command to the self-registered execs. */
    static CORE_API bool StaticExec( UWorld* Inworld, const TCHAR* Cmd, FOutputDevice& Ar );
};

实现原理 (CoreMisc.cpp)

cpp

// 全局注册表类型定义
using FSelfRegisteredExecArray = TArray<FSelfRegisteringExec*, TInlineAllocator<8>>;

// 线程安全的锁
FCriticalSection* GetExecRegistryLock()
{
    // 使用静态局部变量实现懒加载
    static FCriticalSection ExecRegistryLock;
    return &ExecRegistryLock;
}

// 全局注册表
FSelfRegisteredExecArray& GetExecRegistry()
{
    static FSelfRegisteredExecArray Execs;
    return Execs;
}

// 构造函数：自动注册
FSelfRegisteringExec::FSelfRegisteringExec()
{
    FScopeLock ScopeLock(GetExecRegistryLock());
    GetExecRegistry().Add( this );
}

// 析构函数：自动注销
FSelfRegisteringExec::~FSelfRegisteringExec()
{
    FScopeLock ScopeLock(GetExecRegistryLock());
    verify(GetExecRegistry().Remove( this ) == 1 );
}

// 静态执行：遍历所有注册的执行器
bool FSelfRegisteringExec::StaticExec( UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar )
{
    FScopeLock ScopeLock(GetExecRegistryLock());
    for (FSelfRegisteringExec* Exe : GetExecRegistry())
    {
        if (Exe->Exec( InWorld, Cmd, Ar ))
        {
            return true;
        }
    }
    return false;
}

工作流程

1. 静态实例创建
        │
        ▼
2. 构造函数调用
        │
        ▼
3. 加锁 (FScopeLock)
        │
        ▼
4. 添加到 GetExecRegistry()
        │
        ▼
5. 解锁
        │
        ▼
6. 命令执行时:
   StaticExec() 遍历所有注册的执行器
        │
        ▼
7. 调用每个执行器的 Exec() 方法
        │
        ▼
8. 如果返回 true，停止遍历

使用方法

方法 1: 继承类 + 静态实例（推荐）

这是最常用的方式，适合需要复杂逻辑的命令。

cpp

// 在 .cpp 文件中定义（不需要在 .h 中声明）

class FMyCustomExecHelper : public FSelfRegisteringExec
{
    virtual bool Exec_Editor(UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar) override
    {
        if (FParse::Command(&Cmd, TEXT("MYCOMMAND")))
        {
            // 执行命令逻辑
            Ar.Log(TEXT("MyCommand executed!"));
            return true;
        }
        return false;
    }
};

// 创建静态实例，自动注册
static FMyCustomExecHelper GMyCustomExecHelper;

方法 2: 使用静态函数包装器

适合简单命令，避免创建新类。

cpp

// 定义静态函数
static bool MyExecFunction(UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar)
{
    if (FParse::Command(&Cmd, TEXT("MYCOMMAND")))
    {
        Ar.Log(TEXT("MyCommand executed!"));
        return true;
    }
    return false;
}

// 使用包装器注册（根据执行级别选择）
static FStaticSelfRegisteringExec GMyExec(MyExecFunction);           // Runtime
static FStaticSelfRegisteringExec_Dev GMyExec(MyExecFunction);       // Dev only
static FStaticSelfRegisteringExec_Editor GMyExec(MyExecFunction);    // Editor only

选择正确的执行级别

场景	推荐方法
编辑器专用调试工具	`Exec_Editor()` 或 `FStaticSelfRegisteringExec_Editor`
开发期间调试命令	`Exec_Dev()` 或 `FStaticSelfRegisteringExec_Dev`
所有构建版本都需要	`Exec_Runtime()` 或 `FStaticSelfRegisteringExec`

实际案例分析

案例 1: Find In Blueprint 索引缓存导出

cpp

// FindInBlueprintManager.cpp:3913-3937
class FFiBDumpIndexCacheToFileExecHelper : public FSelfRegisteringExec
{
    virtual bool Exec_Editor(class UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar)
    {
        if (FParse::Command(&Cmd, TEXT("DUMPFIBINDEXCACHE")))
        {
            // 构建输出路径
            FString FileLocation = FPaths::ConvertRelativePathToFull(
                FPaths::ProjectIntermediateDir() + TEXT("BlueprintSearchTools"));
            FString FullPath = FString::Printf(TEXT("%s/FullBlueprintIndexCacheDump.csv"), *FileLocation);

            // 创建文件并写入
            FArchive* DumpFile = IFileManager::Get().CreateFileWriter(*FullPath);
            if (DumpFile)
            {
                FFindInBlueprintSearchManager::Get().DumpCache(*DumpFile);
                DumpFile->Close();
                delete DumpFile;

                UE_LOG(LogFindInBlueprint, Log, TEXT("Wrote full index cache to %s"), *FullPath);
            }
            return true;
        }
        return false;
    }
};

// 静态实例 - 自动注册
static FFiBDumpIndexCacheToFileExecHelper GFiBDumpIndexCacheToFileExec;

使用方式: 在编辑器控制台输入 DUMPFIBINDEXCACHE

案例 2: D3D11 状态缓存切换

cpp

// D3D11StateCache.cpp:13-34
#if D3D11_ALLOW_STATE_CACHE && D3D11_STATE_CACHE_RUNTIME_TOGGLE

// Default the state caching system to on.
bool GD3D11SkipStateCaching = false;

// A self registering exec helper to check for the TOGGLESTATECACHE command.
class FD3D11ToggleStateCacheExecHelper : public FSelfRegisteringExec
{
    virtual bool Exec( class UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar )
    {
        if (FParse::Command(&Cmd, TEXT("TOGGLESTATECACHE")))
        {
            GD3D11SkipStateCaching = !GD3D11SkipStateCaching;
            Ar.Log(FString::Printf(TEXT("D3D11 State Caching: %s"), 
                GD3D11SkipStateCaching ? TEXT("OFF") : TEXT("ON")));
            return true;
        }
        return false;
    }
};
static FD3D11ToggleStateCacheExecHelper GD3D11ToggleStateCacheExecHelper;

#endif  // D3D11_ALLOW_STATE_CACHE && D3D11_STATE_CACHE_RUNTIME_TOGGLE

使用方式: 在控制台输入 TOGGLESTATECACHE

注意: 此案例直接重写 Exec() 而非 Exec_Runtime()，因为它需要在所有允许执行命令的构建版本中生效。

案例 3: Vulkan 表面模拟

cpp

// VulkanSwapChain.cpp:90-118
#if !UE_BUILD_SHIPPING

bool GSimulateLostSurfaceInNextTick = false;
bool GSimulateSuboptimalSurfaceInNextTick = false;

// A self registering exec helper to check for the VULKAN_* commands.
class FVulkanCommandsHelper : public FSelfRegisteringExec
{
    virtual bool Exec_Dev(class UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar)
    {
        if (FParse::Command(&Cmd, TEXT("VULKAN_SIMULATE_LOST_SURFACE")))
        {
            GSimulateLostSurfaceInNextTick = true;
            Ar.Log(FString::Printf(TEXT("Vulkan: simulating lost surface next frame")));
            return true;
        }
        else if (FParse::Command(&Cmd, TEXT("VULKAN_SIMULATE_SUBOPTIMAL_SURFACE")))
        {
            GSimulateSuboptimalSurfaceInNextTick = true;
            Ar.Log(FString::Printf(TEXT("Vulkan: simulating suboptimal surface next frame")));
            return true;
        }
        else
        {
            return false;
        }
    }
};
static FVulkanCommandsHelper GVulkanCommandsHelper;

#endif  // !UE_BUILD_SHIPPING

使用方式: 在控制台输入 VULKAN_SIMULATE_LOST_SURFACE 或 VULKAN_SIMULATE_SUBOPTIMAL_SURFACE

命令解析工具

FParse 常用方法

cpp

// 检查并消费命令
if (FParse::Command(&Cmd, TEXT("MYCOMMAND")))
{
    // Cmd 指针已移动到命令之后的参数部分
}

// 解析参数
FString StringParam;
if (FParse::Value(Cmd, TEXT("NAME="), StringParam))
{
    // 获取 NAME=xxx 形式的参数
}

int32 IntParam;
if (FParse::Value(Cmd, TEXT("COUNT="), IntParam))
{
    // 获取整数参数
}

// 检查布尔标志
if (FParse::Param(Cmd, TEXT("VERBOSE")))
{
    // 存在 VERBOSE 标志
}

完整参数解析示例

cpp

class FMyAdvancedExecHelper : public FSelfRegisteringExec
{
    virtual bool Exec_Editor(UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar) override
    {
        if (FParse::Command(&Cmd, TEXT("EXPORTDATA")))
        {
            // 解析参数
            FString OutputPath;
            FParse::Value(Cmd, TEXT("PATH="), OutputPath);
            
            int32 MaxItems = 100; // 默认值
            FParse::Value(Cmd, TEXT("MAX="), MaxItems);
            
            bool bVerbose = FParse::Param(Cmd, TEXT("VERBOSE"));
            
            // 执行逻辑
            Ar.Logf(TEXT("Exporting to: %s, Max: %d, Verbose: %s"), 
                *OutputPath, MaxItems, bVerbose ? TEXT("Yes") : TEXT("No"));
            
            return true;
        }
        return false;
    }
};

static FMyAdvancedExecHelper GMyAdvancedExecHelper;

使用方式: EXPORTDATA PATH="C:/Output" MAX=500 VERBOSE

与其他命令系统的比较

特性	FSelfRegisteringExec	IConsoleCommand	FAutoConsoleCommand
注册方式	自动（静态实例）	手动注册	自动（静态实例）
命令格式	自定义解析	标准控制台变量格式	标准控制台变量格式
参数处理	完全自定义	框架处理	框架处理
适用场景	复杂自定义命令	简单变量/命令	简单变量/命令
执行级别控制	支持 Runtime/Dev/Editor	通过 ECVF 标志	通过 ECVF 标志

最佳实践

1. 命名规范

cpp

// 类名: F{功能}ExecHelper
class FMyFeatureExecHelper : public FSelfRegisteringExec { ... };

// 静态实例: G{类名} 或 G{功能}ExecHelper
static FMyFeatureExecHelper GMyFeatureExecHelper;

// 命令名: 全大写，下划线分隔
if (FParse::Command(&Cmd, TEXT("MY_FEATURE_COMMAND")))

2. 日志输出

cpp

// 使用 Ar 输出到控制台
Ar.Log(TEXT("Command executed successfully"));
Ar.Logf(TEXT("Processed %d items"), Count);

// 同时记录到日志文件
UE_LOG(LogMyCategory, Log, TEXT("Command executed: %s"), *CommandName);

3. 错误处理

cpp

virtual bool Exec_Editor(UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar) override
{
    if (FParse::Command(&Cmd, TEXT("MYCOMMAND")))
    {
        FString RequiredParam;
        if (!FParse::Value(Cmd, TEXT("REQUIRED="), RequiredParam))
        {
            Ar.Log(TEXT("Error: REQUIRED parameter is missing"));
            Ar.Log(TEXT("Usage: MYCOMMAND REQUIRED=<value> [OPTIONAL=<value>]"));
            return true; // 仍然返回 true，因为命令被识别了
        }
        
        // 执行逻辑...
        return true;
    }
    return false;
}

4. 条件编译

cpp

#if WITH_EDITOR
class FEditorOnlyExecHelper : public FSelfRegisteringExec
{
    virtual bool Exec_Editor(UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar) override
    {
        // 编辑器专用逻辑
        return false;
    }
};
static FEditorOnlyExecHelper GEditorOnlyExecHelper;
#endif

注意事项

不要用于 UObject: 官方注释明确指出 "Not intended for use with UObjects!"
静态实例生命周期: 静态实例在模块加载时创建，模块卸载时销毁
线程安全: 虽然注册表操作是线程安全的，但命令执行逻辑需要自行保证线程安全
返回值语义:
- 返回 true: 命令已处理，停止继续查找
- 返回 false: 命令未处理，继续查找其他处理器
命令冲突: 如果多个处理器响应同一命令，只有第一个返回 true 的会生效

总结

FSelfRegisteringExec 是 Unreal Engine 中一个优雅的自注册命令系统，通过 C++ 的静态初始化机制实现零配置的命令注册。它特别适合：

模块级别的调试命令
不依赖 UObject 系统的工具命令
需要精细控制执行级别的命令
需要完全自定义参数解析的复杂命令

通过继承 FSelfRegisteringExec 并创建静态实例，开发者可以快速添加自定义控制台命令，无需修改任何其他代码。

布总

生活明朗，万物可爱

本文是原创文章，采用 CC BY-NC-SA 4.0 协议，完整转载请注明来自布总

FSelfRegisteringExec1

喜欢这篇文章的人也看了

随便逛逛

UE5-TFuture TPromise 异步编程核心模板深度解析

FOutputDeviceFile

隐私政策

评论内容

0/500

昵称

邮箱

网址

滚动到此处加载评论...

安知鱼

来自安知鱼最新设计与科技的文章

查看全部

文章详情

互动

Unreal Engine FSelfRegisteringExec 完全指南

276214分钟2025-12-13240广东深圳0

Unreal Engine FSelfRegisteringExec 完全指南

概述

核心特性

特性	说明
自动注册	构造函数中自动将实例添加到全局注册表
自动注销	析构函数中自动从全局注册表移除
线程安全	使用 `FCriticalSection` 保护注册表操作
多级执行	支持 Runtime、Dev、Editor 三种执行级别
零配置	无需修改其他代码，只需定义类和静态实例

类层次结构

FExec (基类)
    │
    └── FSelfRegisteringExec (自注册执行器)
            │
            ├── FStaticSelfRegisteringExec (静态函数包装器)
            │
            ├── FStaticSelfRegisteringExec_Dev (Dev 模式静态函数包装器)
            │
            └── FStaticSelfRegisteringExec_Editor (Editor 模式静态函数包装器)

源码位置

文件	说明
`Engine/Source/Runtime/Core/Public/Misc/Exec.h`	`FExec` 基类定义
`Engine/Source/Runtime/Core/Public/Misc/CoreMisc.h`	`FSelfRegisteringExec` 及其派生类声明
`Engine/Source/Runtime/Core/Private/Misc/CoreMisc.cpp`	实现代码

FExec 基类

FSelfRegisteringExec 继承自 FExec，了解基类的设计对理解整个机制至关重要。

FExec 定义 (Exec.h)

cpp

// Any object that is capable of taking commands.
class FExec
{
public:
    CORE_API virtual ~FExec();

#if UE_ALLOW_EXEC_COMMANDS
    /**
     * Exec handler
     *
     * @param   InWorld  World context
     * @param   Cmd      Command to parse
     * @param   Ar       Output device to log to
     *
     * @return  true if command was handled, false otherwise
     */
    CORE_API virtual bool Exec( UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar );
#else // UE_ALLOW_EXEC_COMMANDS
    /** final override of Exec that asserts if called */
    CORE_API virtual bool Exec( UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar ) final;
    
    /** final override of Exec to replace overrides where a default value for Ar is provided */
    CORE_API virtual bool Exec( UWorld* InWorld, const TCHAR* Cmd ) final;
#endif // !UE_ALLOW_EXEC_COMMANDS

protected:
    /** Implementation of Exec that is called on all targets where UE_ALLOW_EXEC_COMMANDS is true */
    virtual bool Exec_Runtime( UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar ) { return false; }

    /** Implementation of Exec that is only called in non-shipping targets */
    virtual bool Exec_Dev( UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar ) { return false; }

    /** Implementation of Exec that is only called in editor */
    virtual bool Exec_Editor( UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar ) { return false; }
};

三种执行级别

方法	调用条件	典型用途
`Exec_Runtime()`	`UE_ALLOW_EXEC_COMMANDS` 为 true 时	所有构建版本都需要的命令
`Exec_Dev()`	非 Shipping 构建	开发调试命令
`Exec_Editor()`	仅编辑器模式	编辑器专用工具命令

Exec() vs Exec_Runtime() 的区别

Exec(): 基类的公共入口方法，内部会根据构建类型依次调用 Exec_Runtime()、Exec_Dev()、Exec_Editor()
Exec_Runtime(): 受保护的虚函数，在所有允许执行命令的构建版本中被调用

如果直接重写 Exec()，则绕过了执行级别的自动分发机制。大多数情况下应该重写 Exec_Runtime()、Exec_Dev() 或 Exec_Editor()。

编译条件宏

cpp

#ifndef UE_ALLOW_EXEC_COMMANDS
    #if UE_BUILD_SHIPPING && !WITH_EDITOR
        #define UE_ALLOW_EXEC_COMMANDS UE_ALLOW_EXEC_COMMANDS_IN_SHIPPING
    #else
        #define UE_ALLOW_EXEC_COMMANDS 1
    #endif
#endif

#ifndef UE_ALLOW_EXEC_DEV
    #define UE_ALLOW_EXEC_DEV !UE_BUILD_SHIPPING && UE_ALLOW_EXEC_COMMANDS
#endif

#ifndef UE_ALLOW_EXEC_EDITOR
    #define UE_ALLOW_EXEC_EDITOR WITH_EDITOR && UE_ALLOW_EXEC_COMMANDS
#endif

FSelfRegisteringExec 详解

类定义 (CoreMisc.h)

cpp

/**
 * Exec handler that registers itself and is being routed via StaticExec.
 * Note: Not intended for use with UObjects!
 */
class FSelfRegisteringExec : public FExec
{
public:
    /** Constructor, registering this instance. */
    CORE_API FSelfRegisteringExec();
    
    /** Destructor, unregistering this instance. */
    CORE_API virtual ~FSelfRegisteringExec();

    /** Routes a command to the self-registered execs. */
    static CORE_API bool StaticExec( UWorld* Inworld, const TCHAR* Cmd, FOutputDevice& Ar );
};

实现原理 (CoreMisc.cpp)

cpp

// 全局注册表类型定义
using FSelfRegisteredExecArray = TArray<FSelfRegisteringExec*, TInlineAllocator<8>>;

// 线程安全的锁
FCriticalSection* GetExecRegistryLock()
{
    // 使用静态局部变量实现懒加载
    static FCriticalSection ExecRegistryLock;
    return &ExecRegistryLock;
}

// 全局注册表
FSelfRegisteredExecArray& GetExecRegistry()
{
    static FSelfRegisteredExecArray Execs;
    return Execs;
}

// 构造函数：自动注册
FSelfRegisteringExec::FSelfRegisteringExec()
{
    FScopeLock ScopeLock(GetExecRegistryLock());
    GetExecRegistry().Add( this );
}

// 析构函数：自动注销
FSelfRegisteringExec::~FSelfRegisteringExec()
{
    FScopeLock ScopeLock(GetExecRegistryLock());
    verify(GetExecRegistry().Remove( this ) == 1 );
}

// 静态执行：遍历所有注册的执行器
bool FSelfRegisteringExec::StaticExec( UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar )
{
    FScopeLock ScopeLock(GetExecRegistryLock());
    for (FSelfRegisteringExec* Exe : GetExecRegistry())
    {
        if (Exe->Exec( InWorld, Cmd, Ar ))
        {
            return true;
        }
    }
    return false;
}

工作流程

1. 静态实例创建
        │
        ▼
2. 构造函数调用
        │
        ▼
3. 加锁 (FScopeLock)
        │
        ▼
4. 添加到 GetExecRegistry()
        │
        ▼
5. 解锁
        │
        ▼
6. 命令执行时:
   StaticExec() 遍历所有注册的执行器
        │
        ▼
7. 调用每个执行器的 Exec() 方法
        │
        ▼
8. 如果返回 true，停止遍历

使用方法

方法 1: 继承类 + 静态实例（推荐）

这是最常用的方式，适合需要复杂逻辑的命令。

cpp

// 在 .cpp 文件中定义（不需要在 .h 中声明）

class FMyCustomExecHelper : public FSelfRegisteringExec
{
    virtual bool Exec_Editor(UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar) override
    {
        if (FParse::Command(&Cmd, TEXT("MYCOMMAND")))
        {
            // 执行命令逻辑
            Ar.Log(TEXT("MyCommand executed!"));
            return true;
        }
        return false;
    }
};

// 创建静态实例，自动注册
static FMyCustomExecHelper GMyCustomExecHelper;

方法 2: 使用静态函数包装器

适合简单命令，避免创建新类。

cpp

// 定义静态函数
static bool MyExecFunction(UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar)
{
    if (FParse::Command(&Cmd, TEXT("MYCOMMAND")))
    {
        Ar.Log(TEXT("MyCommand executed!"));
        return true;
    }
    return false;
}

// 使用包装器注册（根据执行级别选择）
static FStaticSelfRegisteringExec GMyExec(MyExecFunction);           // Runtime
static FStaticSelfRegisteringExec_Dev GMyExec(MyExecFunction);       // Dev only
static FStaticSelfRegisteringExec_Editor GMyExec(MyExecFunction);    // Editor only

选择正确的执行级别

场景	推荐方法
编辑器专用调试工具	`Exec_Editor()` 或 `FStaticSelfRegisteringExec_Editor`
开发期间调试命令	`Exec_Dev()` 或 `FStaticSelfRegisteringExec_Dev`
所有构建版本都需要	`Exec_Runtime()` 或 `FStaticSelfRegisteringExec`

实际案例分析

案例 1: Find In Blueprint 索引缓存导出

cpp

// FindInBlueprintManager.cpp:3913-3937
class FFiBDumpIndexCacheToFileExecHelper : public FSelfRegisteringExec
{
    virtual bool Exec_Editor(class UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar)
    {
        if (FParse::Command(&Cmd, TEXT("DUMPFIBINDEXCACHE")))
        {
            // 构建输出路径
            FString FileLocation = FPaths::ConvertRelativePathToFull(
                FPaths::ProjectIntermediateDir() + TEXT("BlueprintSearchTools"));
            FString FullPath = FString::Printf(TEXT("%s/FullBlueprintIndexCacheDump.csv"), *FileLocation);

            // 创建文件并写入
            FArchive* DumpFile = IFileManager::Get().CreateFileWriter(*FullPath);
            if (DumpFile)
            {
                FFindInBlueprintSearchManager::Get().DumpCache(*DumpFile);
                DumpFile->Close();
                delete DumpFile;

                UE_LOG(LogFindInBlueprint, Log, TEXT("Wrote full index cache to %s"), *FullPath);
            }
            return true;
        }
        return false;
    }
};

// 静态实例 - 自动注册
static FFiBDumpIndexCacheToFileExecHelper GFiBDumpIndexCacheToFileExec;

使用方式: 在编辑器控制台输入 DUMPFIBINDEXCACHE

案例 2: D3D11 状态缓存切换

cpp

// D3D11StateCache.cpp:13-34
#if D3D11_ALLOW_STATE_CACHE && D3D11_STATE_CACHE_RUNTIME_TOGGLE

// Default the state caching system to on.
bool GD3D11SkipStateCaching = false;

// A self registering exec helper to check for the TOGGLESTATECACHE command.
class FD3D11ToggleStateCacheExecHelper : public FSelfRegisteringExec
{
    virtual bool Exec( class UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar )
    {
        if (FParse::Command(&Cmd, TEXT("TOGGLESTATECACHE")))
        {
            GD3D11SkipStateCaching = !GD3D11SkipStateCaching;
            Ar.Log(FString::Printf(TEXT("D3D11 State Caching: %s"), 
                GD3D11SkipStateCaching ? TEXT("OFF") : TEXT("ON")));
            return true;
        }
        return false;
    }
};
static FD3D11ToggleStateCacheExecHelper GD3D11ToggleStateCacheExecHelper;

#endif  // D3D11_ALLOW_STATE_CACHE && D3D11_STATE_CACHE_RUNTIME_TOGGLE

使用方式: 在控制台输入 TOGGLESTATECACHE

注意: 此案例直接重写 Exec() 而非 Exec_Runtime()，因为它需要在所有允许执行命令的构建版本中生效。

案例 3: Vulkan 表面模拟

cpp

// VulkanSwapChain.cpp:90-118
#if !UE_BUILD_SHIPPING

bool GSimulateLostSurfaceInNextTick = false;
bool GSimulateSuboptimalSurfaceInNextTick = false;

// A self registering exec helper to check for the VULKAN_* commands.
class FVulkanCommandsHelper : public FSelfRegisteringExec
{
    virtual bool Exec_Dev(class UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar)
    {
        if (FParse::Command(&Cmd, TEXT("VULKAN_SIMULATE_LOST_SURFACE")))
        {
            GSimulateLostSurfaceInNextTick = true;
            Ar.Log(FString::Printf(TEXT("Vulkan: simulating lost surface next frame")));
            return true;
        }
        else if (FParse::Command(&Cmd, TEXT("VULKAN_SIMULATE_SUBOPTIMAL_SURFACE")))
        {
            GSimulateSuboptimalSurfaceInNextTick = true;
            Ar.Log(FString::Printf(TEXT("Vulkan: simulating suboptimal surface next frame")));
            return true;
        }
        else
        {
            return false;
        }
    }
};
static FVulkanCommandsHelper GVulkanCommandsHelper;

#endif  // !UE_BUILD_SHIPPING

使用方式: 在控制台输入 VULKAN_SIMULATE_LOST_SURFACE 或 VULKAN_SIMULATE_SUBOPTIMAL_SURFACE

命令解析工具

FParse 常用方法

cpp

// 检查并消费命令
if (FParse::Command(&Cmd, TEXT("MYCOMMAND")))
{
    // Cmd 指针已移动到命令之后的参数部分
}

// 解析参数
FString StringParam;
if (FParse::Value(Cmd, TEXT("NAME="), StringParam))
{
    // 获取 NAME=xxx 形式的参数
}

int32 IntParam;
if (FParse::Value(Cmd, TEXT("COUNT="), IntParam))
{
    // 获取整数参数
}

// 检查布尔标志
if (FParse::Param(Cmd, TEXT("VERBOSE")))
{
    // 存在 VERBOSE 标志
}

完整参数解析示例

cpp

class FMyAdvancedExecHelper : public FSelfRegisteringExec
{
    virtual bool Exec_Editor(UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar) override
    {
        if (FParse::Command(&Cmd, TEXT("EXPORTDATA")))
        {
            // 解析参数
            FString OutputPath;
            FParse::Value(Cmd, TEXT("PATH="), OutputPath);
            
            int32 MaxItems = 100; // 默认值
            FParse::Value(Cmd, TEXT("MAX="), MaxItems);
            
            bool bVerbose = FParse::Param(Cmd, TEXT("VERBOSE"));
            
            // 执行逻辑
            Ar.Logf(TEXT("Exporting to: %s, Max: %d, Verbose: %s"), 
                *OutputPath, MaxItems, bVerbose ? TEXT("Yes") : TEXT("No"));
            
            return true;
        }
        return false;
    }
};

static FMyAdvancedExecHelper GMyAdvancedExecHelper;

使用方式: EXPORTDATA PATH="C:/Output" MAX=500 VERBOSE

与其他命令系统的比较

特性	FSelfRegisteringExec	IConsoleCommand	FAutoConsoleCommand
注册方式	自动（静态实例）	手动注册	自动（静态实例）
命令格式	自定义解析	标准控制台变量格式	标准控制台变量格式
参数处理	完全自定义	框架处理	框架处理
适用场景	复杂自定义命令	简单变量/命令	简单变量/命令
执行级别控制	支持 Runtime/Dev/Editor	通过 ECVF 标志	通过 ECVF 标志

最佳实践

1. 命名规范

cpp

// 类名: F{功能}ExecHelper
class FMyFeatureExecHelper : public FSelfRegisteringExec { ... };

// 静态实例: G{类名} 或 G{功能}ExecHelper
static FMyFeatureExecHelper GMyFeatureExecHelper;

// 命令名: 全大写，下划线分隔
if (FParse::Command(&Cmd, TEXT("MY_FEATURE_COMMAND")))

2. 日志输出

cpp

// 使用 Ar 输出到控制台
Ar.Log(TEXT("Command executed successfully"));
Ar.Logf(TEXT("Processed %d items"), Count);

// 同时记录到日志文件
UE_LOG(LogMyCategory, Log, TEXT("Command executed: %s"), *CommandName);

3. 错误处理

cpp

virtual bool Exec_Editor(UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar) override
{
    if (FParse::Command(&Cmd, TEXT("MYCOMMAND")))
    {
        FString RequiredParam;
        if (!FParse::Value(Cmd, TEXT("REQUIRED="), RequiredParam))
        {
            Ar.Log(TEXT("Error: REQUIRED parameter is missing"));
            Ar.Log(TEXT("Usage: MYCOMMAND REQUIRED=<value> [OPTIONAL=<value>]"));
            return true; // 仍然返回 true，因为命令被识别了
        }
        
        // 执行逻辑...
        return true;
    }
    return false;
}

4. 条件编译

cpp

#if WITH_EDITOR
class FEditorOnlyExecHelper : public FSelfRegisteringExec
{
    virtual bool Exec_Editor(UWorld* InWorld, const TCHAR* Cmd, FOutputDevice& Ar) override
    {
        // 编辑器专用逻辑
        return false;
    }
};
static FEditorOnlyExecHelper GEditorOnlyExecHelper;
#endif

注意事项

不要用于 UObject: 官方注释明确指出 "Not intended for use with UObjects!"
静态实例生命周期: 静态实例在模块加载时创建，模块卸载时销毁
线程安全: 虽然注册表操作是线程安全的，但命令执行逻辑需要自行保证线程安全
返回值语义:
- 返回 true: 命令已处理，停止继续查找
- 返回 false: 命令未处理，继续查找其他处理器
命令冲突: 如果多个处理器响应同一命令，只有第一个返回 true 的会生效

总结

FSelfRegisteringExec 是 Unreal Engine 中一个优雅的自注册命令系统，通过 C++ 的静态初始化机制实现零配置的命令注册。它特别适合：

模块级别的调试命令
不依赖 UObject 系统的工具命令
需要精细控制执行级别的命令
需要完全自定义参数解析的复杂命令

通过继承 FSelfRegisteringExec 并创建静态实例，开发者可以快速添加自定义控制台命令，无需修改任何其他代码。

布总

生活明朗，万物可爱

本文是原创文章，采用 CC BY-NC-SA 4.0 协议，完整转载请注明来自布总

FSelfRegisteringExec1

喜欢这篇文章的人也看了

随便逛逛

UE5-TFuture TPromise 异步编程核心模板深度解析

FOutputDeviceFile

隐私政策

评论内容

0/500

昵称

邮箱

网址

滚动到此处加载评论...

安知鱼

来自安知鱼最新设计与科技的文章

查看全部