ScyllaFileUtil is the primary entry point for all file work in Scylla. All operations are routed through the internal Scylla.Core.Util.File.FileIOUtil layer, which handles path validation (including path-traversal detection), setting resolution, directory creation, and uniform exception wrapping via FileException.

Every public method follows one of three patterns:

Throwing - validates inputs and throws FileException on failure (e.g., ReadText, WriteBytes). Use these when the caller must handle all errors.
Try-pattern - returns a bool and exposes the result via an out parameter (e.g., TryReadText, TryReadBytes). Use these in non-critical paths where failure is an expected outcome.
Result-returning - returns a SerializationResult<T> that carries either the value or an error message without throwing (e.g., LoadObject, LoadSecureObject).

Async variants exist for all major operations. They open file streams with the async flag enabled for true non-blocking I/O; however, because Unity's texture encoding API (Texture2D.EncodeToJPG etc.) is main-thread-only, image encoding (save) is always performed synchronously before the async write.

Settings: Pass a FileSettings to control buffer size, encoding, share mode, directory creation, and flush behavior. Pass null to use Default (UTF-8, 64KB buffer, read-share, auto directory creation).

Security: Path inputs are validated against invalid characters and .. traversal sequences before any I/O takes place. Passwords passed to encryption methods must be non-empty.

For path manipulation utilities, see FilePathUtil. For image format details, see ImageFileFormat and ImageFileSettings.

Methods

AppendLine(string, string)

Appends a single line of text (followed by a platform line ending) to the end of a file, creating the file if it does not yet exist. Uses default settings.

Declaration

public static void AppendLine(string path, string line)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to append to.
string	line	The text to write as a line. A null value writes a blank line.

Remarks

This method is designed for incremental log file growth. For log rotation support, call RotateFile(string, int, long) before appending.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

AppendLine(string, string, FileSettings)

Appends a single line of text (followed by a platform line ending) to the end of a file, creating the file if it does not yet exist, using the provided settings.

Declaration

public static void AppendLine(string path, string line, FileSettings settings)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to append to.
string	line	The text to write as a line. A null value writes a blank line.
FileSettings	settings	File I/O settings. Pass null for Default.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

AppendLineAsync(string, string, FileSettings, CancellationToken)

Asynchronously appends a line to a text file using the specified settings. If the file does not exist it is created. Parent directories are created automatically when CreateDirectories is true (the default).

Declaration

