DirectoryIndexKeepFiles

DirectoryIndexKeepFiles

#Overview

name: DirectoryIndexKeepFiles

The value of this variable can be defined or overridden in .ini config files. 7 .ini config files referencing this setting variable.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of DirectoryIndexKeepFiles is to specify which files should be kept in the pruned directory index of a Pak file at runtime. This setting is used in the Pak file system, which is a part of Unreal Engine’s file management and asset streaming subsystem.

The Unreal Engine subsystem that relies on this setting variable is primarily the Pak file system, which is part of the Core module and PakFile module. It’s used in the FPakFile class, which handles reading and managing Pak files.

The value of this variable is set in the engine configuration file (GEngineIni). It’s read using the GConfig->GetArray function, specifically looking for the “DirectoryIndexKeepFiles” key under the “Pak” section.

This variable interacts with other related variables such as “DirectoryIndexKeepEmptyDirectories” and “DirectoryRootsToKeepInMemoryWhenUnloadingPakEntryFilenames” (a legacy setting). These variables work together to determine which files and directories should be kept in the pruned directory index.

Developers must be aware that this variable affects memory usage and performance. By specifying which files to keep in the pruned index, developers can control the balance between memory usage and file access speed. It’s important to carefully consider which files need to be quickly accessible and which can be excluded from the in-memory index.

Best practices when using this variable include:

  1. Only include files that are frequently accessed or critical for performance.
  2. Use wildcards judiciously to match file patterns.
  3. Regularly review and update the list as project requirements change.
  4. Consider the impact on memory usage, especially for platforms with limited resources.
  5. Test thoroughly to ensure that excluding files from the index doesn’t negatively impact game performance or cause missing asset issues.

By properly configuring DirectoryIndexKeepFiles, developers can optimize memory usage while maintaining quick access to essential files in their Unreal Engine projects.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:2952, section: [Pak]

Location: <Workspace>/Engine/Config/BaseEngine.ini:2953, section: [Pak]

Location: <Workspace>/Engine/Config/BaseEngine.ini:2954, section: [Pak]

Location: <Workspace>/Engine/Config/BaseEngine.ini:2955, section: [Pak]

Location: <Workspace>/Engine/Config/BaseEngine.ini:2956, section: [Pak]

Location: <Workspace>/Engine/Config/BaseEngine.ini:2957, section: [Pak]

Location: <Workspace>/Engine/Config/BaseEngine.ini:2958, section: [Pak]

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Core/Public/GenericPlatform/GenericPlatformFile.h:880

Scope (from outer to inner):

file
class        class IPakFile

Source code excerpt:

	/**
	 * Calls the given Visitor on every FileName in the Pruned Directory Index. FileNames passed to the Vistory are the RelativePath from the Mount of the PakFile
	 * The Pruned Directory Index at Runtime contains only the DirectoryIndexKeepFiles-specified subset of FilesNames and DirectoryNames that exist in the PakFile
	 */
	virtual void PakVisitPrunedFilenames(IPlatformFile::FDirectoryVisitor& Visitor) const = 0;
	virtual const FString& PakGetMountPoint() const = 0;

	virtual int32 GetNumFiles() const = 0;
};

inline uint32 GetTypeHash(const FFileJournalFileHandle& A)
{

#Loc: <Workspace>/Engine/Source/Runtime/PakFile/Private/IPlatformFilePak.cpp:6472

Scope (from outer to inner):

file
function     bool FPakFile::LoadLegacyIndex

Source code excerpt:

		bWillPruneDirectoryIndex = true;
		bSomePakNeedsPruning = true;
		// We cannot prune during this call because config settings have not yet been loaded and we need the settings for DirectoryIndexKeepFiles before we can prune
		// PrunedDirectoryIndex will be created and swapped with DirectoryIndex in OptimizeMemoryUsageForMountedPaks, and bHasFullDirectoryIndex will be set to false then
	}
	else
	{
		bNeedsLegacyPruning = false;
		bWillPruneDirectoryIndex = false;

#Loc: <Workspace>/Engine/Source/Runtime/PakFile/Private/IPlatformFilePak.cpp:6591

Scope (from outer to inner):

file
function     void FPakFile::PruneDirectoryIndex

Source code excerpt:

	// Caller holds WriteLock on DirectoryIndexLock
	TArray<FString> FileWildCards, DirectoryWildCards, OldWildCards;
	GConfig->GetArray(TEXT("Pak"), TEXT("DirectoryIndexKeepFiles"), FileWildCards, GEngineIni);
	GConfig->GetArray(TEXT("Pak"), TEXT("DirectoryIndexKeepEmptyDirectories"), DirectoryWildCards, GEngineIni);
	GConfig->GetArray(TEXT("Pak"), TEXT("DirectoryRootsToKeepInMemoryWhenUnloadingPakEntryFilenames"), OldWildCards, GEngineIni); // Legacy name, treated as both KeepFiles and KeepEmptyDirectories
	DirectoryWildCards.Append(OldWildCards);
	FileWildCards.Append(OldWildCards);
	int32 NumKeptEntries = 0;

#Loc: <Workspace>/Engine/Source/Runtime/PakFile/Public/IPlatformFilePak.h:793

Scope: file

Source code excerpt:

	/** Info on all files stored in pak. */
	TArray<FPakEntry> Files;
	/** Pak Index organized as a map of directories to support searches by path.  This Index is pruned at runtime of all FileNames and Paths that are not allowed by DirectoryIndexKeepFiles */
	FDirectoryIndex DirectoryIndex;
#if ENABLE_PAKFILE_RUNTIME_PRUNING
	/** Temporary-lifetime copy of the Pruned DirectoryIndex; all Pruned files have been removed form this copy.  This copy is used for validation that no queries are missing during runtime, and will be swapped into the DirectoryIndex when Pak Mounting is complete */
	FDirectoryIndex PrunedDirectoryIndex;
	/** ReaderWriter lock to guard DirectoryIndex iteration from being interrupted by the swap of PrunedDirectoryIndex */
	mutable FRWLock DirectoryIndexLock;