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
Public functions
| Returns | Name | Description |
|---|---|---|
VFS& | Get | |
VFS* | TryGet | Null-safe variant for code that may run before the engine (or a test) constructs the instance. |
void | Initialize | |
void | Shutdown | |
void | Mount | Higher priority mounts are checked first, which is how overlays win over the archive they shadow. |
void | Unmount | Drop EVERY file system at this mount point. |
void | Unmount | 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. |
void | UnmountAll | |
void | MountEmbeddedContent | Mounts one embedded content set at FEmbeddedContentRegistry::kMountPriority. |
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. |
bool | HasNativeRootFallback | |
std::vector<FMountInfo> | GetMounts | |
void | DumpMounts | 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. |
Scope<IFile> | Open | |
bool | Exists | |
bool | IsDirectory | |
bool | IsFile | |
FileInfo | GetFileInfo | |
std::vector<FileInfo> | ListDirectory | The 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 | |
bool | TryReadFile | False 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>> | ReadFileShared | Zero-copy variant — a cache hit shares the cached buffer instead of copying the whole file. |
size_t | ReadFileRange | Partial read — the bytes at [offset, offset+size) without pulling the whole file into memory. |
int64_t | GetFileSize | Size in bytes through the same kept handle ReadFileRange uses, so a streamer asking "how big, then give me [a, b)" opens once. |
std::string | ReadTextFile | |
bool | WriteFile | |
bool | WriteTextFile | |
AsyncReadHandle | ReadFileAsync | Whole-file reads on the compute JobSystem. |
void | ReadFileAsync | |
bool | ResolvePhysical | 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. |
bool | ResolvePhysicalStored | 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. |
uint64_t | MountGeneration | Moves on every Mount / Unmount, so a holder of a physical location can tell the mount table it was resolved against is gone. |
uint64_t | StorageReads | 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. |
uint64_t | StorageBytesRead | |
void | SetOpenOrderRecording | 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. |
bool | IsRecordingOpenOrder | |
std::vector<std::string> | GetOpenOrder | |
bool | WriteOpenOrder | One key per line, first open first; false when the file cannot be written. |
std::string | ResolveNativePath | Resolve VFS path to an absolute native filesystem path (skips pak mounts). |
void | SetCacheEnabled | |
bool | IsCacheEnabled | |
void | SetCacheMaxEntries | |
void | SetCacheMaxMemory | |
void | InvalidateCache | |
void | ClearCache | |
size_t | GetCacheSize | |
size_t | GetCacheMemoryUsage | |
std::string | NormalizePath | |
std::string | GetExtension | |
std::string | GetFileName | |
std::string | GetDirectory | |
std::string | JoinPath |
Function details
VFS
VFS()~VFS
~VFS()Get
static VFS& Get()TryGet
static VFS* TryGet()Null-safe variant for code that may run before the engine (or a test) constructs the instance.
Initialize
void Initialize()Shutdown
void Shutdown()Mount
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
void Unmount(const std::string& mountPoint)Drop EVERY file system at this mount point.
Unmount
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
void UnmountAll()MountEmbeddedContent
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
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
bool HasNativeRootFallback() constGetMounts
std::vector<FMountInfo> GetMounts() constDumpMounts
void DumpMounts() constLogs 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
Scope<IFile> Open(const std::string& path, FileMode mode = FileMode::Read)Exists
bool Exists(const std::string& path) constIsDirectory
bool IsDirectory(const std::string& path) constIsFile
bool IsFile(const std::string& path) constGetFileInfo
FileInfo GetFileInfo(const std::string& path) constListDirectory
std::vector<FileInfo> ListDirectory(const std::string& path) constThe 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
std::vector<uint8_t> ReadFile(const std::string& path)TryReadFile
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
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
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
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
std::string ReadTextFile(const std::string& path)WriteFile
bool WriteFile(const std::string& path, const void* data, size_t size)WriteTextFile
bool WriteTextFile(const std::string& path, const std::string& text)ReadFileAsync
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
void ReadFileAsync(const std::string& path, AsyncReadCallback callback)ResolvePhysical
bool ResolvePhysical(const std::string& path, FPhysicalLocation& out) constWhere 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
bool ResolvePhysicalStored(const std::string& path, FPhysicalLocation& out) constThe 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
uint64_t MountGeneration() constMoves on every Mount / Unmount, so a holder of a physical location can tell the mount table it was resolved against is gone.
StorageReads
uint64_t StorageReads() constReads 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
uint64_t StorageBytesRead() constSetOpenOrderRecording
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
bool IsRecordingOpenOrder() constGetOpenOrder
std::vector<std::string> GetOpenOrder() constWriteOpenOrder
bool WriteOpenOrder(const std::string& path) constOne key per line, first open first; false when the file cannot be written.
ResolveNativePath
std::string ResolveNativePath(const std::string& path) constResolve 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
void SetCacheEnabled(bool enabled)IsCacheEnabled
bool IsCacheEnabled() constSetCacheMaxEntries
void SetCacheMaxEntries(size_t maxEntries)SetCacheMaxMemory
void SetCacheMaxMemory(size_t maxBytes)InvalidateCache
void InvalidateCache(const std::string& path)ClearCache
void ClearCache()GetCacheSize
size_t GetCacheSize() constGetCacheMemoryUsage
size_t GetCacheMemoryUsage() constNormalizePath
static std::string NormalizePath(const std::string& path)GetExtension
static std::string GetExtension(const std::string& path)GetFileName
static std::string GetFileName(const std::string& path)GetDirectory
static std::string GetDirectory(const std::string& path)JoinPath
static std::string JoinPath(const std::string& a, const std::string& b)