class

VFS

Mount points, LRU cache, async I/O. Mounting a file system at a virtual path makes its files reachable under that prefix: Mount("Content", new NativeFileSystem("C:/Game/Content")) Open("Content/Textures/player.png") -> C:/Game/Content/Textures/player.png

Module
Filesystem
Header
#include "Filesystem/VFS.h"
Namespace
Mowo

Constructors

SignatureNameDescription
VFS()VFS
~VFS()~VFS

Public functions

ReturnsNameDescription
VFS&Get
VFS*TryGetNull-safe variant for code that may run before the engine (or a test) constructs the instance.
voidInitialize
voidShutdown
voidMountHigher priority mounts are checked first, which is how overlays win over the archive they shadow.
voidUnmountDrop EVERY file system at this mount point.
voidUnmountDrop one file system from a shared mount point — "Content" carries both the engine archive and the open project's loose files, and a project close must not take the engine's with it.
voidUnmountAll
voidMountEmbeddedContentMounts one embedded content set at FEmbeddedContentRegistry::kMountPriority.
voidRemoveNativeRootFallbackInitialize mounts the working directory at the root as the lowest priority fallback, so any relative key no archive holds is read loose off the disk.
boolHasNativeRootFallback
std::vector<FMountInfo>GetMounts
voidDumpMountsLogs the mount table and cache occupancy — vfs.DumpMounts at the console; vfs.LogMisses 1 additionally logs every failed Open with the mounts that were tried.
Scope<IFile>Open
boolExists
boolIsDirectory
boolIsFile
FileInfoGetFileInfo
std::vector<FileInfo>ListDirectoryThe union of every matching mount's listing, one entry per name with the highest-priority mount's winning, sorted by name.
std::vector<uint8_t>ReadFile
boolTryReadFileFalse when the file cannot be opened; an existing empty file fills outData with nothing and returns true.
std::shared_ptr<const std::vector<uint8_t>>ReadFileSharedZero-copy variant — a cache hit shares the cached buffer instead of copying the whole file.
size_tReadFileRangePartial read — the bytes at [offset, offset+size) without pulling the whole file into memory.
int64_tGetFileSizeSize in bytes through the same kept handle ReadFileRange uses, so a streamer asking "how big, then give me [a, b)" opens once.
std::stringReadTextFile
boolWriteFile
boolWriteTextFile
AsyncReadHandleReadFileAsyncWhole-file reads on the compute JobSystem.
voidReadFileAsync
boolResolvePhysicalWhere path's bytes sit on disk, resolved the way Open resolves it: the first mount holding the file answers, and false when that mount cannot name a plain slice of a native file (a compressed or encrypted archive entry) — a lower mount is never consulted behind it.
boolResolvePhysicalStoredThe same lookup through IFileSystem::ResolvePhysicalStored: an encrypted, compressed or block-verified archive entry also resolves, carrying the decoder an async reader runs on the bytes it read.
uint64_tMountGenerationMoves on every Mount / Unmount, so a holder of a physical location can tell the mount table it was resolved against is gone.
uint64_tStorageReadsReads the VFS served from storage — read-cache misses and range reads, the IO queue's synchronous path included — and the bytes they returned, since start.
uint64_tStorageBytesRead
voidSetOpenOrderRecordingOpen-order recording (--record-open-order): the first time a play session asks for each relative key — an open, a whole read, a range read or the streaming queue resolving it — the key is appended.
boolIsRecordingOpenOrder
std::vector<std::string>GetOpenOrder
boolWriteOpenOrderOne key per line, first open first; false when the file cannot be written.
std::stringResolveNativePathResolve VFS path to an absolute native filesystem path (skips pak mounts).
voidSetCacheEnabled
boolIsCacheEnabled
voidSetCacheMaxEntries
voidSetCacheMaxMemory
voidInvalidateCache
voidClearCache
size_tGetCacheSize
size_tGetCacheMemoryUsage
std::stringNormalizePath
std::stringGetExtension
std::stringGetFileName
std::stringGetDirectory
std::stringJoinPath

Function details

VFS

C++
VFS()

~VFS

