Class FilePathUtil

Provides standardized, platform-independent access to well-known file system paths and a suite of path manipulation utilities.

Inheritance

object

FilePathUtil

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Core.Util.File

Assembly: ScyllaCore.dll

Syntax

public static class FilePathUtil

Remarks

FilePathUtil surfaces Unity application paths (data, streaming assets, persistent storage, console log) together with OS user-profile folders (documents, desktop, AppData) through a single, consistent API.

Path manipulation methods such as Normalize(string), ToForwardSlashes(string), MakeRelative(string, string), and MakeAbsolute(string, string) handle cross-platform separator differences so callers do not need to branch on RuntimePlatform.

Validation helpers (IsValidPath(string), ContainsInvalidPathChars(string), ContainsInvalidFileNameChars(string)) delegate directly to Path character sets, so they accurately reflect the current platform's constraints.

For full file read/write operations, use ScyllaFileUtil. For config-file path resolution, use ConfigFileUtil.

Fields

AltDirectorySeparator

The platform-specific alternative directory separator character. On Windows this is /; on Unix-like systems it is the same as DirectorySeparator.

Declaration

public static readonly char AltDirectorySeparator

Field Value

Type	Description
char

DirectorySeparator

The platform-specific primary directory separator character. On Windows this is </code>; on macOS and Linux this is /.

Declaration

public static readonly char DirectorySeparator

Field Value

Type	Description
char

Remarks

Prefer Normalize(string) or ToForwardSlashes(string) to convert a full path rather than using this constant directly.

InvalidFileNameChars

The set of characters that are illegal in file name components (not full paths) on the current platform, as reported by GetInvalidFileNameChars().

Declaration

public static readonly char[] InvalidFileNameChars

Field Value

Type	Description
char[]

Remarks

This is a superset of InvalidPathChars because it additionally forbids separator characters (e.g., / and </code>). Use ContainsInvalidFileNameChars(string) or GetSafeFileName(string, char) to sanitize user-supplied file name segments.

InvalidPathChars

The set of characters that are illegal in file system path strings on the current platform, as reported by GetInvalidPathChars().

Declaration

public static readonly char[] InvalidPathChars

Field Value

Type	Description
char[]

Remarks

Use ContainsInvalidPathChars(string) to test a path string against this set without enumerating the array manually.

Properties

AppDataPath

Gets the roaming application data folder for the current user.

Declaration

public static string AppDataPath { get; }

Property Value

Type	Description
string

Remarks

On Windows this is %AppData% (i.e., AppData\Roaming), on macOS it maps to ~/Library. Prefer PersistentDataPath for Unity game data; use this path only when integrating with OS-level application data conventions.

ApplicationPath

Gets the absolute path of the directory that contains the application executable (equivalent to Path.GetFullPath(".") at the time of the call).

Declaration

public static string ApplicationPath { get; }

Property Value

Type	Description
string

Remarks

In the Unity Editor this resolves to the project root directory. In a standalone build it resolves to the folder containing the executable. This is not the same as DataPath.

ConsoleLogPath

Gets the file path to Unity's console log output file on the current platform.

Declaration

public static string ConsoleLogPath { get; }

Property Value

Type	Description
string

Remarks

The path is empty on platforms that do not write a log file (e.g., WebGL). In the Editor this typically points to the Editor log rather than the player log.

DataPath

Gets Unity's Application.dataPath, which points to the Assets folder in the Editor or the *_Data folder in standalone builds.

Declaration

public static string DataPath { get; }

Property Value

Type	Description
string

Remarks

This path is read-only at runtime on most platforms. For writable user data, use PersistentDataPath instead.

DesktopPath

Gets the current user's Desktop folder path, or null on non-desktop platforms (mobile, console, server).

Declaration

public static string DesktopPath { get; }

Property Value

Type	Description
string

Remarks

Availability is gated by PlatformUtil.IsDesktop. Always check the return value for null before using it.

DocumentsPath

Gets the current user's "My Documents" folder path in a platform-specific location.

Declaration

public static string DocumentsPath { get; }

Property Value

Type	Description
string

Remarks

Typical locations: C:\Users{user}\Documents on Windows, ~/Documents on macOS. Returns an empty string on platforms where the concept does not apply (e.g., mobile or headless servers).

LocalAppDataPath

Gets the local (non-roaming) application data folder for the current user.

Declaration

public static string LocalAppDataPath { get; }

Property Value

