9.3 - Working with Paths

When developing games that need to access files—whether save data, configuration files, or game assets—properly handling file paths is crucial. Path handling might seem simple, but it can become complex when dealing with different operating systems, relative vs. absolute paths, and ensuring your game can find its files in various deployment scenarios.

Understanding File Paths

A file path is a string that specifies the location of a file or directory in a file system. There are two main types of paths:

Absolute Paths

An absolute path provides the complete location of a file or directory from the root of the file system:

• Windows: C:\Games\MyGame\Saves\player1.sav
• macOS/Linux: /Users/username/Games/MyGame/Saves/player1.sav

Absolute paths are specific to a particular computer and file system structure.

Relative Paths

A relative path specifies the location of a file or directory relative to a current working directory:

• Saves/player1.sav (relative to the current directory)
• ../Config/settings.cfg (one directory up, then into the Config directory)

Relative paths are more portable but depend on the context of where your code is running.

The Path Class

The System.IO.Path class is your best friend when working with file paths in C#. It provides methods and properties for processing directory strings in a cross-platform way, handling differences between operating systems automatically.

Path Separators

Different operating systems use different characters to separate directories in a path:

• Windows: Backslash (\)
• macOS/Linux: Forward slash (/)

The Path class handles these differences for you:

// Path.DirectorySeparatorChar gives you the correct separator for the current platform
char separator = Path.DirectorySeparatorChar;
Console.WriteLine($"This platform uses '{separator}' as a path separator");

// Path.AltDirectorySeparatorChar gives you the alternative separator
char altSeparator = Path.AltDirectorySeparatorChar;
Console.WriteLine($"The alternative separator is '{altSeparator}'");

Combining Paths

One of the most useful methods in the Path class is Combine(), which joins path strings together using the correct separator:

// Basic path combination
string basePath = "GameData";
string savesFolder = "Saves";
string fileName = "player1.sav";

// Combines paths with the correct separator for the current platform
string savePath = Path.Combine(basePath, savesFolder, fileName);
Console.WriteLine(savePath); // GameData/Saves/player1.sav (on Unix-like systems)
                            // GameData\Saves\player1.sav (on Windows)

// Path.Combine handles trailing separators correctly
string dataPath = "GameData/";
string configPath = Path.Combine(dataPath, "Config");
Console.WriteLine(configPath); // GameData/Config (not GameData//Config)

Using Path.Combine() instead of string concatenation ensures your paths work correctly across different platforms.

Getting Path Components

The Path class provides methods to extract different parts of a path:

string fullPath = @"C:\Games\MyGame\Saves\player1.sav";

// Get just the filename with extension
string fileName = Path.GetFileName(fullPath); // player1.sav

// Get filename without extension
string fileNameWithoutExt = Path.GetFileNameWithoutExtension(fullPath); // player1

// Get just the extension
string extension = Path.GetExtension(fullPath); // .sav

// Get the directory name
string directory = Path.GetDirectoryName(fullPath); // C:\Games\MyGame\Saves

// Get the root directory
string root = Path.GetPathRoot(fullPath); // C:\

These methods work regardless of the platform your code is running on.

Normalizing and Resolving Paths

Sometimes you need to convert between relative and absolute paths, or normalize paths with unnecessary elements:

// Get the full (absolute) path from a relative path
string relativePath = "Saves/player1.sav";
string absolutePath = Path.GetFullPath(relativePath);
Console.WriteLine(absolutePath); // Converts to an absolute path based on the current directory

// Normalize a path with ".." elements
string complexPath = "GameData/Levels/../Saves/./player1.sav";
string normalizedPath = Path.GetFullPath(complexPath);
Console.WriteLine(normalizedPath); // Simplifies to GameData/Saves/player1.sav

Checking Path Validity

The Path class also helps you validate paths:

// Check if a path contains invalid characters
string suspiciousPath = "Game*Data/Save?.sav";
bool hasInvalidChars = suspiciousPath.IndexOfAny(Path.GetInvalidPathChars()) >= 0;
Console.WriteLine($"Path contains invalid characters: {hasInvalidChars}");

