Deficuet.APFS 0.0.1-alpha.4

APFS — AzurPromilia Package File System

A read-only virtual file system for game asset packages, built on ROVFS (and therefore WinFsp). APFS is the data manager implementation: it maps a JSON-describable asset tree onto two flat, case-insensitive dictionaries and serves reads from segmented package files.

Concepts

Population workflow

The manager follows a populate first, mount once, never modify lifecycle. Entry and directory objects are created outside this project; after population they are handed to the manager, and the tree can be serialized to / deserialized from JSON (also outside this project) for persistence.

1. Create a root DirectoryData instance acting as the volume root.

2. For every file call root.AddFile(path, entry). path is the file's full path relative to the node, /-separated, and never starts with a separator; missing intermediate directories are created implicitly (case-insensitively merged). The per-directory key inserts a _{PackResName}-{offset}-{size} suffix between the file name and its extension, so identically named segments from different packages stay unique:

   root.AddFile("characters/hero/hero.bin", new SegmentedFileEntry
   {
       PackageName = "pkg001",
       ResSubPath = "characters/hero/hero.bin",
       PackResName = "pkg001",
       PathType = PathType.Static,
       Offset = 0,
       Size = 1048576,
   });
   // dictionary key: "hero_pkg001-0-1048576.bin"
   

3. Call manager.AddFileTree(root). This traverses the tree breadth-first, finalizes every node into a DirectoryView, assigns a unique IndexNumber to every file and directory (counter starts at 0, also persisted with the intermediate tree), accumulates TotalSize, and stores every node under its full path. Full paths are rooted at \ and use \ separators — this is exactly the form WinFsp passes to the file system, regardless of whether the volume is mounted on a drive letter or into an existing empty folder (the mount point prefix never reaches user mode).

4. Mount. AddFileTree may be called exactly once; the internal maps must not be modified afterwards.

All lookups (TryResolveFile, TryResolveDirectory, TryCheckNodeExists) use StringComparer.OrdinalIgnoreCase dictionaries, matching the case-insensitive volume flag applied by ROVFS.

Backing files

RootDirectoryPath must not end with a separator. Handles are opened read-only with FILE_FLAG_OVERLAPPED, so multiple segments of the same package can be read concurrently through independent handles. A missing or unreadable backing file is logged and mapped to a Win32-derived NT status.

Mounting example

var manager = new AzurPromiliaFileDataManager(rootDirectoryPath, mountPoint)
{
    GlobalTimestamp = volumeCreationFileTime,
};
manager.PackageTimestampMap["pkg001"] = packageFileTime;
manager.AddFileTree(root); // populated tree from the steps above

var fileSystem = new ReadOnlyFileSystem<
    SegmentedFileEntry, DirectoryView, SafeFileHandle, string, string>(manager);
var host = new FileSystemHost(fileSystem);
host.Mount("X:"); // or host.Mount(@"C:\Some\Empty\Folder");

Dependencies

• Deficuet.ROVFS 0.0.1-alpha.14
• NaturalSort.Extension 4.4.1
• Newtonsoft.Json 13.0.4 (used by the external serialization code, not by this library)
• System.Text.Encoding.CodePages 8.0.0
• WinFsp 2.1 must be installed on the machine.

Both libraries target netstandard2.0; Deficuet.ROVFS transitively brings in System.Memory, which Unity consumers must also ship.