Type	Description
string

Remarks

On Windows this is %LocalAppData% (i.e., AppData\Local). Data stored here is not synchronized to other machines via roaming profiles, making it suitable for machine-specific caches or large local datasets.

PersistentDataPath

Gets the platform-specific persistent data directory where save files, user preferences, and other durable data should be stored.

Declaration

public static string PersistentDataPath { get; }

Property Value

Type	Description
string

Remarks

This path is writable on all supported platforms and its contents survive application updates and reinstallations. Typical locations:

• Windows: %AppData%\..\LocalLow\{company}\{product}
• macOS: ~/Library/Application Support/{company}/{product}
• Linux: ~/.config/unity3d/{company}/{product}
• Android: device-specific sandboxed storage
• iOS: Documents within the app sandbox

StreamingAssetsPath

Gets the path to Unity's StreamingAssets folder, which contains read-only files bundled with the build that are accessible at runtime.

Declaration

public static string StreamingAssetsPath { get; }

Property Value

Type	Description
string

Remarks

On Android the path is a compressed APK URI; use UnityWebRequest or Application.streamingAssetsPath directly when loading on that platform. On all other platforms it is a regular file system directory.

Files in this directory are read-only at runtime. To write files, use PersistentDataPath instead.

TemporaryCachePath

Gets the path to Unity's temporary cache directory, which the operating system may clear at any time, especially during low-storage conditions.

Declaration

public static string TemporaryCachePath { get; }

Property Value

Type	Description
string

Remarks

Only use this directory for short-lived intermediate files (e.g., download buffers, transient processing outputs). Do not store any data here that must survive between sessions.

UserProfilePath

Gets the current user's home (profile) directory path.

Declaration

public static string UserProfilePath { get; }

Property Value

Type	Description
string

Remarks

Typical locations: C:\Users{user} on Windows, /home/{user} on Linux, /Users/{user} on macOS.

Methods

ChangeExtension(string, string)

Replaces the extension of path with newExtension, delegating to ChangeExtension(string, string).

Declaration

public static string ChangeExtension(string path, string newExtension)

Parameters

Type	Name	Description
string	path	The file path whose extension should be replaced.
string	newExtension	The replacement extension. May include or omit the leading dot; ChangeExtension(string, string) normalizes this automatically. Pass null or an empty string to remove the extension entirely.

Returns

Type	Description
string	The modified path with the new extension, or the original path when it is null or empty.

See Also

GetExtension(string)

Combine(params string[])

Combines one or more path segments into a single path string, delegating to Combine(params string[]).

Declaration

public static string Combine(params string[] paths)

Parameters

Type	Name	Description
string[]	paths	The path segments to join. If any segment is an absolute path, all preceding segments are discarded (standard Combine(string, string) behavior).

Returns

Type	Description
string	The combined path. Returns Empty when paths is null or empty.

CombineWithExtension(string, string, string)

Combines a directory path, a file name, and a file extension into a complete file path, automatically normalizing the extension to include a leading dot.

Declaration

public static string CombineWithExtension(string directory, string fileName, string extension)

Parameters

Type	Name	Description
string	directory	The directory portion of the path. May be null or empty, in which case the result contains only the file name and extension.
string	fileName	The file name without any extension. Must not be null or empty; returns Empty if it is.
string	extension	The file extension, with or without a leading dot (e.g., ".ttf" and "ttf" are both accepted). Pass null or an empty string to produce a file name with no extension.

Returns

Type	Description
string	The combined file path. Returns Empty when fileName is null or empty.

Remarks

/* Returns "Assets/Fonts/MyFont.ttf" */
var path = FilePathUtil.CombineWithExtension("Assets/Fonts", "MyFont", ".ttf");

/* Also works without leading dot. */
var path2 = FilePathUtil.CombineWithExtension("Assets/Fonts", "MyFont", "ttf");

ContainsInvalidFileNameChars(string)

Determines whether a file name string (not a full path) contains any character that is illegal in file names on the current platform.

Declaration

public static bool ContainsInvalidFileNameChars(string fileName)

Parameters

Type	Name	Description
string	fileName	The file name component to inspect (must not include directory separators).

Returns

Type	Description
bool	true if fileName contains at least one character present in InvalidFileNameChars; otherwise false. Returns false for null or empty strings.

See Also

GetSafeFileName(string, char)

ContainsInvalidPathChars(string)

ContainsInvalidPathChars(string)

