User Tools

Site Tools


The Drag[en]gine provides a sophisticated Virtual File System to manage resources easy across a variety of platforms and helps a lot in patching as well as allowing customers to adjust the file system structure to their needs without huge configuration works required. The various users of the Drag[en]gine ( developers, game designers and players ) see only the virtual file system provided by the game engine and work with it like with their real disk file system just with a few differencies.


Located at the heart of the Virtual File System are the Containers. A Container contributes a set of directories and files to the Virtual File System. Containers are not the same as mounting as known from Unix systems. Mounting replaces ( virtually not physically ) the content of a directory with the content of a disk drive or network drive. Containers on the other hand add their content to the already existing content in the directory they are applied to. Existing files are replaced ( again virtually ) by the new ones. Hence the order in which Containers are added to a Virtual File System is important. Containers exist in various types but all share a common property which is the base path and read/write testing. The base path indicates at which point in the Virtual File System their content is injected. The read/write testing allows the Virtual File System to test if a file can be read or written to a Container. More about this later.

Disk Container

Disk Containers are the most basic ones and simply inject the content of a physical file system directory into the Virtual File System. They take the directory ( in the form used by the operating system ) on disk they map into the base path. Disk Containers allow reading of files existing on disk as well as writing to files in existing directories. You can set a Disk Container to read-only if you want to prevent files to be written there. This is typically the case if the directory maps to a CD-Rom drive or another read-only place. The Disk Directory tests the given path for write support at the beginning and sets the read-only flag accordingly. You can change the flag at any times but you should do this not while the Container is part of the Virtual File System to not upset applications.

Memory Container

Memory Containers inject memory files into the Virtual File System. Memory files are often used in applications in the form of resources linked into the executable. Simply add a set of memory files to the container with a given path for each file to make them visible. Memory Containers are by default read-only to prevent users saving files into memory as they would be lost upon application exit. You can though turn them writable if you want to save the files afterwards somewhere on your own. Just be careful to not forget doing so or hard work of users is blown into oblivion.

Archive Container

Archives are often used to group many files into a continuous file on disk. This can be required for various reasons ranging from restrictions on the hosting platform to distribution considerations. The Archive Container takes a file path ( in the form of the native operating system ) and injects the content of the archive into the Virtual File System. And Archive Module is used to access the content of the file which allows to use any kind of archive format with this Container without having to subclass it. By default Archive Containers are read-only. If the Archive Module supports writing to an archive it is possible to set this Container to writable. Most of the time though this is not very optimal and should not be done. Better save files into a disk directory and archive them together once upon time. This Container is not implemented yet but in design phase.

Remote Directory Container

The Remote Directory Containers (URL/FTP) are something particular. They allow to inject the content of a remote directory given by an URL into the Virtual File System. Files are only downloaded and uploaded if required. This can be used to accomplish various tasks like fetching updates or writing stats to a remote server. The good thing here is that you do this by simply writing to a file in the Virtual File System not caring at all where this file is stored. The Container takes care of the naughty networking for you. This Container is not implemented yet but in design phase.

How it all works

VFS Example Scenario

VFS Example Scenario

Getting the hang on the Virtual File System can be hard at the beginning. In contrary to mounting the injecting of files is a bit a different concept although used by other games like Quake with their pak files. If a user requests to read a file with a given path from the Virtual File System a query is conducted against the Containers. Each Container is asked in the counter order they have been added ( with the last Container added being the first one to be asked followed by second last Container and so forth ) if they can deliver the requested file. If so the query stops and the file is returned to the requesting user to be read from. For writing things work similar. The Containers are queried again but this time they are first checked if they can write the given file. The first Container claiming to be able to do so wins and the query ends. The returned file can be written by the user. Imagine the Containers as metal slabs with holes. You poke with a needle through until you hit a slab blocking your needle. This one wins and delivers you the file you are looking for. For the user this is nothing else than asking to read for example “/mygame/models/player.model” but the actual file can be delivered by the Disk Container sitting on your Game-CD or on your disk installation or even from an Archive Container containing updated files. The possibilities are endless.

You could leave a comment if you were logged in.
gamedev/vfs.txt · Last modified: 2019/05/24 23:43 by dragonlord