C++
~VFS()

Get

C++
static VFS& Get()

TryGet

C++
static VFS* TryGet()

Null-safe variant for code that may run before the engine (or a test) constructs the instance.

Initialize

C++
void Initialize()

Shutdown

C++
void Shutdown()

Mount

C++
void Mount(const std::string& mountPoint, Ref<IFileSystem> fileSystem, int priority = 0)

Higher priority mounts are checked first, which is how overlays win over the archive they shadow.

Unmount

C++
void Unmount(const std::string& mountPoint)

Drop EVERY file system at this mount point.

Unmount

C++
void Unmount(const std::string& mountPoint, const Ref<IFileSystem>& fileSystem)

Drop one file system from a shared mount point — "Content" carries both the engine archive and the open project's loose files, and a project close must not take the engine's with it.

UnmountAll

C++
void UnmountAll()

MountEmbeddedContent

C++
void MountEmbeddedContent(const FEmbeddedContentRegistry::FRegistration& registration)

Mounts one embedded content set at FEmbeddedContentRegistry::kMountPriority. Initialize mounts every registered set; FEmbeddedContentRegistry::Register calls this for a set that arrives once the VFS is up. A set already mounted is not mounted twice.

RemoveNativeRootFallback

C++
void RemoveNativeRootFallback()

Initialize mounts the working directory at the root as the lowest priority fallback, so any relative key no archive holds is read loose off the disk. A shipped game must read its content only from the signed paks: a loose file beside the package would otherwise shadow nothing yet still load, unsigned and uncompressed, for every key the cook missed. Absolute paths (saves, the per-user config) keep their passthrough.

HasNativeRootFallback

C++
bool HasNativeRootFallback() const

GetMounts

C++
std::vector<FMountInfo> GetMounts() const

DumpMounts

C++
void DumpMounts() const

Logs the mount table and cache occupancy — vfs.DumpMounts at the console; vfs.LogMisses 1 additionally logs every failed Open with the mounts that were tried.

Open

C++
Scope<IFile> Open(const std::string& path, FileMode mode = FileMode::Read)

Exists

C++
bool Exists(const std::string& path) const

IsDirectory

C++
bool IsDirectory(const std::string& path) const

IsFile

C++
bool IsFile(const std::string& path) const

GetFileInfo

C++
FileInfo GetFileInfo(const std::string& path) const

ListDirectory

C++
std::vector<FileInfo> ListDirectory(const std::string& path) const

The union of every matching mount's listing, one entry per name with the highest-priority mount's winning, sorted by name. A single mount's view was wrong for anything layered — engine locales plus project locales under one prefix, a DLC's files next to the base archive's.

ReadFile

C++
std::vector<uint8_t> ReadFile(const std::string& path)

TryReadFile

C++
bool TryReadFile(const std::string& path, std::vector<uint8_t>& outData)

False when the file cannot be opened; an existing empty file fills outData with nothing and returns true. ReadFile/ReadTextFile cannot tell those two apart.

ReadFileShared

C++
std::shared_ptr<const std::vector<uint8_t>> ReadFileShared(const std::string& path)

Zero-copy variant — a cache hit shares the cached buffer instead of copying the whole file. Returns nullptr only when the file can't be opened; an existing empty file yields an empty (cached) buffer, so it is not re-read from disk on every call. Prefer on hot paths that only need to LOOK at the bytes.

ReadFileRange

C++
size_t ReadFileRange(const std::string& path, uint64_t offset, size_t size, void* outBuffer)

Partial read — the bytes at [offset, offset+size) without pulling the whole file into memory. A native file seeks; a MEAF entry that was cooked block-compressed (the Streamable hint) decompresses only the blocks the range touches, and one that was not still answers correctly by inflating the entry. Returns the byte count actually read. Deliberately NOT cached: the callers are streamers pulling large spans they immediately hand to the GPU, and putting those through the LRU would evict everything else to hold bytes nobody reads twice. An archive entry's open handle IS kept between calls (a small per-path table), so a sequence of ranges over one entry reuses the MEAF block cache instead of reopening and re-decompressing the same block every call; a native file reopens (IFile::ShouldKeepOpenForRanges).

