IFileSystem

Source replaces the standard file handling functions (fopen etc.) with its own. The functions, members of the global IFileSystem* filesystem object, provide access to the whole engine filesystem, including cascading access through all mounted SeachPaths and access within GCF files.

You must #include "Filesystem.h" before you can use it.

Tip:If you really do want to use fopen, just do #undef fopen.

Paths IDs

In Source, the same file can exist in multiple SearchPaths. IFileSystem defines a few different access modes for determining precisely where it should look:

MOD

The gameinfo.txt (i.e. topmost) SeachPath only.

GAME

All SeachPaths, including those inside GCFs.

XGAME

Xbox 360 equivalent to GAME.

GAMEBIN

The game's \bin folder (not the engine binary folder).

DEFAULT_WRITE_PATH

Wherever the game is currently configured to write out to. Defaults to the gameinfo.txt folder.

You can get the path of the gameinfo.txt folder like this:

// server
char pGameDir[MAX_PATH];
engine->GetGameDir(&pGameDir, MAX_PATH);

// client
const char *pGameDir = engine->GetGameDirectory();

Reading files

#include "Filesystem.h"

FileHandle_t fh = filesystem->Open("gameinfo.txt","r","GAME");

int file_len = filesystem->size(fh);
char* GameInfo = new char[file_len];

filesystem->Read((void*)GameInfo,file_len,fh);

filesystem->Close(fh);

// Use GameInfo here...

delete[] GameInfo;

This code opens gameinfo.txt in read-only mode, then stores its contents in pBuf, a C string. Because the string was created with the new keyword, it is very important to call delete[] on it afterwards or the memory would be leaked.

This is always how files are read, but there is also a helper function that handles open/read/close for you in one swoop:

#include "Filesystem.h"
#include "utlbuffer.h"

CUtlBuffer buf;
filesystem->ReadFile("gameinfo.txt","GAME",buf);

char* GameInfo = new char[buf.Size()];
buf.GetString(GameInfo);

// Use GameInfo here...

delete[] GameInfo;

Todo: Is there a better way of reading from a CUtlBuffer?

Create Directory

To create a directory you need to know two things; the relative path (Can include folders, i.e. scripts/weapon.txt) containing the new directory name and Path ID where the path will be created — called a Path ID because it does not appear to be possible to create a directory using anything other than a search path id.

Default Path Ids

• DEFAULT_WRITE_PATH
• MOD
• GAME
• GAMEBIN

char * relpath = new char[1024];
V_snprintf(relpath, 1024, "stuff\\%s", "newdirectory");
filesystem->CreateDirHierarchy( relpath, "MOD" );

This code will create a newdirectory in your stuff directory, which if does not exist will be created along with newdirectory inside of your MOD directory.

Delete Directory

To remove a directory, first make sure to remove all the files in that directory. Then you can call this code:

#include "direct.h"

char *toRemove = new char[1096];
toRemove[0] = 0;
#ifndef CLIENT_DLL
  char * pGameDir = new char[1024];
  engine->GetGameDir(pGameDir, 1024);
#else
  const char *pGameDir = engine->GetGameDirectory();
#endif
V_strcat(toRemove, pGameDir);
//concatenate the rest of the directory name here
_rmdir(toRemove);

Copy File

Warning:Untested

bool CopyFile(const char *from, const char *to)
{
	Assert(from);
	Assert(to);

	CUtlBuffer buf;

	// Read in file to copy
	if(filesystem->ReadFile(from, "MOD", buf))
		return filesystem->WriteFile(to, "MOD", buf); // Write out copy

	return false;
}

File I/O

I/O Modes

r	Open a text file for reading
w	Create a text file for writing
a	Append to a text file
rb	Open a binary file for reading
wb	Create a binary file for writing
ab	Append to a binary file
r+	Open a text file for read/write
w+	Create a text file for read/write
a+	Append to or create a text file for read/write
rb+	Open a binary file for read/write
wb+	Create a binary file for read/write
ab+	Append to or create a binary file for read/write

FileHandle_t fh;
fh = filesystem->Open( "mylog.log", "a", "MOD");

if (fh)
{
    filesystem->FPrintf(fh, "%s", "Logging A Test Line...");  
    filesystem->Close(fh);
}

or

FileHandle_t fh;
fh = filesystem->Open( "mylog.log", "a", "MOD");

if (fh)
{
    char* text = "Logging A Test Line...";
    filesystem->Write(text, V_strlen(text), fh);  
    filesystem->Close(fh);
}

So in this example we open mylog.log in Append mode. Then we print the line Logging A Test Line... and close the file.

FileHandle_t File; //file wer're reading
File = filesystem->Open( "test/test.txt", "r", "MOD"); //opens a pre-made file in the MOD/test directory called test.txt
int size = filesystem->Size(File); //gets the size of the file
char *Raw = new char[ size + 1 ]; //makes a pointer array 1 bigger to sign
filesystem->Read( Raw, size, File); // reads into the pointer array, the size of the file charecters, from the file
Raw[size] = 0; //signs
Msg(Raw); //outputs to the command line

Toss this little bit of code into a function called by a ConCommand and it can spit out the contents of a file.

Search Files

To iterate through a list of files in a given Path ID you would do the following.

FileFindHandle_t findHandle;
const char *pFilename = filesystem->FindFirstEx( "*.*", "MOD", &findHandle );
while ( pFilename != NULL )
{
    pFilename = filesystem->FindNext( findHandle );
}
filesystem->FindClose( findHandle );