// Check if a filename contains invalid characters
string suspiciousFileName = "player:1.sav";
bool hasInvalidFileNameChars = suspiciousFileName.IndexOfAny(Path.GetInvalidFileNameChars()) >= 0;
Console.WriteLine($"Filename contains invalid characters: {hasInvalidFileNameChars}");

Working with Special Folders

Sometimes you need to access standard system folders. The Environment.SpecialFolder enumeration and Environment.GetFolderPath() method help with this:

// Get the user's documents folder
string documentsFolder = Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments);
Console.WriteLine($"Documents folder: {documentsFolder}");

// Get the application data folder
string appDataFolder = Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData);
Console.WriteLine($"AppData folder: {appDataFolder}");

// Create a game-specific save directory in the user's documents folder
string gameSavesFolder = Path.Combine(documentsFolder, "MyGame", "Saves");
Directory.CreateDirectory(gameSavesFolder); // Ensure it exists

// Now we can save files there
string saveFilePath = Path.Combine(gameSavesFolder, "player1.sav");
File.WriteAllText(saveFilePath, "Player save data goes here");

Using standard system folders ensures your game follows platform conventions for where to store user data.

Current Directory and Executable Path

Sometimes you need to know where your application is running from:

// Get the current working directory
string currentDir = Directory.GetCurrentDirectory();
Console.WriteLine($"Current directory: {currentDir}");

// Get the directory where the executable is located
string exeDir = AppDomain.CurrentDomain.BaseDirectory;
Console.WriteLine($"Executable directory: {exeDir}");

// These might be different depending on how the application was launched

In game development, knowing the executable location is often more reliable than the current directory, which can change depending on how the game was launched.

Path Manipulation Best Practices

Here are some best practices for working with paths in your games:

1. Always Use Path.Combine()

// Good - works cross-platform
string configPath = Path.Combine(gameDataFolder, "Config", "settings.cfg");

// Bad - platform-specific and error-prone
string configPath = gameDataFolder + "\\" + "Config" + "\\" + "settings.cfg";

2. Check for Directory Existence Before Creating Files

string saveDir = Path.Combine(gameDataFolder, "Saves");
if (!Directory.Exists(saveDir))
{
    Directory.CreateDirectory(saveDir);
}

string savePath = Path.Combine(saveDir, "player1.sav");
File.WriteAllText(savePath, "Save data here");

3. Use Path Methods for Path Manipulation

// Good - uses Path methods
string extension = Path.GetExtension(filePath);
if (extension == ".sav")
{
    // Process save file
}

// Bad - manual string manipulation
if (filePath.EndsWith(".sav"))
{
    // Process save file
}

4. Handle Path Validation

public bool IsValidFileName(string fileName)
{
    // Check for null or empty
    if (string.IsNullOrEmpty(fileName))
        return false;
        
    // Check for invalid characters
    if (fileName.IndexOfAny(Path.GetInvalidFileNameChars()) >= 0)
        return false;
        
    // Additional validation as needed
    return true;
}

5. Use Relative Paths for Portability

// Store paths relative to a known base directory
string relativePath = "Levels/Forest/map.data";

// Resolve to absolute path when needed
string absolutePath = Path.Combine(gameDataFolder, relativePath);

Practical Example: Game Asset Manager

Let's create a simple asset manager that handles file paths for different types of game assets:

public class GameAssetManager
{
    // Base directories
    private readonly string gameRootDir;
    private readonly string assetsDir;
    private readonly string savesDir;
    private readonly string configDir;
    private readonly string userContentDir;
    
    public GameAssetManager(string rootDirectory)
    {
        // Store the root game directory
        gameRootDir = rootDirectory;
        
        // Set up standard subdirectories
        assetsDir = Path.Combine(gameRootDir, "Assets");
        savesDir = Path.Combine(gameRootDir, "Saves");
        configDir = Path.Combine(gameRootDir, "Config");
        
        // User content goes in Documents for better accessibility
        string docsFolder = Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments);
        userContentDir = Path.Combine(docsFolder, "MyGame", "UserContent");
        