Determines whether a path string contains any character that is illegal in file system paths on the current platform.

Declaration

public static bool ContainsInvalidPathChars(string path)

Parameters

Type	Name	Description
string	path	The path string to inspect.

Returns

Type	Description
bool	true if path contains at least one character present in InvalidPathChars; otherwise false. Returns false for null or empty strings.

Remarks

Uses a simple nested loop against InvalidPathChars for allocation-free checking. Call IsValidPath(string) for a combined null/empty/invalid-chars check.

GetExtension(string)

Returns the extension of the specified path string, always including the leading dot character, equivalent to GetExtension(ReadOnlySpan<char>).

Declaration

public static string GetExtension(string path)

Parameters

Type	Name	Description
string	path	The path to examine. Only the last path component is considered.

Returns

Type	Description
string	The extension including the leading dot (e.g., ".txt", ".json"). Returns Empty when path is null, empty, or has no extension.

See Also

ChangeExtension(string, string)

GetFileName(string)

GetFileName(string)

Extracts the file name and extension from the last component of the specified path, equivalent to GetFileName(ReadOnlySpan<char>).

Declaration

public static string GetFileName(string path)

Parameters

Type	Name	Description
string	path	The full or partial file path to examine. May be a relative or absolute path.

Returns

Type	Description
string	The file name with extension (e.g., "config.json"). Returns Empty when path is null, empty, or ends with a directory separator character.

See Also

GetFileNameWithoutExtension(string)

GetExtension(string)

GetFileNameWithoutExtension(string)

Extracts the file name without its extension from the last component of the specified path, equivalent to GetFileNameWithoutExtension(ReadOnlySpan<char>).

Declaration

public static string GetFileNameWithoutExtension(string path)

Parameters

Type	Name	Description
string	path	The full or partial file path to examine.

Returns

Type	Description
string	The file name without the extension (e.g., "config" from "config.json"). Returns Empty when path is null or empty.

See Also

GetFileName(string)

GetExtension(string)

GetParent(string)

Returns the directory component of the specified path, equivalent to GetDirectoryName(ReadOnlySpan<char>).

Declaration

public static string GetParent(string path)

Parameters

Type	Name	Description
string	path	The file or directory path to examine. May be absolute or relative.

Returns

Type	Description
string	The parent directory portion of path, or null when the path is null, empty, or represents a root (e.g., C:</code>).

GetRoot(string)

Returns the root portion of the specified path (e.g., C:</code> on Windows or / on Unix), equivalent to GetPathRoot(ReadOnlySpan<char>).

Declaration

public static string GetRoot(string path)

Parameters

Type	Name	Description
string	path	The absolute or relative path to examine.

Returns

Type	Description
string	The root directory component of path (e.g., "C:" or "/"), or null when path is null, empty, or represents a relative path with no root.

See Also

IsRootPath(string)

IsAbsolutePath(string)

GetSafeFileName(string, char)

Replaces every character in fileName that is illegal on the current platform with the specified replacement character, producing a file name that can safely be used without throwing an I/O exception.

Declaration

public static string GetSafeFileName(string fileName, char replacement = '_')

Parameters

Type	Name	Description
string	fileName	The raw file name (without directory path) to sanitize. Must not include directory separator characters; those would also be treated as invalid and replaced.
char	replacement	The character to substitute for each illegal character. Defaults to '_'. Ensure the replacement character is itself valid; passing another invalid character will produce a file name that still fails.

Returns

Type	Description
string	A new string with all illegal characters replaced. Returns the original string unchanged when fileName is null or empty (the original reference is returned, not a copy).

See Also

ContainsInvalidFileNameChars(string)

GetUniqueFileName(string, string)

Generates a file path that does not currently exist on disk by appending an incrementing counter suffix (_1, _2, …) to the base file name until a non-existing name is found.

Declaration

public static string GetUniqueFileName(string directory, string fileName)

Parameters

Type	Name	Description
string	directory	The directory in which the file will reside. May be null or empty, in which case only the file name is used (relative to the working directory).
string	fileName	The desired file name, including extension (e.g., "save.json"). If the file does not already exist in directory, this name is returned unchanged.

Returns

Type	Description
string	A full file path that does not exist on disk at the time of the call. The counter suffix is capped at 9999; if all variants up to that number already exist, the last attempted path is returned. Returns the original fileName when it is null or empty.

Remarks