GetFileSize

C++
int64_t GetFileSize(const std::string& path)

Size in bytes through the same kept handle ReadFileRange uses, so a streamer asking "how big, then give me [a, b)" opens once. -1 when the file cannot be opened.

ReadTextFile

C++
std::string ReadTextFile(const std::string& path)

WriteFile

C++
bool WriteFile(const std::string& path, const void* data, size_t size)

WriteTextFile

C++
bool WriteTextFile(const std::string& path, const std::string& text)

ReadFileAsync

C++
AsyncReadHandle ReadFileAsync(const std::string& path)

Whole-file reads on the compute JobSystem. Streaming and asset loads go through StreamingIOQueue instead (priorities, cancellation, a bandwidth budget, dedicated IO workers); these are kept for one-off callers with no such needs.

ReadFileAsync

C++
void ReadFileAsync(const std::string& path, AsyncReadCallback callback)

ResolvePhysical

C++
bool ResolvePhysical(const std::string& path, FPhysicalLocation& out) const

Where path's bytes sit on disk, resolved the way Open resolves it: the first mount holding the file answers, and false when that mount cannot name a plain slice of a native file (a compressed or encrypted archive entry) — a lower mount is never consulted behind it.

ResolvePhysicalStored

C++
bool ResolvePhysicalStored(const std::string& path, FPhysicalLocation& out) const

The same lookup through IFileSystem::ResolvePhysicalStored: an encrypted, compressed or block-verified archive entry also resolves, carrying the decoder an async reader runs on the bytes it read.

MountGeneration

C++
uint64_t MountGeneration() const

Moves on every Mount / Unmount, so a holder of a physical location can tell the mount table it was resolved against is gone.

StorageReads

C++
uint64_t StorageReads() const

Reads the VFS served from storage — read-cache misses and range reads, the IO queue's synchronous path included — and the bytes they returned, since start. The async backend's reads never pass here; with the queue's AsyncBytesRead they are a level load's whole IO.

StorageBytesRead

C++
uint64_t StorageBytesRead() const

SetOpenOrderRecording

C++
void SetOpenOrderRecording(bool enabled)

Open-order recording (--record-open-order): the first time a play session asks for each relative key — an open, a whole read, a range read or the streaming queue resolving it — the key is appended. A package lays its paks out in that order (Config/OpenOrder.txt, mbt package --promote-open-order), so a level load reads forward through the archive instead of hopping across it. Native absolute paths (saves, per-user config) are not content and are never recorded.

IsRecordingOpenOrder

C++
bool IsRecordingOpenOrder() const

GetOpenOrder

C++
std::vector<std::string> GetOpenOrder() const

WriteOpenOrder

C++
bool WriteOpenOrder(const std::string& path) const

One key per line, first open first; false when the file cannot be written.

ResolveNativePath

C++
std::string ResolveNativePath(const std::string& path) const

Resolve VFS path to an absolute native filesystem path (skips pak mounts). Returns empty string if the file doesn't exist on any native mount.

SetCacheEnabled

C++
void SetCacheEnabled(bool enabled)

IsCacheEnabled

C++
bool IsCacheEnabled() const

SetCacheMaxEntries

C++
void SetCacheMaxEntries(size_t maxEntries)

SetCacheMaxMemory

C++
void SetCacheMaxMemory(size_t maxBytes)

InvalidateCache

C++
void InvalidateCache(const std::string& path)

ClearCache

C++
void ClearCache()

GetCacheSize

C++
size_t GetCacheSize() const

GetCacheMemoryUsage

C++
size_t GetCacheMemoryUsage() const

NormalizePath

C++
static std::string NormalizePath(const std::string& path)

GetExtension

C++
static std::string GetExtension(const std::string& path)

GetFileName

C++
static std::string GetFileName(const std::string& path)

GetDirectory

C++
static std::string GetDirectory(const std::string& path)

JoinPath

C++
static std::string JoinPath(const std::string& a, const std::string& b)
Generated from Filesystem/VFS.h via filesystem.json · Oct 26, 2026Version 1.0.0