*.* is the wildcard to match the files against. "MOD" is the Path ID.

The value in pFilename for each filesystem->FindNext is nothing but the file name (i.e. for maps/d1_trainstation_01.bsp, pFilename would be d1_trainstation_01)

Mount Steam Application Content

The following code segment should be added to both CHLClient::Init in src\cl_dll\cdll_client_int.cpp and CServerGameDLL::DLLInit in src\dlls\GameInterface.cpp after filesystem is initialized.

	filesystem->AddSearchPath("path", "GAME");
	if(filesystem->MountSteamContent(-id)==FILESYSTEM_MOUNT_FAILED)
		return false;

path should be retrieved from Game Name Abbreviations

id should be retrieved from Steam Application IDs

- is a negative sign (Subtract) and is required to mount content properly.

Interface Details

The IFileSystem interface provides routines for accessing content on both the local drives, and in packages.

Search Paths

File paths are usually formatted as a relative path to the current folder. For example:

.\materials\Brick\brickfloor001a.vtf

Content from several sources is merged into this common root folder using search paths. This provides useful, however complex to the uninitiated, behaviour for accessing content. While the file used in the example above originates from the source 2007 shared material.gcf, not all files found in the .\materials folder will originate from the same place. Another example:

.\materials\myCustomMadeTexture.vtf

This file would most likely reside on the hard disk, in a mod folder, under its materials directory. The full path may be something like this:

C:\Program Files\Steam\SteamApps\SourceMods\MyMod\Materials\myCustomMadeTexture.vtf

The IFileSystem function GetSearchPaths retrieves a list of the search paths used to achieve this behaviour. Typical paths that would be returned:

C:\program files\steam\steamapps\sourcemods\mymod
C:\program files\steam\steamapps\username\sourcesdk\bin\orangebox\hl2

When the calling application attempts to open .\materials\myCustomMadeTexture.vtf, this first search path allows it to be interpreted as the full path. There may be many more search paths than these two. Whichever search path first finds an existing file, is the search path that is used. Hence, the order of the search paths is significant, and the GetSearchPaths function returns them in the correct order.

While this makes clear how hard disk files are found, the matter of mounted content requires further explanation.

Mounted Content

The second search path example above is what allows mounted content to be found. If one examines this folder on their hard disk, they will find little there. However, the steam file system can mount content (typically based on AppId) as paths in the local file system. When the IFileSystem is created, the content is mounted to the current directory of the calling code. Note, however that this directory should NOT be ...\orangebox\hl2. This is because the root of the associated packs are mounted to the current directory. GCFs such as the source 2007 shared material.gcf contain a folder called hl2 inside their root. When the GCF is mounted, this hl2 folder inside the gcf becomes ...orangebox\hl2. Therefore, when the IFileSystem is Loaded/Connected, the current directory should first be changed to:

C:\program files\steam\steamapps\username\sourcesdk\bin\orangebox

Or the appropriate path for the version of the source SDK being used.

Instantiating an IFileSystem

Though the IFileSystem interface cannot itself be instantiated, the closed source class that implements it can be, which provides us with a working IFileSystem. Several steps must be taken to retrieve an IFileSystem that functions as expected (functions at all).

Information that must be known:

• Whether steam is running or not
• The game directory (for example: c:\program files\steam\steamapps\sourcemods\mymod)
• the SDK base directory (C:\program files\steam\steamapps\username\sourcesdk\bin\orangebox)
• Whether or not to mount ExtraAppId

Is Steam Running?

The easiest way to do this is to check for steam.exe as a running process. However, this is not the safest way to allow the application to proceed. (For more details, see Api.cpp API::FileSystemReady in the DuctTape project). If Steam is not ready to provide the file system interface, the calling application will terminate immediately with a message printed to the debug output: "steam is not running"

Preparing the Runtime Environment

• The location of steam.dll must be in the path environment variable.
• If steam is an NT service (running in Vista) then the SteamAppUser environment variable must be set to the users name. This can be retrieved from the AutoLoginUser key in file:

steam install path\config\SteamAppData.vdf

• The SteamAppId environment variable must be set to the AppId found in the mods/games gameinfo.txt
• Set the sourcesdk environment variable to the SDK base directory
• Change the current directory to the SDK base directory

Loading the FileSystem Module

The full path of filesystem_steam.dll must be determined, which resides in the source sdk's bin directory (orangebox\bin). This file must be used from this location, or mounted content will not be retrievable.

• Call the Sys_LoadInterface function. It returns true on success:

CSysModule** module;
IFileSystem* fileSystem;
Sys_LoadInterface(fullPathToFileSystemDLL, "VFileSystem017", module, (void**)&fileSystem);

• Connect the file system. It returns true on success:

fileSystem->Connect(Sys_GetFactoryThis());

• Initialize the files system. It returns INIT_OK on success.

fileSystem->Init();

• At this point, current directory can be restored.

Mount the extra content

If SDK extra content is to be mounted, the ToolsAppID must be retrieved from gameinfo.txt. Currently it is 211.

fileSystem->MounteSteamContent(toolsAppId);

Load Search Paths

The search paths must be loaded from gameinfo.txt. For a thorough example of how this is to be done, see filesystem_init.cpp FileSystem_LoadSearchPaths in the DuctTape project. A simple explanation of how search paths are loaded can be found in the unmodified gameinfo.txt of a new mod.

See Also

• Mounting Other Content