There is an inherent TOCTOU (time-of-check / time-of-use) race condition: another process may create the returned path between this call and the caller actually creating the file. For atomic creation, open the file with CreateNew and handle IOException instead.

IsAbsolutePath(string)

Determines whether the specified path is rooted (absolute), equivalent to IsPathRooted(ReadOnlySpan<char>).

Declaration

public static bool IsAbsolutePath(string path)

Parameters

Type	Name	Description
string	path	The path to examine.

Returns

Type	Description
bool	true if path is an absolute path (begins with a root such as C:</code> or /); otherwise false. Also returns false when path is null or empty.

See Also

MakeAbsolute(string, string)

IsRootPath(string)

IsRootPath(string)

Determines whether the specified path is exactly a file system root (e.g., "C:" on Windows or "/" on Unix) rather than a path that merely has a root prefix.

Declaration

public static bool IsRootPath(string path)

Parameters

Type	Name	Description
string	path	The path to examine.

Returns

Type	Description
bool	true when path equals its own root component (i.e., it has no additional directory or file components); otherwise false. Also returns false when path is null or empty.

See Also

GetRoot(string)

IsAbsolutePath(string)

IsValidPath(string)

Determines whether a path string is non-empty and contains only characters that are legal in file system paths on the current platform.

Declaration

public static bool IsValidPath(string path)

Parameters

Type	Name	Description
string	path	The path string to validate.

Returns

Type	Description
bool	true if path is neither null nor empty and does not contain any character from InvalidPathChars; otherwise false.

Remarks

This method only validates the character set. It does not verify that the path actually exists or that the caller has the necessary permissions. For existence checks, use Exists(string) or DirectoryExists(string).

See Also

ContainsInvalidPathChars(string)

IsAbsolutePath(string)

MakeAbsolute(string, string)

Resolves relativePath against basePath to produce a canonicalized absolute path, collapsing any .. segments.

Declaration

public static string MakeAbsolute(string basePath, string relativePath)

Parameters

Type	Name	Description
string	basePath	The base directory from which to resolve the relative path. When null or empty, relativePath is returned as-is without further processing.
string	relativePath	The relative path to resolve. If this is already an absolute path it is returned unchanged. When null or empty, basePath is returned.

Returns

Type	Description
string	The fully-qualified absolute path produced by combining basePath and relativePath and passing the result through GetFullPath(string).

See Also

MakeRelative(string, string)

MakeRelative(string, string)

Computes the relative path from basePath to targetPath using URI-based path relativity.

Declaration

public static string MakeRelative(string basePath, string targetPath)

Parameters

Type	Name	Description
string	basePath	The directory to use as the starting point. Must be an absolute path. A trailing separator is appended internally if missing.
string	targetPath	The target file or directory path to express as relative to basePath. Must be an absolute path on the same URI scheme.

Returns

Type	Description
string	A relative path string (e.g., "../sibling/file.txt") that, when resolved from basePath, points to targetPath. Returns targetPath unchanged if either argument is null or empty, if the two paths use different URI schemes, or if an exception occurs during URI construction.

See Also

MakeAbsolute(string, string)

Normalize(string)

Normalizes all directory separator characters in a path to the platform-specific DirectorySeparator, and removes any trailing separator character unless the path is a root (e.g., C:</code> or /).

Declaration

public static string Normalize(string path)

Parameters

Type	Name	Description
string	path	The path to normalize. Both backslash and forward-slash variants are replaced.

Returns

Type	Description
string	The normalized path. Returns the original value unchanged when path is null or empty.

See Also

ToForwardSlashes(string)

ToBackSlashes(string)

ToBackSlashes(string)

Converts all forward slash directory separators in a path to backslashes, producing a Windows-native path string.

Declaration

public static string ToBackSlashes(string path)

Parameters

Type	Name	Description
string	path	The path to convert.

Returns

Type	Description
string	The path with all forward slashes replaced by backslashes. Returns the original value unchanged when path is null or empty.

See Also

ToForwardSlashes(string)

Normalize(string)

ToForwardSlashes(string)

Converts all backslash directory separators in a path to forward slashes, making the path safe for use in URLs, Unity asset paths, and Unix-style APIs.

Declaration

public static string ToForwardSlashes(string path)

Parameters

Type	Name	Description
string	path	The path to convert.

Returns

Type	Description
string	The path with all backslashes replaced by forward slashes. Returns the original value unchanged when path is null or empty.

See Also

ToBackSlashes(string)

Normalize(string)