public static Task AppendLineAsync(string path, string line, FileSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to append to.
string	line	The text to append, followed by the platform line terminator. May be null or empty to append a blank line.
FileSettings	settings	File I/O settings controlling encoding, buffer size, share mode, and flush behavior. Pass null for Default.
CancellationToken	cancellationToken	Token that can cancel the operation before the write begins. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task	A Task representing the append operation.

Exceptions

Type	Condition
FileException	Thrown with OperationCancelled on cancellation, or with other codes for path validation or file I/O errors.

AppendLineAsync(string, string, CancellationToken)

Asynchronously appends a line to a text file using default settings. If the file does not exist it is created. Parent directories are created automatically. This is a convenience overload of AppendLineAsync(string, string, FileSettings, CancellationToken).

Declaration

public static Task AppendLineAsync(string path, string line, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to append to.
string	line	The text to append, followed by the platform line terminator. May be null or empty to append a blank line.
CancellationToken	cancellationToken	Token that can cancel the operation before the write begins. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task	A Task representing the append operation.

Exceptions

Type	Condition
FileException	Thrown with OperationCancelled on cancellation, or with other codes for path validation or file I/O errors.

AppendLines(string, IEnumerable<string>)

Appends multiple lines to a file.

Declaration

public static void AppendLines(string path, IEnumerable<string> lines)

Parameters

Type	Name	Description
string	path	The path to the file.
IEnumerable<string>	lines	The lines to append.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

AppendLines(string, IEnumerable<string>, FileSettings)

Appends multiple lines to a file with specified settings.

Declaration

public static void AppendLines(string path, IEnumerable<string> lines, FileSettings settings)

Parameters

Type	Name	Description
string	path	The path to the file.
IEnumerable<string>	lines	The lines to append.
FileSettings	settings	The settings to use, or null for defaults.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

AppendLinesAsync(string, IEnumerable<string>, FileSettings, CancellationToken)

Asynchronously appends multiple lines to a text file using the specified settings. If the file does not exist it is created. The lines sequence is materialized into a list before the async write to prevent multiple enumeration of the source collection.

Declaration

public static Task AppendLinesAsync(string path, IEnumerable<string> lines, FileSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to append to.
IEnumerable<string>	lines	The sequence of lines to append. Must not be null. Each element is written followed by the platform line terminator.
FileSettings	settings	File I/O settings controlling encoding, buffer size, share mode, and flush behavior. Pass null for Default.
CancellationToken	cancellationToken	Token that can cancel the operation before the write begins. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task	A Task representing the append operation.

Exceptions

Type	Condition
FileException	Thrown with NullData if `lines` is null, OperationCancelled on cancellation, or other codes for path validation or file I/O errors.

AppendLinesAsync(string, IEnumerable<string>, CancellationToken)

Asynchronously appends multiple lines to a text file using default settings. If the file does not exist it is created. The sequence is materialized before writing to avoid multiple enumeration. This is a convenience overload of AppendLinesAsync(string, IEnumerable<string>, FileSettings, CancellationToken).

Declaration

public static Task AppendLinesAsync(string path, IEnumerable<string> lines, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to append to.
IEnumerable<string>	lines	The sequence of lines to append. Must not be null. Each element is written followed by the platform line terminator.
CancellationToken	cancellationToken	Token that can cancel the operation before the write begins. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task	A Task representing the append operation.

Exceptions

Type	Condition
FileException	Thrown with NullData if `lines` is null, OperationCancelled on cancellation, or other codes for file I/O errors.

AppendText(string, string)

Appends raw text to the end of a file without adding a trailing line ending, creating the file if it does not yet exist. Uses default settings.

Declaration

public static void AppendText(string path, string text)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to append to.
string	text	The text to append verbatim. A null value appends an empty string (no bytes written). Use AppendLine(string, string) if a line terminator is needed.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

AppendText(string, string, FileSettings)

Appends raw text to the end of a file without adding a trailing line ending, creating the file if it does not yet exist, using the provided settings.

Declaration

public static void AppendText(string path, string text, FileSettings settings)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to append to.
string	text	The text to append verbatim. A null value appends nothing.
FileSettings	settings	File I/O settings. Pass null for Default.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

AppendTextAsync(string, string, FileSettings, CancellationToken)

Asynchronously appends raw text to the end of a file without adding a trailing line ending, creating the file if it does not yet exist, using the specified settings. Use AppendLineAsync(string, string, FileSettings, CancellationToken) when a trailing newline is required.

Declaration

public static Task AppendTextAsync(string path, string text, FileSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to append to.
string	text	The text to append verbatim. A null value appends nothing.
FileSettings	settings	File I/O settings controlling encoding, buffer size, share mode, and flush behavior. Pass null for Default.
CancellationToken	cancellationToken	Token that can cancel the operation before writing begins. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task	A Task representing the append operation.

Exceptions

Type	Condition
FileException	Thrown with OperationCancelled on cancellation, or other codes for path validation or file I/O errors.

AppendTextAsync(string, string, CancellationToken)

Asynchronously appends raw text to the end of a file without adding a trailing line ending, creating the file if it does not yet exist, using default settings. This is a convenience overload of AppendTextAsync(string, string, FileSettings, CancellationToken).

Declaration

public static Task AppendTextAsync(string path, string text, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to append to.
string	text	The text to append verbatim. A null value appends nothing.
CancellationToken	cancellationToken	Token that can cancel the operation before writing begins. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task	A Task representing the append operation.

Exceptions

Type	Condition
FileException	Thrown with OperationCancelled on cancellation, or other codes for path validation or file I/O errors.

CombinePath(params string[])

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

Declaration

public static string CombinePath(params string[] paths)

Parameters

Type	Name	Description
string[]	paths	The path segments to combine. If any segment is an absolute path, all preceding segments are discarded.

Returns

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

CopyFile(string, string)

Copies a file from source to destination, using default settings (overwrite enabled, timestamps preserved, auto directory creation).

Declaration

public static void CopyFile(string source, string destination)

Parameters

Type	Name	Description
string	source	The absolute or relative path of the source file.
string	destination	The absolute or relative path of the destination file.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

CopyFile(string, string, FileSettings)

Copies a file from source to destination using the provided settings.

Declaration

public static void CopyFile(string source, string destination, FileSettings settings)

Parameters

Type	Name	Description
string	source	The absolute or relative path of the source file.
string	destination	The absolute or relative path of the destination file.
FileSettings	settings	File I/O settings that control overwrite behavior, directory creation, and timestamp preservation. Pass null for Default.

Exceptions

Type	Condition
FileException	Thrown when the source file is not found, the destination exists and OverwriteExisting is false, or any other I/O error occurs.

CopyFileAsync(string, string, FileSettings, IProgress<FileProgress>, CancellationToken)

Asynchronously copies a file from source to destination in buffered chunks, with optional progress reporting.

Declaration

public static Task CopyFileAsync(string source, string destination, FileSettings settings, IProgress<FileProgress> progress = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	source	The absolute or relative path of the source file.
string	destination	The absolute or relative path of the destination file.
FileSettings	settings	File I/O settings controlling buffer size, overwrite behavior, timestamp preservation, and directory creation. Pass null for Default.
IProgress<FileProgress>	progress	Optional progress reporter. Reports bytes copied and total source file size after each buffer chunk.
CancellationToken	cancellationToken	Token that cancels the operation. On cancellation, the partially written destination file is deleted (cleanup errors are suppressed) and a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task	A Task representing the copy operation.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

CopyFileAsync(string, string, CancellationToken)

Asynchronously copies a file from source to destination using default settings.

Declaration

public static Task CopyFileAsync(string source, string destination, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	source	The absolute or relative path of the source file.
string	destination	The absolute or relative path of the destination file.
CancellationToken	cancellationToken	Token that cancels the operation. On cancellation, any partially written destination file is deleted automatically.

Returns

Type	Description
Task	A Task representing the copy operation.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

DeleteFile(string)

Deletes the specified file. Does nothing if the file does not exist, so it is safe to call unconditionally.

Declaration

public static void DeleteFile(string path)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to delete.

Exceptions

Type	Condition
FileException	Thrown when the path is invalid or access is denied. Does not throw when the file simply does not exist.

DetectImageFormat(byte[])

Attempts to identify the ImageFileFormat of a byte array by inspecting its magic bytes (file signature header). This is the reliable detection path for data loaded without a file path.

Declaration

public static ImageFileFormat? DetectImageFormat(byte[] data)

Parameters

Type	Name	Description
byte[]	data	The raw image file bytes to inspect. The first few bytes are examined for known format signatures (e.g., PNG header `0x89 0x50 0x4E 0x47`, JPEG SOI marker `0xFF 0xD8`, EXR magic `0x76 0x2F 0x31 0x01`). Note that TGA has no standardized magic bytes and cannot be detected from data alone.

Returns

Type	Description
ImageFileFormat?	The detected ImageFileFormat, or null when the data is null, too short to read a signature, or does not match any known format header.

DetectImageFormat(string)

Determines the ImageFileFormat from a file path's extension. This is the preferred detection path when a file path is available, because it also works for TGA files, which have no magic bytes.

Declaration

public static ImageFileFormat? DetectImageFormat(string path)

Parameters

Type	Name	Description
string	path	The file path whose extension is used for format detection. Recognized extensions are `.png`, `.jpg`, `.jpeg`, `.webp`, `.exr`, and `.tga` (case-insensitive).

Returns

Type	Description
ImageFileFormat?	The ImageFileFormat corresponding to the extension, or null when `path` is null, has no extension, or has an unrecognized extension.

DirectoryExists(string)

Determines whether a directory exists at the specified path without throwing exceptions. Safe to call with null or empty strings.

Declaration

public static bool DirectoryExists(string path)

Parameters

Type	Name	Description
string	path	The path to test.

Returns

Type	Description
bool	true if a directory exists at `path`; false when the path is null, empty, or no directory exists.

Declaration

public static void EnsureDirectoryExists(string path)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the directory to create.

Exceptions

Type	Condition
FileException	Thrown when directory creation fails.

EnsureParentDirectoryExists(string)

Ensures that the directory containing the specified file path exists, creating any missing intermediate directories. This is a convenience wrapper for use before writing a file to a path whose parent directory may not exist.

Declaration

public static void EnsureParentDirectoryExists(string filePath)

Parameters

Type	Name	Description
string	filePath	The absolute or relative path of the file whose parent directory should be guaranteed to exist. The file itself is not created.

Exceptions

Type	Condition
FileException	Thrown when directory creation fails.

EnumerateLines(string)

Returns a lazily-evaluated sequence that yields lines from the specified text file one at a time, keeping only a single buffer in memory at any given moment. Uses default settings.

Declaration

public static IEnumerable<string> EnumerateLines(string path)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the text file.

Returns

Type	Description
IEnumerable<string>	An IEnumerable<T> of string that yields each line as the caller iterates. The file is opened when enumeration begins and closed when enumeration ends or is abandoned.

Remarks

Unlike ReadLines(string), this method does not load the entire file into memory up front. Prefer it for large files where only a subset of lines will be consumed. Note that the file stream remains open for the duration of enumeration.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

EnumerateLines(string, FileSettings)

Returns a lazily-evaluated sequence that yields lines from the specified text file one at a time using the provided settings.

Declaration

public static IEnumerable<string> EnumerateLines(string path, FileSettings settings)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the text file.
FileSettings	settings	File I/O settings controlling encoding, buffer size, and share mode. Pass null for Default.

Returns

Type	Description
IEnumerable<string>	An IEnumerable<T> of string lines. The file stream is opened on first iteration and disposed in the `finally` block at the end of enumeration.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

Exists(string)

Determines whether a file exists at the specified path without throwing exceptions. Safe to call with null or empty strings.

Declaration

public static bool Exists(string path)

Parameters

Type	Name	Description
string	path	The path to test.

Returns

Type	Description
bool	true if a file exists at `path`; false when the path is null, empty, or no file exists.

GetAvailableDiskSpace(string)

Returns the number of available free bytes on the drive that contains the specified path.

Declaration

public static long GetAvailableDiskSpace(string path)

Parameters

Type	Name	Description
string	path	Any path on the drive to query. Only the root component is used; the path itself need not exist.

Returns

Type	Description
long	The available free space in bytes as reported by AvailableFreeSpace, or `-1` when the path is null, empty, the drive root cannot be determined, the drive is not ready, or any exception occurs.

GetCreationTime(string)

Returns the creation time of the specified file in local time.

Declaration

public static DateTime GetCreationTime(string path)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the file.

Returns

Type	Description
DateTime	A DateTime in local time representing when the file was created.

Exceptions

Type	Condition
FileException	Thrown when the file is not found or cannot be accessed.

GetFileSize(string)

Returns the size of the specified file in bytes.

Declaration

public static long GetFileSize(string path)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the file.

Returns

Type	Description
long	The file size in bytes as reported by Length.

Exceptions

Type	Condition
FileException	Thrown when the file is not found or cannot be accessed.

GetFilesByAge(string, string, bool)

Returns all files in a directory matching a wildcard pattern, sorted by their last-write time.

Declaration

public static string[] GetFilesByAge(string directory, string pattern, bool ascending = true)

Parameters

Type	Name	Description
string	directory	The directory to search.
string	pattern	A wildcard file name pattern (e.g., `".log"`, `"session_"`).
bool	ascending	true to sort from oldest to newest (default); false to sort from newest to oldest.

Returns

Type	Description
string[]	An array of full file paths sorted by last-write time in the requested order. Returns Empty<T>() when either argument is null or empty, the directory does not exist, no files match, or an exception occurs.

GetLastWriteTime(string)

Returns the last-write time of the specified file in local time.

Declaration

public static DateTime GetLastWriteTime(string path)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the file.

Returns

Type	Description
DateTime	A DateTime in local time representing when the file was last written.

Exceptions

Type	Condition
FileException	Thrown when the file is not found or cannot be accessed.

GetOldestFile(string, string)

Returns the path of the file with the earliest last-write timestamp among all files in directory matching pattern.

Declaration

public static string GetOldestFile(string directory, string pattern)

Parameters

Type	Name	Description
string	directory	The directory to search. Returns null if the directory does not exist.
string	pattern	A wildcard pattern to match file names (e.g., `"*.log"`).

Returns

Type	Description
string	The full path of the oldest file by last-write time, or null when either argument is null or empty, the directory does not exist, no files match, or an exception occurs.

GetSafeFileName(string)

Returns a sanitized copy of a file name with all characters that are illegal on the current platform replaced by an underscore, using the default replacement character.

Declaration

public static string GetSafeFileName(string fileName)

Parameters

Type	Name	Description
string	fileName	The raw file name component (not a full path) to sanitize.

Returns

Type	Description
string	A file name safe for use on the current platform. Returns the original value unchanged when it is null or empty.

GetUniqueFileName(string)

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

Declaration

public static string GetUniqueFileName(string path)

Parameters

Type	Name	Description
string	path	The full file path (directory + file name + extension) to make unique. Returned unchanged when the file does not already exist.

Returns

Type	Description
string	A full file path guaranteed not to exist at the time of the call.

Remarks

The counter is capped at 9999 to prevent runaway loops. There is an inherent TOCTOU race condition; see GetUniqueFileName(string, string) for details.

HasSufficientDiskSpace(string, long)

Determines whether at least requiredBytes of disk space are available on the drive containing path.

Declaration

public static bool HasSufficientDiskSpace(string path, long requiredBytes)

Parameters

Type	Name	Description
string	path	Any path on the drive to check.
long	requiredBytes	The minimum number of bytes required.

Returns

Type	Description
bool	true when sufficient space is available, or when the available space cannot be determined (the method defaults to assuming space is available rather than blocking the operation). Returns false only when the available space is known and is less than `requiredBytes`.

IsImageFormatSupported(ImageFileFormat)

Determines whether the specified ImageFileFormat is available for encoding in the current Unity runtime environment.

Declaration

public static bool IsImageFormatSupported(ImageFileFormat format)

Parameters

Type	Name	Description
ImageFileFormat	format	The image format to query.

Returns

Type	Description
bool	true if the format can be used for encoding on the current platform and Unity version; false otherwise. In particular, WEBP requires Unity 2021.2 or later and will return false on older versions. PNG, JPG, EXR, and TGA are supported in all Unity 6.3+ builds.

LoadCompressed(string)

Reads a compressed file from disk and decompresses it using default settings. The compressed format is auto-detected by ScyllaCompression from the data header. This is a convenience overload of LoadCompressed(string, CompressionSettings).

Declaration

public static byte[] LoadCompressed(string path)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the compressed file to read.

Returns

Type	Description
byte[]	The decompressed raw byte array. The returned array is always a new allocation.

Exceptions

Type	Condition
FileException	Thrown with CompressionFailed if decompression fails, or with other codes for file I/O errors.

LoadCompressed(string, CompressionSettings)

Reads a compressed file from disk and decompresses it using the specified compression settings. Pass null for compressionSettings to let ScyllaCompression auto-detect the algorithm from the data header.

Declaration

public static byte[] LoadCompressed(string path, CompressionSettings compressionSettings)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the compressed file to read.
CompressionSettings	compressionSettings	Settings that specify the expected compression algorithm and parameters. Pass null to auto-detect from the file data header.

Returns

Type	Description
byte[]	The decompressed raw byte array.

Exceptions

Type	Condition
FileException	Thrown with CompressionFailed if decompression fails, or with other codes for path validation and file I/O errors.

LoadCompressedAsync(string, CompressionSettings, CancellationToken)

Asynchronously reads a compressed file and decompresses it using the specified compression settings. Both the file read and the decompression step are performed asynchronously.

Declaration

public static Task<byte[]> LoadCompressedAsync(string path, CompressionSettings compressionSettings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the compressed file to read.
CompressionSettings	compressionSettings	Settings specifying the expected compression algorithm. Pass null to auto-detect the algorithm from the data header.
CancellationToken	cancellationToken	Token that can cancel the operation. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task<byte[]>	A Task<TResult> whose result is the decompressed byte array.

Exceptions

Type	Condition
FileException	Thrown with CompressionFailed on failure, OperationCancelled on cancellation, or with other codes for path validation or file I/O errors.

LoadCompressedAsync(string, CancellationToken)

Asynchronously reads a compressed file and decompresses it using default (auto-detect) settings. Both the file read and the decompression step are performed asynchronously. This is a convenience overload of LoadCompressedAsync(string, CompressionSettings, CancellationToken).

Declaration

public static Task<byte[]> LoadCompressedAsync(string path, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the compressed file to read.
CancellationToken	cancellationToken	Token that can cancel the operation. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task<byte[]>	A Task<TResult> whose result is the decompressed byte array.

Exceptions

Type	Condition
FileException	Thrown with CompressionFailed on failure, OperationCancelled on cancellation.

LoadEncrypted(string, string)

Reads a file written by SaveEncrypted(string, byte[], string) and decrypts it using the provided password and auto-detected crypto settings. The algorithm is detected from the file header written during encryption. This is a convenience overload of LoadEncrypted(string, string, CryptoSettings).

Declaration

public static byte[] LoadEncrypted(string path, string password)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the encrypted file to read.
string	password	The password originally used to encrypt the file. Must not be null or empty.

Returns

Type	Description
byte[]	The decrypted plaintext byte array.

Exceptions

Type	Condition
FileException	Thrown with EncryptionFailed if the password is empty or decryption fails (e.g., wrong key, corrupted data), or with other codes for file I/O errors.

LoadEncrypted(string, string, CryptoSettings)

Reads an encrypted file and decrypts it using the provided password and the specified crypto settings. The algorithm is determined by cryptoSettings; pass null to auto-detect from the file header written during encryption.

Declaration

public static byte[] LoadEncrypted(string path, string password, CryptoSettings cryptoSettings)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the encrypted file to read.
string	password	The password originally used to encrypt the file. Must not be null or empty.
CryptoSettings	cryptoSettings	The expected encryption algorithm and key-derivation parameters, or null to auto-detect from the file header.

Returns

Type	Description
byte[]	The decrypted plaintext byte array.

Exceptions

Type	Condition
FileException	Thrown with EncryptionFailed if the password is empty or decryption fails, or with other codes for path validation or I/O errors.

LoadEncryptedAsync(string, string, CryptoSettings, CancellationToken)

Asynchronously reads an encrypted file and decrypts it using the provided password and the specified crypto settings. Both the file read and the decryption step are performed asynchronously.

Declaration

public static Task<byte[]> LoadEncryptedAsync(string path, string password, CryptoSettings cryptoSettings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the encrypted file to read.
string	password	The password originally used to encrypt the file. Must not be null or empty.
CryptoSettings	cryptoSettings	The expected encryption algorithm and key-derivation parameters, or null to auto-detect from the file header.
CancellationToken	cancellationToken	Token that can cancel the operation. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task<byte[]>	A Task<TResult> whose result is the decrypted plaintext byte array.

Exceptions

Type	Condition
FileException	Thrown with EncryptionFailed on empty password or decryption failure, OperationCancelled on cancellation, or with other codes for path validation or file I/O errors.

LoadEncryptedAsync(string, string, CancellationToken)

Asynchronously reads an encrypted file and decrypts it using the provided password and auto-detected crypto settings. The algorithm is detected from the file header. This is a convenience overload of LoadEncryptedAsync(string, string, CryptoSettings, CancellationToken).

Declaration

public static Task<byte[]> LoadEncryptedAsync(string path, string password, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the encrypted file to read.
string	password	The password originally used to encrypt the file. Must not be null or empty.
CancellationToken	cancellationToken	Token that can cancel the operation. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task<byte[]>	A Task<TResult> whose result is the decrypted plaintext byte array.

Exceptions

Type	Condition
FileException	Thrown with EncryptionFailed on empty password or decryption failure, OperationCancelled on cancellation.

LoadImage(string)

Loads an image file from disk and decodes it into a new UnityEngine.Texture2D using default image settings (PNG format, readable, bilinear filter, clamp wrap).

Declaration

public static Texture2D LoadImage(string path)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the image file.

Returns

Type	Description
Texture2D	A new UnityEngine.Texture2D containing the decoded image data. The caller is responsible for destroying the texture when it is no longer needed.

Exceptions

Type	Condition
FileException	Thrown with ImageDecodingFailed when the image data cannot be decoded, or with other codes for file I/O errors.

LoadImage(string, ImageFileSettings)

Loads an image file from disk and decodes it into a new UnityEngine.Texture2D using the provided image settings.

Declaration

public static Texture2D LoadImage(string path, ImageFileSettings settings)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the image file.
ImageFileSettings	settings	Image decoding settings (readable flag, mipmap generation, filter mode, etc.). Pass null for Default.

Returns

Type	Description
Texture2D	A new UnityEngine.Texture2D containing the decoded image data.

Exceptions

Type	Condition
FileException	Thrown with ImageDecodingFailed when the image data cannot be decoded, or with other codes for file I/O errors.

LoadImageAsync(string, ImageFileSettings, CancellationToken)

Asynchronously reads an image file from disk and decodes it into a new UnityEngine.Texture2D using the provided image settings. The file bytes are read on a background thread; decoding is performed on the calling thread because Unity's texture API is not thread-safe and must run on the main thread.

Declaration

public static Task<Texture2D> LoadImageAsync(string path, ImageFileSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the image file.
ImageFileSettings	settings	Image decoding settings (mipmap generation, readable flag, filter mode, wrap mode, aniso level). Pass null for Default.
CancellationToken	cancellationToken	Token that can cancel the file-read portion of the operation. If cancelled before decoding begins, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task<Texture2D>	A Task<TResult> whose result is a new UnityEngine.Texture2D containing the decoded image data. The caller is responsible for destroying the texture when it is no longer needed.

Exceptions

Type	Condition
FileException	Thrown with ImageDecodingFailed when the image data cannot be decoded, OperationCancelled when cancelled, or with other codes for file I/O errors.

LoadImageAsync(string, CancellationToken)

Asynchronously reads an image file from disk and decodes it into a new UnityEngine.Texture2D using default image settings. The file bytes are read on a background thread; decoding is performed on the calling thread because Unity's texture API is not thread-safe and must run on the main thread.

Declaration

public static Task<Texture2D> LoadImageAsync(string path, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the image file.
CancellationToken	cancellationToken	Token that can cancel the file-read portion of the operation. If cancelled before decoding begins, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task<Texture2D>	A Task<TResult> whose result is a new UnityEngine.Texture2D containing the decoded image data. The caller is responsible for destroying the texture when it is no longer needed.

Exceptions

Type	Condition
FileException	Thrown with ImageDecodingFailed when the image data cannot be decoded, OperationCancelled when cancelled, or with other codes for file I/O errors.

LoadObjectAsync<T>(string, SerializationSettings, CancellationToken)

Asynchronously reads a JSON file and deserializes its content into an object of type T using the specified serialization settings. This method never throws; all errors (file not found, invalid JSON, type mismatch, cancellation) are captured in the returned result.

Declaration

public static Task<SerializationResult<T>> LoadObjectAsync<T>(string path, SerializationSettings serializationSettings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the JSON file to read.
SerializationSettings	serializationSettings	Deserialization settings (e.g., type handling, migration). Pass null to use ScyllaSerialization defaults.
CancellationToken	cancellationToken	Token that can cancel the file-read step. If cancelled, the returned result will be a failure result with a cancellation message rather than throwing.

Returns

Type	Description
Task<SerializationResult<T>>	A Task<TResult> whose result is a SerializationResult<T> with `IsSuccess` true on success or `IsSuccess` false and an `ErrorMessage` on failure.

Type Parameters

Name	Description
T	The type to deserialize into. Must be deserializable by ScyllaSerialization.

LoadObjectAsync<T>(string, CancellationToken)

Asynchronously reads a JSON file and deserializes its content into an object of type T using default serialization settings. This method never throws; all errors are captured in the returned result. This is a convenience overload of LoadObjectAsync<T>(string, SerializationSettings, CancellationToken).

Declaration

public static Task<SerializationResult<T>> LoadObjectAsync<T>(string path, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the JSON file to read.
CancellationToken	cancellationToken	Token that can cancel the file-read step. If cancelled, the returned result will be a failure result with a cancellation message.

Returns

Type	Description
Task<SerializationResult<T>>	A Task<TResult> whose result is a SerializationResult<T> with `IsSuccess` true on success or `IsSuccess` false and an `ErrorMessage` on failure.

Type Parameters

Name	Description
T	The type to deserialize into. Must be deserializable by ScyllaSerialization.

LoadObject<T>(string)

Reads a JSON file and deserializes its content into an object of type T using default serialization settings. This method never throws; errors are captured in the returned SerializationResult<T>. This is a convenience overload of LoadObject<T>(string, SerializationSettings).

Declaration

public static SerializationResult<T> LoadObject<T>(string path)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the JSON file to read.

Returns

Type	Description
SerializationResult<T>	A SerializationResult<T> whose `IsSuccess` property is true and `Value` contains the deserialized object on success, or whose `IsSuccess` is false and `ErrorMessage` describes the failure on error.

Type Parameters

Name	Description
T	The type to deserialize into. Must be deserializable by ScyllaSerialization.

LoadObject<T>(string, SerializationSettings)

Reads a JSON file and deserializes its content into an object of type T using the specified serialization settings. This method never throws; all errors (file not found, invalid JSON, type mismatch) are captured in the returned result.

Declaration

public static SerializationResult<T> LoadObject<T>(string path, SerializationSettings serializationSettings)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the JSON file to read.
SerializationSettings	serializationSettings	Deserialization settings (e.g., type handling, migration). Pass null to use ScyllaSerialization defaults.

Returns

Type	Description
SerializationResult<T>	A SerializationResult<T> whose `IsSuccess` property is true and `Value` contains the deserialized object on success, or whose `IsSuccess` is false and `ErrorMessage` describes the failure on error.

Type Parameters

Name	Description
T	The type to deserialize into. Must be deserializable by ScyllaSerialization.

LoadSecureObjectAsync<T>(string, string, SerializationSettings, CompressionSettings, CryptoSettings, CancellationToken)

Asynchronously reads a secure file and reverses the full pipeline - decrypts, decompresses, and deserializes - using the specified settings for each step. This method never throws; all errors are captured in the returned result.

The pipeline is: ReadBytesAsync -> DecryptAsync -> DecompressAsync -> Deserialize. Pass null for any settings parameter to auto-detect or use defaults.

Declaration

public static Task<SerializationResult<T>> LoadSecureObjectAsync<T>(string path, string password, SerializationSettings serializationSettings, CompressionSettings compressionSettings, CryptoSettings cryptoSettings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the secure file to read.
string	password	The password originally used to encrypt the file. An empty or null password returns a failure result.
SerializationSettings	serializationSettings	Deserialization settings. Pass null for defaults.
CompressionSettings	compressionSettings	Decompression settings. Pass null to auto-detect from the data header.
CryptoSettings	cryptoSettings	Decryption settings. Pass null to auto-detect from the file header.
CancellationToken	cancellationToken	Token that can cancel the operation. If cancelled, the returned result is a failure result with a cancellation message rather than throwing.

Returns

Type	Description
Task<SerializationResult<T>>	A Task<TResult> whose result is a SerializationResult<T> with `IsSuccess` true on success or `IsSuccess` false on any failure.

Type Parameters

Name	Description
T	The type to deserialize into. Must be deserializable by ScyllaSerialization.

LoadSecureObjectAsync<T>(string, string, CancellationToken)

Asynchronously reads a secure file and reverses the full pipeline - decrypts, decompresses, and deserializes - using the provided password and auto-detected settings. This method never throws; all errors (file not found, wrong password, decompression failure, cancellation) are captured in the returned result. This is a convenience overload of LoadSecureObjectAsync<T>(string, string, SerializationSettings, CompressionSettings, CryptoSettings, CancellationToken).

Declaration

public static Task<SerializationResult<T>> LoadSecureObjectAsync<T>(string path, string password, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the secure file to read.
string	password	The password originally used to encrypt the file. An empty or null password returns a failure result.
CancellationToken	cancellationToken	Token that can cancel the operation. If cancelled, the returned result is a failure result with a cancellation message rather than throwing.

Returns

Type	Description
Task<SerializationResult<T>>	A Task<TResult> whose result is a SerializationResult<T> with `IsSuccess` true on success or `IsSuccess` false on any failure.

Type Parameters

Name	Description
T	The type to deserialize into. Must be deserializable by ScyllaSerialization.

LoadSecureObject<T>(string, string)

Reads a file written by SaveSecureObject<T>(string, T, string) and reverses the full pipeline - decrypts, decompresses, and deserializes - using the provided password and auto-detected settings for each step. This method never throws; all errors are captured in the returned result.

The pipeline is: ReadBytes -> Decrypt -> Decompress -> Deserialize.

Declaration

public static SerializationResult<T> LoadSecureObject<T>(string path, string password)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the secure file to read.
string	password	The password originally used to encrypt the file. An empty or null password returns a failure result.

Returns

Type	Description
SerializationResult<T>	A SerializationResult<T> with `IsSuccess` true and `Value` set on success, or `IsSuccess` false and an `ErrorMessage` on failure.

Type Parameters

Name	Description
T	The type to deserialize into. Must be deserializable by ScyllaSerialization.

LoadSecureObject<T>(string, string, SerializationSettings, CompressionSettings, CryptoSettings)

Reads a file written by SaveSecureObject<T>(string, T, string, SerializationSettings, CompressionSettings, CryptoSettings) and reverses the full pipeline - decrypts, decompresses, and deserializes - using the specified settings for each step. This method never throws; all errors are captured in the returned result.

The pipeline is: ReadBytes -> Decrypt -> Decompress -> Deserialize. Pass null for any settings to auto-detect or use defaults.

Declaration

public static SerializationResult<T> LoadSecureObject<T>(string path, string password, SerializationSettings serializationSettings, CompressionSettings compressionSettings, CryptoSettings cryptoSettings)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the secure file to read.
string	password	The password originally used to encrypt the file. An empty or null password returns a failure result.
SerializationSettings	serializationSettings	Deserialization settings. Pass null for defaults.
CompressionSettings	compressionSettings	Decompression settings. Pass null to auto-detect from the data header.
CryptoSettings	cryptoSettings	Decryption settings. Pass null to auto-detect from the file header.

Returns

Type	Description
SerializationResult<T>	A SerializationResult<T> with `IsSuccess` true and `Value` set on success, or `IsSuccess` false and an `ErrorMessage` on failure.

Type Parameters

Name	Description
T	The type to deserialize into. Must be deserializable by ScyllaSerialization.

MoveFile(string, string)

Moves a file from source to destination using default settings (overwrite enabled, auto directory creation).

Declaration

public static void MoveFile(string source, string destination)

Parameters

Type	Name	Description
string	source	The absolute or relative path of the file to move.
string	destination	The absolute or relative path of the destination.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

MoveFile(string, string, FileSettings)

Moves a file from source to destination using the provided settings. When OverwriteExisting is true, an existing destination is replaced in one step.

Declaration

public static void MoveFile(string source, string destination, FileSettings settings)

Parameters

Type	Name	Description
string	source	The absolute or relative path of the file to move.
string	destination	The absolute or relative path of the destination.
FileSettings	settings	File I/O settings. Pass null for Default.

Remarks

The overwrite goes through the framework's single-call replace rather than deleting the destination first. On the same volume that is one rename, so an interruption leaves either the old file or the new one. Deleting first opens a window in which neither exists, which is how a save interrupted at the wrong moment loses the file it was rewriting rather than merely failing to update it.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

NormalizePath(string)

Normalizes all directory separator characters in a path to the current platform's primary separator and removes any trailing separator (unless the path is a root). Delegates to the internal NormalizePath(string) implementation.

Declaration

public static string NormalizePath(string path)

Parameters

Type	Name	Description
string	path	The path to normalize.

Returns

Type	Description
string	The normalized path, or the original value when `path` is null or empty.

ReadBytes(string)

Reads the entire contents of a binary file into a byte array using default settings (64KB buffer, read-share mode).

Declaration

public static byte[] ReadBytes(string path)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the binary file.

Returns

Type	Description
byte[]	A byte[] containing all bytes of the file. The array length equals the file size at the time of reading.

Exceptions

Type	Condition
FileException	Thrown when the file is not found, access is denied, the file exceeds MaxValue bytes, or any other I/O error occurs.

ReadBytes(string, FileSettings)

Reads the entire contents of a binary file into a byte array using the provided settings.

Declaration

public static byte[] ReadBytes(string path, FileSettings settings)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the binary file.
FileSettings	settings	File I/O settings controlling buffer size and share mode. Pass null for Default.

Returns

Type	Description
byte[]	A byte[] containing all bytes of the file.

Exceptions

Type	Condition
FileException	Thrown when the file exceeds MaxValue bytes (IOError), is not found, or any other I/O error occurs.

ReadBytesAsync(string, FileSettings, CancellationToken)

Asynchronously reads the entire contents of a binary file into a byte array using the provided settings.

Declaration

public static Task<byte[]> ReadBytesAsync(string path, FileSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the binary file.
FileSettings	settings	File I/O settings. Pass null for Default.
CancellationToken	cancellationToken	Token that cancels the read. Cancellation is checked between buffer reads.

Returns

Type	Description
Task<byte[]>	A Task<TResult> that resolves to a byte[] containing all bytes of the file.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

ReadBytesAsync(string, CancellationToken)

Asynchronously reads the entire contents of a binary file into a byte array using default settings.

Declaration

public static Task<byte[]> ReadBytesAsync(string path, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the binary file.
CancellationToken	cancellationToken	Token that cancels the read. Cancellation is checked between internal buffer chunks, so very large files may not cancel immediately.

Returns

Type	Description
Task<byte[]>	A Task<TResult> that resolves to a byte[] containing all bytes of the file.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

ReadLines(string)

Reads every line from the specified text file into an array, using default settings. The file is fully buffered into memory before returning.

Declaration

public static string[] ReadLines(string path)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the text file.

Returns

Type	Description
string[]	An array of line strings. Empty lines are included. The final line terminator (if present) does not produce a trailing empty element.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

ReadLines(string, FileSettings)

Reads every line from the specified text file into an array using the provided settings. The file is fully buffered into memory before returning.

Declaration

public static string[] ReadLines(string path, FileSettings settings)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the text file.
FileSettings	settings	File I/O settings controlling encoding, buffer size, and share mode. Pass null for Default.

Returns

Type	Description
string[]	An array of line strings from the file. Empty lines are included.

Remarks

For very large files where holding all lines in memory simultaneously is undesirable, use EnumerateLines(string, FileSettings) instead.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

ReadLinesAsync(string, FileSettings, CancellationToken)

Asynchronously reads every line from the specified text file into an array using the provided settings.

Declaration

public static Task<string[]> ReadLinesAsync(string path, FileSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the text file.
FileSettings	settings	File I/O settings. Pass null for Default.
CancellationToken	cancellationToken	Token that cancels the read. Checked between lines, so cancellation latency depends on individual line lengths.

Returns

Type	Description
Task<string[]>	A Task<TResult> that resolves to an array of line strings.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

ReadLinesAsync(string, CancellationToken)

Asynchronously reads every line from the specified text file into an array, using default settings.

Declaration

public static Task<string[]> ReadLinesAsync(string path, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the text file.
CancellationToken	cancellationToken	Token that cancels the read. Cancellation is checked between each line read, so very long files may not cancel immediately.

Returns

Type	Description
Task<string[]>	A Task<TResult> that resolves to an array of line strings.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

ReadText(string)

Reads all text from the specified file using default settings (UTF-8, 64KB buffer, BOM detection enabled).

Declaration

public static string ReadText(string path)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the text file. Must not be null or empty, and must not contain invalid path characters or `..` traversal sequences.

Returns

Type	Description
string	The entire file contents as a string.

Exceptions

Type	Condition
FileException	Thrown with an appropriate FileErrorCode when the path is invalid (InvalidPath), the file is not found (FileNotFound), access is denied (AccessDenied), or any other I/O error occurs.

ReadText(string, FileSettings)

Reads all text from the specified file using the provided settings, including encoding, buffer size, and file-share mode.

Declaration

public static string ReadText(string path, FileSettings settings)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the text file. Must not be null or empty and must pass path-traversal validation.
FileSettings	settings	File I/O settings that control encoding, buffer size, and read-share mode. Pass null to use Default.

Returns

Type	Description
string	The entire file contents as a string.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

ReadText(string, Encoding)

Reads all text from the specified file using the given encoding with default buffer size and file-share settings.

Declaration

public static string ReadText(string path, Encoding encoding)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the text file.
Encoding	encoding	The character encoding to use when decoding the file bytes. When null, UTF8 is used.

Returns

Type	Description
string	The entire file contents as a string.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

ReadTextAsync(string, FileSettings, CancellationToken)

Asynchronously reads all text from the specified file using the provided settings. The file stream is opened with the async flag for non-blocking I/O.

Declaration

public static Task<string> ReadTextAsync(string path, FileSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the text file.
FileSettings	settings	File I/O settings. Pass null for Default.
CancellationToken	cancellationToken	Token that cancels the read. Cancellation is checked before opening the stream and may interrupt the async read mid-operation.

Returns

Type	Description
Task<string>	A Task<TResult> that resolves to the entire file contents as a string.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

ReadTextAsync(string, CancellationToken)

Asynchronously reads all text from the specified file using default settings.

Declaration

public static Task<string> ReadTextAsync(string path, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the text file.
CancellationToken	cancellationToken	Token that can be used to cancel the read before it completes. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task<string>	A Task<TResult> that resolves to the entire file contents as a string.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

ReadToStream(string, Stream)

Reads the contents of a file and writes them into an existing stream in buffered chunks, using default settings. Suitable for piping file data into network streams, MemoryStream, or any writable Stream.

Declaration

public static void ReadToStream(string path, Stream destination)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the source file.
Stream	destination	The writable stream to receive the file data. Must not be null. The stream's position is not reset before writing; data is appended at the current position.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

Declaration

public static void ReadToStream(string path, Stream destination, FileSettings settings, IProgress<FileProgress> progress = null)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the source file.
Stream	destination	The writable stream to receive the file data. Must not be null.
FileSettings	settings	File I/O settings controlling the buffer size and read-share mode. Pass null for Default.
IProgress<FileProgress>	progress	Optional progress reporter. Each buffer chunk written invokes Report(T) with a FileProgress value carrying the cumulative bytes written and the total file size.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

ReadToStreamAsync(string, Stream, FileSettings, IProgress<FileProgress>, CancellationToken)

Asynchronously reads a file and writes its contents into an existing stream in buffered chunks, with optional progress reporting.

Declaration

public static Task ReadToStreamAsync(string path, Stream destination, FileSettings settings, IProgress<FileProgress> progress = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the source file.
Stream	destination	The writable stream to receive the file data. Must not be null.
FileSettings	settings	File I/O settings. Pass null for Default.
IProgress<FileProgress>	progress	Optional progress reporter. Reports after each buffer chunk is written.
CancellationToken	cancellationToken	Token that cancels the operation. Checked between buffer reads/writes.

Returns

Type	Description
Task	A Task representing the read operation.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

ReadToStreamAsync(string, Stream, CancellationToken)

Asynchronously reads a file and writes its contents into an existing stream using default settings and no progress reporting.

Declaration

public static Task ReadToStreamAsync(string path, Stream destination, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the source file.
Stream	destination	The writable stream to receive the file data. Must not be null.
CancellationToken	cancellationToken	Token that cancels the operation. Cancellation is checked between buffer chunks.

Returns

Type	Description
Task	A Task representing the read operation.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

RotateFile(string, int, long)

Checks whether a log file has exceeded its maximum size and, if so, deletes it so that subsequent append operations create a fresh file.

Declaration

public static void RotateFile(string path, int maxFiles = 10, long maxFileSizeBytes = 1048576)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the log file to rotate.
int	maxFiles	Reserved for future multi-file rotation support (renaming old files to `.1`, `.2`, etc.). Currently ignored.
long	maxFileSizeBytes	The maximum file size in bytes. When the file is at least this large it is deleted. Values below 1024 are clamped to 1024. Defaults to 1 MB.

Remarks

Call this method before AppendLine(string, string) or AppendLines(string, IEnumerable<string>) at the start of each session to bound log file growth. The method is a no-op when the file does not yet exist or is within the size limit.

Exceptions

Type	Condition
FileException	Thrown when the deletion fails.

Declaration

public static void RotateFiles(string directory, string pattern, int maxFiles = 10)

Parameters

Type	Name	Description
string	directory	The directory to scan. The method returns immediately if the directory does not exist.
string	pattern	A wildcard pattern to match file names (e.g., `"log_*.txt"`). Must not be null or empty.
int	maxFiles	The maximum number of matching files to retain. Values below 1 are clamped to 1. Files beyond this limit are deleted from oldest to newest. Defaults to 10.

Exceptions

Type	Condition
FileException	Thrown when `pattern` is empty or an I/O error prevents directory enumeration. Individual file deletion errors are silently ignored.

SaveCompressed(string, byte[])

Compresses a byte array using default compression settings and writes the compressed data to a file. This is a convenience overload of SaveCompressed(string, byte[], CompressionSettings) that uses the ScyllaCompression default algorithm (GZip).

Declaration

public static void SaveCompressed(string path, byte[] data)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
byte[]	data	The raw byte array to compress. Must not be null or empty.

Exceptions

Type	Condition
FileException	Thrown with CompressionFailed if compression fails, or with other codes for file I/O errors.

SaveCompressed(string, byte[], CompressionSettings)

Compresses a byte array using the specified compression settings and writes the compressed data to a file. The algorithm and level are determined by compressionSettings; pass null to use the ScyllaCompression defaults (GZip at the default level).

Declaration

public static void SaveCompressed(string path, byte[] data, CompressionSettings compressionSettings)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
byte[]	data	The raw byte array to compress. Must not be null or empty.
CompressionSettings	compressionSettings	Compression algorithm and level configuration. Pass null to use the ScyllaCompression default settings.

Exceptions

Type	Condition
FileException	Thrown with CompressionFailed if compression fails, or with other codes for path validation or file I/O errors.

SaveCompressedAsync(string, byte[], CompressionSettings, CancellationToken)

Asynchronously compresses a byte array using the specified compression settings and writes the result to a file. Both the compression step and the file write are performed asynchronously.

Declaration

public static Task SaveCompressedAsync(string path, byte[] data, CompressionSettings compressionSettings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
byte[]	data	The raw byte array to compress. Must not be null or empty.
CompressionSettings	compressionSettings	Compression algorithm and level configuration. Pass null to use the ScyllaCompression default settings.
CancellationToken	cancellationToken	Token that can cancel the operation. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task	A Task representing the compress-and-write operation.

Exceptions

Type	Condition
FileException	Thrown with CompressionFailed on failure, OperationCancelled on cancellation, or with other codes for path validation or file I/O errors.

SaveCompressedAsync(string, byte[], CancellationToken)

Asynchronously compresses a byte array and writes the result to a file using default compression settings. Both the compression step and the file write are performed asynchronously. This is a convenience overload of SaveCompressedAsync(string, byte[], CompressionSettings, CancellationToken).

Declaration

public static Task SaveCompressedAsync(string path, byte[] data, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
byte[]	data	The raw byte array to compress. Must not be null or empty.
CancellationToken	cancellationToken	Token that can cancel the operation. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task	A Task representing the compress-and-write operation.

Exceptions

Type	Condition
FileException	Thrown with CompressionFailed on failure, OperationCancelled on cancellation.

SaveEncrypted(string, byte[], string)

Encrypts a byte array using the default ScyllaCrypto algorithm and writes the ciphertext to a file. A random salt and IV are generated and prepended to the output so that the same password produces different ciphertext on each call. This is a convenience overload of SaveEncrypted(string, byte[], string, CryptoSettings).

Declaration

public static void SaveEncrypted(string path, byte[] data, string password)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
byte[]	data	The plaintext byte array to encrypt. Must not be null or empty.
string	password	The password used to derive the encryption key via PBKDF2. Must not be null or empty; an empty password causes a FileException with EncryptionFailed.

Exceptions

Type	Condition
FileException	Thrown with EncryptionFailed if the password is empty or encryption fails, or with other codes for file I/O errors.

SaveEncrypted(string, byte[], string, CryptoSettings)

Encrypts a byte array using the specified crypto settings and writes the ciphertext to a file. A random salt and IV are generated and prepended to the output. Pass null for cryptoSettings to use the ScyllaCrypto default algorithm (AES-CBC-HMAC).

Declaration

public static void SaveEncrypted(string path, byte[] data, string password, CryptoSettings cryptoSettings)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
byte[]	data	The plaintext byte array to encrypt. Must not be null or empty.
string	password	The password used to derive the encryption key. Must not be null or empty.
CryptoSettings	cryptoSettings	Encryption algorithm and key-derivation configuration. Pass null to use ScyllaCrypto defaults.

Exceptions

Type	Condition
FileException	Thrown with EncryptionFailed if the password is empty, encryption fails, or with other codes for path validation or I/O errors.

SaveEncryptedAsync(string, byte[], string, CryptoSettings, CancellationToken)

Asynchronously encrypts a byte array using the specified crypto settings and writes the ciphertext to a file. Both the encryption and file write steps are performed asynchronously. A random salt and IV are generated and prepended to the output.

Declaration

public static Task SaveEncryptedAsync(string path, byte[] data, string password, CryptoSettings cryptoSettings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
byte[]	data	The plaintext byte array to encrypt. Must not be null or empty.
string	password	The password used to derive the encryption key. Must not be null or empty.
CryptoSettings	cryptoSettings	Encryption algorithm and key-derivation configuration. Pass null to use ScyllaCrypto defaults.
CancellationToken	cancellationToken	Token that can cancel the operation. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task	A Task representing the encrypt-and-write operation.

Exceptions

Type	Condition
FileException	Thrown with EncryptionFailed on empty password or encryption failure, OperationCancelled on cancellation, or with other codes for path validation or I/O errors.

SaveEncryptedAsync(string, byte[], string, CancellationToken)

Asynchronously encrypts a byte array using default crypto settings and writes the ciphertext to a file. This is a convenience overload of SaveEncryptedAsync(string, byte[], string, CryptoSettings, CancellationToken).

Declaration

public static Task SaveEncryptedAsync(string path, byte[] data, string password, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
byte[]	data	The plaintext byte array to encrypt. Must not be null or empty.
string	password	The password used to derive the encryption key. Must not be null or empty.
CancellationToken	cancellationToken	Token that can cancel the operation. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task	A Task representing the encrypt-and-write operation.

Exceptions

Type	Condition
FileException	Thrown with EncryptionFailed on empty password or encryption failure, OperationCancelled on cancellation.

SaveImage(string, Texture2D)

Encodes a UnityEngine.Texture2D and saves it to an image file. When no settings are provided, the output format is inferred from the file extension (e.g., .png -> PNG, .jpg/.jpeg -> JPG).

Declaration

public static void SaveImage(string path, Texture2D texture)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the image file to write.
Texture2D	texture	The texture to encode. Must not be null. Must be readable (i.e., not have the Non-Readable flag set in the import settings).

Exceptions

Type	Condition
FileException	Thrown with ImageEncodingFailed if encoding fails, or with other codes for file I/O errors.

SaveImage(string, Texture2D, ImageFileFormat)

Encodes a UnityEngine.Texture2D in the specified format and saves it to an image file using the default quality (DEFAULT_QUALITY). This is a convenience overload of SaveImage(string, Texture2D, ImageFileFormat, int) that uses quality 90 for lossy formats.

Declaration

public static void SaveImage(string path, Texture2D texture, ImageFileFormat format)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the image file to write.
Texture2D	texture	The texture to encode. Must not be null and must be readable.
ImageFileFormat	format	The ImageFileFormat to use for encoding. For lossy formats (JPG, WEBP), the default quality DEFAULT_QUALITY (90) is applied. For lossless formats (PNG, TGA) and EXR, quality has no effect.

Exceptions

Type	Condition
FileException	Thrown with ImageEncodingFailed if encoding fails, or with other codes for file I/O errors.

SaveImage(string, Texture2D, ImageFileFormat, int)

Encodes a UnityEngine.Texture2D in the specified format at the given quality and saves it to an image file. This is the most explicit format-and-quality overload; it constructs an ImageFileSettings internally and delegates to SaveImage(string, Texture2D, ImageFileSettings).

Declaration

public static void SaveImage(string path, Texture2D texture, ImageFileFormat format, int quality)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the image file to write.
Texture2D	texture	The texture to encode. Must not be null and must be readable.
ImageFileFormat	format	The ImageFileFormat to use for encoding.
int	quality	The encoding quality for lossy formats (JPG, WEBP). Valid range is [MIN_QUALITY, MAX_QUALITY] (1-100). Higher values produce larger files with fewer compression artifacts. This parameter has no effect on lossless formats (PNG, TGA) or EXR.

Exceptions

Type	Condition
FileException	Thrown with ImageEncodingFailed if encoding fails, or with other codes for file I/O errors (including invalid quality values detected by Validate()).

Declaration

public static void SaveImage(string path, Texture2D texture, ImageFileSettings settings)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the image file to write.
Texture2D	texture	The texture to encode. Must not be null and must be readable.
ImageFileSettings	settings	Image encoding settings including format, quality (for lossy formats), and EXR flags. Pass null to auto-detect format from the extension.

Exceptions

Type	Condition
FileException	Thrown with ImageEncodingFailed if encoding fails.

SaveImageAsync(string, Texture2D, ImageFileSettings, CancellationToken)

Asynchronously encodes a UnityEngine.Texture2D using the provided settings and saves it to an image file. When settings is null or Default, the format is inferred from the file extension.

Unity's texture encoding API is not thread-safe. Encoding is performed synchronously on the calling thread before the async file write begins. This method must be called from the Unity main thread.

Declaration

public static Task SaveImageAsync(string path, Texture2D texture, ImageFileSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the image file to write.
Texture2D	texture	The texture to encode. Must not be null and must be readable.
ImageFileSettings	settings	Image encoding settings (format, quality for lossy formats, EXR flags). Pass null to auto-detect format from the file extension.
CancellationToken	cancellationToken	Token that can cancel the file-write portion of the operation after encoding is complete. Cancellation throws a FileException with OperationCancelled.

Returns

Type	Description
Task	A Task representing the write operation.

Exceptions

Type	Condition
FileException	Thrown with ImageEncodingFailed if encoding fails, OperationCancelled if cancelled, or with other codes for file I/O errors.

SaveImageAsync(string, Texture2D, CancellationToken)

Asynchronously encodes a UnityEngine.Texture2D and saves it to an image file using default image settings. The output format is inferred from the file extension if no explicit format is configured.

Unity's texture encoding API is not thread-safe. Encoding is performed synchronously on the calling thread before the async file write begins. This method must be called from the Unity main thread.

Declaration

public static Task SaveImageAsync(string path, Texture2D texture, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the image file to write.
Texture2D	texture	The texture to encode. Must not be null and must be readable.
CancellationToken	cancellationToken	Token that can cancel the file-write portion of the operation after encoding is complete. Cancellation throws a FileException with OperationCancelled.

Returns

Type	Description
Task	A Task representing the write operation.

Exceptions

Type	Condition
FileException	Thrown with ImageEncodingFailed if encoding fails, OperationCancelled if cancelled, or with other codes for file I/O errors.

SaveObjectAsync<T>(string, T, SerializationSettings, CancellationToken)

Asynchronously serializes an object to JSON using the specified settings and writes the result as a UTF-8 text file. Serialization is performed synchronously; only the file write step is asynchronous.

Declaration

public static Task SaveObjectAsync<T>(string path, T obj, SerializationSettings serializationSettings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the JSON file to write.
T	obj	The object to serialize. May be null.
SerializationSettings	serializationSettings	Serialization settings (e.g., formatting, type handling). Pass null to use ScyllaSerialization defaults.
CancellationToken	cancellationToken	Token that can cancel the file-write step. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task	A Task representing the serialize-and-write operation.

Type Parameters

Name	Description
T	The type of the object to serialize. Must be serializable by ScyllaSerialization.

Exceptions

Type	Condition
FileException	Thrown with SerializationFailed if serialization fails, OperationCancelled on cancellation, or with other codes for path validation or file I/O errors.

SaveObjectAsync<T>(string, T, CancellationToken)

Asynchronously serializes an object to JSON using default settings and writes the result as a UTF-8 text file. Serialization is performed synchronously; only the file write step is asynchronous. This is a convenience overload of SaveObjectAsync<T>(string, T, SerializationSettings, CancellationToken).

Declaration

public static Task SaveObjectAsync<T>(string path, T obj, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the JSON file to write.
T	obj	The object to serialize. May be null.
CancellationToken	cancellationToken	Token that can cancel the file-write step. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task	A Task representing the serialize-and-write operation.

Type Parameters

Name	Description
T	The type of the object to serialize. Must be serializable by ScyllaSerialization.

Exceptions

Type	Condition
FileException	Thrown with SerializationFailed if serialization fails, OperationCancelled on cancellation, or with other codes for file I/O errors.

SaveObject<T>(string, T)

Serializes an object to JSON using default serialization settings and writes the result as a UTF-8 text file. This is a convenience overload of SaveObject<T>(string, T, SerializationSettings).

Declaration

public static void SaveObject<T>(string path, T obj)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the JSON file to write.
T	obj	The object to serialize. May be null.

Type Parameters

Name	Description
T	The type of the object to serialize. Must be serializable by ScyllaSerialization.

Exceptions

Type	Condition
FileException	Thrown with SerializationFailed if serialization fails, or with other codes for file I/O errors.

SaveObject<T>(string, T, SerializationSettings)

Serializes an object to JSON using the specified serialization settings and writes the result as a UTF-8 text file. If serialization fails, a FileException is thrown rather than returning an error result.

Declaration

public static void SaveObject<T>(string path, T obj, SerializationSettings serializationSettings)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the JSON file to write.
T	obj	The object to serialize. May be null.
SerializationSettings	serializationSettings	Serialization settings (e.g., formatting, type handling). Pass null to use ScyllaSerialization defaults.

Type Parameters

Name	Description
T	The type of the object to serialize. Must be serializable by ScyllaSerialization.

Exceptions

Type	Condition
FileException	Thrown with SerializationFailed if serialization fails, or with other codes for path validation or file I/O errors.

SaveSecureObjectAsync<T>(string, T, string, SerializationSettings, CompressionSettings, CryptoSettings, CancellationToken)

Asynchronously serializes, compresses, encrypts, and writes an object using the specified settings for each step. Serialization is performed synchronously; the compression, encryption, and file write steps are asynchronous.

The pipeline is: Serialize -> CompressAsync -> EncryptAsync -> WriteBytesAsync. To load data written with this method, use LoadSecureObjectAsync<T>(string, string, SerializationSettings, CompressionSettings, CryptoSettings, CancellationToken) with matching settings.

Declaration

public static Task SaveSecureObjectAsync<T>(string path, T obj, string password, SerializationSettings serializationSettings, CompressionSettings compressionSettings, CryptoSettings cryptoSettings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
T	obj	The object to serialize. May be null.
string	password	The password used to derive the encryption key. Must not be null or empty.
SerializationSettings	serializationSettings	Serialization settings. Pass null for defaults.
CompressionSettings	compressionSettings	Compression settings. Pass null for defaults (GZip).
CryptoSettings	cryptoSettings	Encryption settings. Pass null for defaults (AES-CBC-HMAC).
CancellationToken	cancellationToken	Token that can cancel the operation. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task	A Task representing the full pipeline operation.

Type Parameters

Name	Description
T	The type of the object to serialize. Must be serializable by ScyllaSerialization.

Exceptions

Type	Condition
FileException	Thrown with SerializationFailed if serialization fails, EncryptionFailed if the password is empty or encryption fails, OperationCancelled on cancellation, or other codes for compression or file I/O errors.

SaveSecureObjectAsync<T>(string, T, string, CancellationToken)

Asynchronously serializes, compresses, encrypts, and writes an object using default settings for each step. Serialization is performed synchronously; the compression, encryption, and file write steps are asynchronous. This is a convenience overload of SaveSecureObjectAsync<T>(string, T, string, SerializationSettings, CompressionSettings, CryptoSettings, CancellationToken).

Declaration

public static Task SaveSecureObjectAsync<T>(string path, T obj, string password, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
T	obj	The object to serialize. May be null.
string	password	The password used to derive the encryption key. Must not be null or empty.
CancellationToken	cancellationToken	Token that can cancel the operation at the compression, encryption, or file-write step. On cancellation, a FileException with OperationCancelled is thrown.

Returns

Type	Description
Task	A Task representing the full pipeline operation.

Type Parameters

Name	Description
T	The type of the object to serialize. Must be serializable by ScyllaSerialization.

Exceptions

Type	Condition
FileException	Thrown with SerializationFailed if serialization fails, EncryptionFailed if the password is empty or encryption fails, OperationCancelled on cancellation, or other codes for compression or file I/O errors.

SaveSecureObject<T>(string, T, string)

Serializes an object, compresses the result, encrypts the compressed bytes, and writes the final ciphertext to a file - all in one call using default settings for each step. This is the recommended method for persisting game state or configuration data that must be both compact and tamper-resistant.

The pipeline is: Serialize -> Compress -> Encrypt -> WriteBytes. To load data saved with this method, use LoadSecureObject<T>(string, string).

Declaration

public static void SaveSecureObject<T>(string path, T obj, string password)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
T	obj	The object to serialize. May be null.
string	password	The password used to derive the encryption key. Must not be null or empty.

Type Parameters

Name	Description
T	The type of the object to serialize. Must be serializable by ScyllaSerialization.

Exceptions

Type	Condition
FileException	Thrown with SerializationFailed if serialization fails, EncryptionFailed if the password is empty or encryption fails, or with other codes for compression or file I/O errors.

SaveSecureObject<T>(string, T, string, SerializationSettings, CompressionSettings, CryptoSettings)

Serializes an object, compresses the result, encrypts the compressed bytes, and writes the final ciphertext to a file, using the provided settings for each step. Pass null for any settings parameter to use the defaults for that subsystem.

The pipeline is: Serialize -> Compress -> Encrypt -> WriteBytes. To load data saved with this method, use LoadSecureObject<T>(string, string, SerializationSettings, CompressionSettings, CryptoSettings) with matching settings.

Declaration

public static void SaveSecureObject<T>(string path, T obj, string password, SerializationSettings serializationSettings, CompressionSettings compressionSettings, CryptoSettings cryptoSettings)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
T	obj	The object to serialize. May be null.
string	password	The password used to derive the encryption key. Must not be null or empty.
SerializationSettings	serializationSettings	Serialization settings. Pass null for defaults.
CompressionSettings	compressionSettings	Compression settings. Pass null for defaults (GZip).
CryptoSettings	cryptoSettings	Encryption settings. Pass null for defaults (AES-CBC-HMAC).

Type Parameters

Name	Description
T	The type of the object to serialize. Must be serializable by ScyllaSerialization.

Exceptions

Type	Condition
FileException	Thrown with SerializationFailed if serialization fails, EncryptionFailed if the password is empty or encryption fails, or with other codes for compression or file I/O errors.

TryDeleteFile(string)

Attempts to delete the specified file without throwing exceptions. Returns true both when the file was successfully deleted and when it did not exist.

Declaration

public static bool TryDeleteFile(string path)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to delete.

Returns

Type	Description
bool	true if the deletion succeeded or the file did not exist; false if an error occurred (e.g., access denied, invalid path).

TryLoadImage(string, ImageFileSettings, out Texture2D)

Attempts to load an image from disk and decode it into a UnityEngine.Texture2D using the provided image settings, without throwing exceptions on failure.

Declaration

public static bool TryLoadImage(string path, ImageFileSettings settings, out Texture2D texture)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the image file.
ImageFileSettings	settings	Image decoding settings (mipmap generation, readable flag, filter mode, wrap mode, aniso level). Pass null for Default.
Texture2D	texture	When this method returns true, contains the decoded UnityEngine.Texture2D. When this method returns false, this output is set to null. The caller is responsible for destroying the texture when it is no longer needed.

Returns

Type	Description
bool	true if the image was loaded and decoded successfully; false if any error occurred (file not found, unsupported format, decoding failure, invalid settings, etc.).

TryLoadImage(string, out Texture2D)

Attempts to load an image from disk and decode it into a UnityEngine.Texture2D using default image settings, without throwing exceptions on failure.

Declaration

public static bool TryLoadImage(string path, out Texture2D texture)

Parameters

Type	Name	Description
string	path	The absolute or relative path to the image file.
Texture2D	texture	When this method returns true, contains the decoded UnityEngine.Texture2D. When this method returns false, this output is set to null. The caller is responsible for destroying the texture when it is no longer needed.

Returns

Type	Description
bool	true if the image was loaded and decoded successfully; false if any error occurred (file not found, unsupported format, decoding failure, etc.).

TryReadBytes(string, FileSettings, out byte[])

Attempts to read all bytes from the specified file without throwing exceptions, using the provided settings.

Declaration

public static bool TryReadBytes(string path, FileSettings settings, out byte[] data)

Parameters

Type	Name	Description
string	path	The path to the file.
FileSettings	settings	File I/O settings. Pass null for Default.
byte[]	data	When this method returns true, contains the entire file contents as a byte[]. When it returns false, this value is null.

Returns

Type	Description
bool	true if the file was read successfully; false if any error occurred.

TryReadBytes(string, out byte[])

Attempts to read all bytes from the specified file without throwing exceptions, using default settings.

Declaration

public static bool TryReadBytes(string path, out byte[] data)

Parameters

Type	Name	Description
string	path	The path to the file.
byte[]	data	When this method returns true, contains the entire file contents as a byte[]. When it returns false, this value is null.

Returns

Type	Description
bool	true if the file was read successfully; false if any error occurred.

TryReadText(string, FileSettings, out string)

Attempts to read all text from the specified file without throwing exceptions, using the provided settings.

Declaration

public static bool TryReadText(string path, FileSettings settings, out string content)

Parameters

Type	Name	Description
string	path	The path to the file.
FileSettings	settings	File I/O settings. Pass null for Default.
string	content	When this method returns true, contains the entire file contents. When it returns false, this value is null.

Returns

Type	Description
bool	true if the file was read successfully; false if any error occurred.

TryReadText(string, out string)

Attempts to read all text from the specified file without throwing exceptions, using default settings.

Declaration

public static bool TryReadText(string path, out string content)

Parameters

Type	Name	Description
string	path	The path to the file.
string	content	When this method returns true, contains the entire file contents. When it returns false, this value is null.

Returns

Type	Description
bool	true if the file was read successfully; false if any error occurred (invalid path, file not found, access denied, etc.).

WriteBytes(string, byte[])

Writes a byte array to a file, creating or overwriting it, using default settings (64KB buffer, auto directory creation, overwrite enabled).

Declaration

public static void WriteBytes(string path, byte[] data)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
byte[]	data	The bytes to write. Must not be null; an empty array produces a zero-length file.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

WriteBytes(string, byte[], FileSettings)

Writes a byte array to a file, creating or overwriting it, using the provided settings.

Declaration

public static void WriteBytes(string path, byte[] data, FileSettings settings)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
byte[]	data	The bytes to write. Must not be null (NullData is thrown if it is).
FileSettings	settings	File I/O settings. Pass null for Default.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

WriteBytesAsync(string, byte[], FileSettings, CancellationToken)

Asynchronously writes a byte array to a file using the provided settings, creating or overwriting the file. The stream is opened with the async flag for non-blocking I/O.

Declaration

public static Task WriteBytesAsync(string path, byte[] data, FileSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
byte[]	data	The bytes to write. Must not be null.
FileSettings	settings	File I/O settings. Pass null for Default.
CancellationToken	cancellationToken	Token that cancels the write. Checked before the stream is opened.

Returns

Type	Description
Task	A Task representing the write operation.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

WriteBytesAsync(string, byte[], CancellationToken)

Asynchronously writes a byte array to a file using default settings, creating or overwriting the file.

Declaration

public static Task WriteBytesAsync(string path, byte[] data, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
byte[]	data	The bytes to write. Must not be null.
CancellationToken	cancellationToken	Token that cancels the write. Checked before the stream is opened.

Returns

Type	Description
Task	A Task representing the write operation.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

WriteFromStream(string, Stream)

Reads data from a source stream and writes it to a new file using default settings, creating or overwriting the file.

Declaration

public static void WriteFromStream(string path, Stream source)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the destination file.
Stream	source	The readable stream to read data from. Must not be null. Reading starts at the stream's current position.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

Declaration

public static void WriteFromStream(string path, Stream source, FileSettings settings, IProgress<FileProgress> progress = null)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the destination file.
Stream	source	The readable stream to read data from. Must not be null. When the stream supports seeking, total bytes are determined from `source.Length - source.Position`; otherwise progress reports `-1` for TotalBytes.
FileSettings	settings	File I/O settings. Pass null for Default.
IProgress<FileProgress>	progress	Optional progress reporter. Reports after each buffer chunk is written.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

WriteFromStreamAsync(string, Stream, FileSettings, IProgress<FileProgress>, CancellationToken)

Asynchronously reads data from a source stream and writes it to a new file in buffered chunks, with optional progress reporting, using the provided settings.

Declaration

public static Task WriteFromStreamAsync(string path, Stream source, FileSettings settings, IProgress<FileProgress> progress = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the destination file.
Stream	source	The readable stream to read data from. Must not be null. When the stream supports seeking, total bytes are computed from `source.Length - source.Position`; otherwise TotalBytes reports `-1`.
FileSettings	settings	File I/O settings. Pass null for Default.
IProgress<FileProgress>	progress	Optional progress reporter. Reports after each buffer chunk is written.
CancellationToken	cancellationToken	Token that cancels the operation. Checked between buffer reads/writes.

Returns

Type	Description
Task	A Task representing the write operation.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

WriteFromStreamAsync(string, Stream, CancellationToken)

Asynchronously reads data from a source stream and writes it to a new file using default settings, creating or overwriting the file.

Declaration

public static Task WriteFromStreamAsync(string path, Stream source, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the destination file.
Stream	source	The readable stream to read data from. Must not be null.
CancellationToken	cancellationToken	Token that cancels the operation. Checked between buffer reads/writes.

Returns

Type	Description
Task	A Task representing the write operation.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

WriteLines(string, IEnumerable<string>)

Writes a sequence of lines to a file, each terminated by the platform line ending, creating or overwriting the file with default settings.

Declaration

public static void WriteLines(string path, IEnumerable<string> lines)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
IEnumerable<string>	lines	The line strings to write. Must not be null; an empty sequence produces an empty file.

Exceptions

Type	Condition
FileException	Thrown when `lines` is null (NullData) or any I/O error occurs.

WriteLines(string, IEnumerable<string>, FileSettings)

Writes a sequence of lines to a file, each terminated by the platform line ending, creating or overwriting the file with the provided settings.

Declaration

public static void WriteLines(string path, IEnumerable<string> lines, FileSettings settings)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
IEnumerable<string>	lines	The line strings to write. The sequence is materialized before writing to avoid multiple enumeration. Must not be null.
FileSettings	settings	File I/O settings. Pass null for Default.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

WriteLinesAsync(string, IEnumerable<string>, FileSettings, CancellationToken)

Asynchronously writes a sequence of lines to a file using the provided settings, creating or overwriting the file. The stream is opened with the async flag for non-blocking I/O.

Declaration

public static Task WriteLinesAsync(string path, IEnumerable<string> lines, FileSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
IEnumerable<string>	lines	The line strings to write. The sequence is materialized to a list before writing. Must not be null.
FileSettings	settings	File I/O settings. Pass null for Default.
CancellationToken	cancellationToken	Token that cancels the write. Checked between lines, so cancellation latency depends on individual line lengths.

Returns

Type	Description
Task	A Task representing the write operation.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

WriteLinesAsync(string, IEnumerable<string>, CancellationToken)

Asynchronously writes a sequence of lines to a file with default settings, creating or overwriting the file.

Declaration

public static Task WriteLinesAsync(string path, IEnumerable<string> lines, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
IEnumerable<string>	lines	The line strings to write. Must not be null.
CancellationToken	cancellationToken	Token that cancels the write. Cancellation is checked between individual line writes.

Returns

Type	Description
Task	A Task representing the write operation.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

WriteText(string, string)

Writes content to a file, creating or overwriting it, using default settings (UTF-8 encoding, 64KB buffer, auto directory creation, overwrite enabled).

Declaration

public static void WriteText(string path, string content)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write. Parent directories are created automatically by default.
string	content	The text to write. A null value is written as an empty string.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

WriteText(string, string, FileSettings)

Writes content to a file, creating or overwriting it, using the provided settings.

Declaration

public static void WriteText(string path, string content, FileSettings settings)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write. Parent directories are created when CreateDirectories is true (the default).
string	content	The text to write. A null value is written as an empty string.
FileSettings	settings	File I/O settings controlling encoding, buffer size, overwrite behavior, and more. Pass null for Default.

Exceptions

Type	Condition
FileException	Thrown when the path is invalid, the file exists and OverwriteExisting is false, or any other I/O error occurs.

WriteText(string, string, Encoding)

Writes content to a file using the specified encoding and default buffer size, creating or overwriting the file.

Declaration

public static void WriteText(string path, string content, Encoding encoding)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
string	content	The text to write. A null value is written as an empty string.
Encoding	encoding	The character encoding to use when writing. When null, UTF8 is used.

Exceptions

Type	Condition
FileException	Thrown when the operation fails.

WriteTextAsync(string, string, FileSettings, CancellationToken)

Asynchronously writes content to a file using the provided settings, creating or overwriting the file. The stream is opened with the async flag for non-blocking I/O.

Declaration

public static Task WriteTextAsync(string path, string content, FileSettings settings, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
string	content	The text to write. A null value is written as an empty string.
FileSettings	settings	File I/O settings. Pass null for Default.
CancellationToken	cancellationToken	Token that cancels the write. Checked before the stream is opened.

Returns

Type	Description
Task	A Task representing the write operation.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

WriteTextAsync(string, string, CancellationToken)

Asynchronously writes content to a file using default settings, creating or overwriting the file.

Declaration

public static Task WriteTextAsync(string path, string content, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	path	The absolute or relative path of the file to write.
string	content	The text to write. A null value is written as an empty string.
CancellationToken	cancellationToken	Token that cancels the write before it completes. A FileException with OperationCancelled is thrown on cancellation.

Returns

Type	Description
Task	A Task representing the write operation.

Exceptions

Type	Condition
FileException	Thrown when the operation fails or is cancelled.

Class ScyllaFileUtil

Inheritance

Inherited Members

Namespace: Scylla.Core.Util.File

Assembly: ScyllaCore.dll

Syntax

Remarks

Methods

AppendLine(string, string)

Declaration

Parameters

Remarks

Exceptions

See Also

AppendLine(string, string, FileSettings)

Declaration

Parameters

Exceptions

AppendLineAsync(string, string, FileSettings, CancellationToken)

Declaration

Parameters

Returns

Exceptions

AppendLineAsync(string, string, CancellationToken)

Declaration

Parameters

Returns

Exceptions

AppendLines(string, IEnumerable<string>)

Declaration

Parameters

Exceptions

AppendLines(string, IEnumerable<string>, FileSettings)

Declaration

Parameters

Exceptions

AppendLinesAsync(string, IEnumerable<string>, FileSettings, CancellationToken)

Declaration

Parameters

Returns

Exceptions

AppendLinesAsync(string, IEnumerable<string>, CancellationToken)

Declaration

Parameters

Returns

Exceptions

AppendText(string, string)

Declaration

Parameters

Exceptions

See Also

AppendText(string, string, FileSettings)

Declaration

Parameters

Exceptions

AppendTextAsync(string, string, FileSettings, CancellationToken)

Declaration

Parameters

Returns

Exceptions

AppendTextAsync(string, string, CancellationToken)

Declaration

Parameters

Returns

Exceptions

See Also

CombinePath(params string[])

Declaration

Parameters

Returns

See Also

CopyFile(string, string)

Declaration

Parameters

Exceptions

See Also

CopyFile(string, string, FileSettings)

Declaration

Parameters

Exceptions