        // Ensure directories exist
        EnsureDirectoryExists(assetsDir);
        EnsureDirectoryExists(savesDir);
        EnsureDirectoryExists(configDir);
        EnsureDirectoryExists(userContentDir);
    }
    
    // Helper method to create directories if they don't exist
    private void EnsureDirectoryExists(string directory)
    {
        if (!Directory.Exists(directory))
        {
            try
            {
                Directory.CreateDirectory(directory);
                Console.WriteLine($"Created directory: {directory}");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error creating directory {directory}: {ex.Message}");
            }
        }
    }
    
    // Get path for a game asset
    public string GetAssetPath(string assetType, string assetName)
    {
        string assetTypeDir = Path.Combine(assetsDir, assetType);
        EnsureDirectoryExists(assetTypeDir);
        return Path.Combine(assetTypeDir, assetName);
    }
    
    // Get path for a save file
    public string GetSavePath(string saveFileName)
    {
        // Validate the filename
        if (saveFileName.IndexOfAny(Path.GetInvalidFileNameChars()) >= 0)
        {
            throw new ArgumentException("Save filename contains invalid characters");
        }
        
        // Ensure it has the correct extension
        if (!Path.GetExtension(saveFileName).Equals(".sav", StringComparison.OrdinalIgnoreCase))
        {
            saveFileName = Path.ChangeExtension(saveFileName, ".sav");
        }
        
        return Path.Combine(savesDir, saveFileName);
    }
    
    // Get path for a config file
    public string GetConfigPath(string configFileName)
    {
        return Path.Combine(configDir, configFileName);
    }
    
    // Get path for user-generated content
    public string GetUserContentPath(string contentType, string fileName)
    {
        string contentTypeDir = Path.Combine(userContentDir, contentType);
        EnsureDirectoryExists(contentTypeDir);
        return Path.Combine(contentTypeDir, fileName);
    }
    
    // List all files of a certain type
    public string[] GetFilesOfType(string directory, string searchPattern)
    {
        try
        {
            if (Directory.Exists(directory))
            {
                return Directory.GetFiles(directory, searchPattern);
            }
            return new string[0];
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error listing files in {directory}: {ex.Message}");
            return new string[0];
        }
    }
    
    // Get all save files
    public string[] GetAllSaveFiles()
    {
        return GetFilesOfType(savesDir, "*.sav");
    }
    
    // Get all user levels
    public string[] GetAllUserLevels()
    {
        return GetFilesOfType(Path.Combine(userContentDir, "Levels"), "*.level");
    }
    
    // Display the directory structure (useful for debugging)
    public void PrintDirectoryStructure()
    {
        Console.WriteLine("Game Directory Structure:");
        Console.WriteLine($"Root: {gameRootDir}");
        Console.WriteLine($"├── Assets: {assetsDir}");
        Console.WriteLine($"├── Saves: {savesDir}");
        Console.WriteLine($"├── Config: {configDir}");
        Console.WriteLine($"User Content: {userContentDir}");
    }
}

// Usage example
public class Program
{
    public static void Main()
    {
        // Initialize the asset manager with the game's root directory
        // In a real game, this might be the directory where the executable is located
        string gameRoot = AppDomain.CurrentDomain.BaseDirectory;
        GameAssetManager assetManager = new GameAssetManager(gameRoot);
        
        // Print the directory structure
        assetManager.PrintDirectoryStructure();
        
        // Get paths for different types of files
        string texturePath = assetManager.GetAssetPath("Textures", "player.png");
        string soundPath = assetManager.GetAssetPath("Sounds", "explosion.wav");
        string savePath = assetManager.GetSavePath("player1");
        string configPath = assetManager.GetConfigPath("settings.cfg");
        string userLevelPath = assetManager.GetUserContentPath("Levels", "myCustomLevel.level");
        
        Console.WriteLine("\nExample Paths:");
        Console.WriteLine($"Texture: {texturePath}");
        Console.WriteLine($"Sound: {soundPath}");
        Console.WriteLine($"Save: {savePath}");
        Console.WriteLine($"Config: {configPath}");
        Console.WriteLine($"User Level: {userLevelPath}");
        
        // Create a sample save file
        File.WriteAllText(savePath, "This is a sample save file");
        Console.WriteLine($"\nCreated sample save file at: {savePath}");
        
        // List all save files
        string[] saveFiles = assetManager.GetAllSaveFiles();
        Console.WriteLine($"\nFound {saveFiles.Length} save files:");
        foreach (string file in saveFiles)
        {
            Console.WriteLine($"- {Path.GetFileName(file)}");
        }
    }
}

This asset manager demonstrates:

1. Organizing game files into logical directories
2. Ensuring directories exist before trying to use them
3. Validating filenames
4. Standardizing file extensions
5. Separating user-generated content from game assets
6. Listing files of specific types
7. Providing a clean API for path management

Paths in Unity

Unity Relevance

Unity provides several special paths that you should use instead of hardcoded paths:

1. Application.dataPath: Points to the Assets folder in the Editor, or the game's data directory in a build.

   string dataPath = Application.dataPath;
   Debug.Log($"Data Path: {dataPath}");

2. Application.persistentDataPath: A writable location that persists between application sessions.

   string savePath = Path.Combine(Application.persistentDataPath, "Saves", "player1.sav");

3. Application.streamingAssetsPath: A read-only location for assets that are included with your build.

   string configPath = Path.Combine(Application.streamingAssetsPath, "Config", "defaultSettings.json");

4. Application.temporaryCachePath: A location for temporary files that may be cleared when the application is closed.

   string tempFile = Path.Combine(Application.temporaryCachePath, "tempData.tmp");

These paths handle the differences between platforms automatically, ensuring your game works correctly whether it's running on Windows, macOS, Linux, iOS, Android, or consoles.

// Example of a Unity-specific path manager
public class UnityPathManager : MonoBehaviour
{
    public string GetSavePath(string fileName)
    {
        string saveDir = Path.Combine(Application.persistentDataPath, "Saves");
        if (!Directory.Exists(saveDir))
        {
            Directory.CreateDirectory(saveDir);
        }
        return Path.Combine(saveDir, fileName);
    }
    
    public string GetConfigPath()
    {
        return Path.Combine(Application.streamingAssetsPath, "Config");
    }
}

Cross-Platform Path Considerations

When developing games that run on multiple platforms, keep these considerations in mind:

Path Separators

As we've seen, different operating systems use different path separators. Always use Path.Combine() instead of hardcoding separators.

Case Sensitivity

Windows file systems are case-insensitive (e.g., "Game.txt" and "game.txt" refer to the same file), but macOS and Linux file systems are case-sensitive. Always use consistent casing in your paths to avoid cross-platform issues.

// Problematic on case-sensitive file systems
if (File.Exists("Assets/textures/player.png"))
{
    // Load the texture
}

// But the actual file might be at "Assets/Textures/Player.png"

Path Length Limitations

Windows has a traditional path length limit of 260 characters (though this can be extended in newer versions). Design your directory structure to avoid extremely long paths.

Reserved Names and Characters

Different operating systems have different reserved filenames and characters. Use Path.GetInvalidFileNameChars() to check for invalid characters.

File Locking Differences

File locking behavior varies between operating systems. Windows tends to lock files more aggressively than Unix-based systems. Always close files promptly after use.

Conclusion

Proper path handling is a fundamental skill for game developers. By using the Path class and following best practices, you can create games that reliably find and manage their files across different platforms and deployment scenarios.

In the next section, we'll explore data serialization, which is the process of converting game objects and data structures into formats that can be easily saved to and loaded from files.