Namespace Scylla.Core.Util.File

Classes

ConfigFile

In-memory representation of a grouped JSON configuration file used by the Scylla framework's layered configuration system. A ConfigFile organizes its data as a flat collection of named ConfigFileGroup instances, each containing an arbitrary number of ConfigFileProperty values. Both groups and properties within each group are stored in alphabetical order using case-insensitive key comparison.

Supports all primitive JSON types (boolean, integer, float, double, string), as well as nested groups and ordered arrays. Colors are stored as ARGB hex strings (e.g. "#FF8040FF") and can be read and written using TryGetColor(string, string, out Color) and SetColor(string, string, Color).

Provides serialization to and from human-readable, pretty-printed JSON via ToJSON() and FromJSON(string). Multiple files can be layered together using Merge(ConfigFile, ConfigFile), which combines a higher-priority file with a lower-priority one so that values from the lower file fill gaps not present in the higher file. This is the mechanism behind the four-tier override chain managed by ConfigFileManager.

Float and double values are rounded to six decimal places when serialized to JSON for human readability. NaN and infinity are preserved as-is.

ConfigFileGroup

Represents a named group of properties within a ConfigFile. A group corresponds to a single JSON object at the top level or as a nested value within a ConfigFile. Each group owns an arbitrary number of ConfigFileProperty entries keyed by name, stored in case-insensitive alphabetical order.

Groups can hold properties of any ConfigFilePropertyType, including nested sub-groups and arrays. Typed convenience methods (e.g. TryGetBool(string, out bool), SetString(string, string)) provide direct access without needing to work with raw ConfigFileProperty structs.

Groups are created either by GetOrAddGroup(string) / AddGroup(string) for top-level groups, or by the Group(ConfigFileGroup) factory method when nesting groups as property values.

ConfigFileUtil

Provides file I/O and path resolution utilities for ConfigFile instances, supporting the Scylla framework's four-tier layered configuration system. The four tiers, from highest to lowest priority, are: User Documents, Application folder, Unity Asset, and compiled defaults. This class handles the two filesystem tiers - User Documents and Application folder - by constructing their canonical paths and performing JSON-based load and save operations.

All load operations are non-throwing: a missing file, empty file, or JSON parse failure each return null with a warning logged to the Core log category. Save operations return a bool indicating success and log a warning on failure rather than throwing. Parent directories are created automatically on save.

Config file paths follow the convention {BasePath}/Config/{configBaseName}.json, where configBaseName identifies the owning module or subsystem (e.g. "Core", "Input", "Logger"). Use GetUserDocumentsConfigPath(string) for the User Documents tier and GetAppFolderConfigPath(string) for the Application folder tier.

FileException

Exception thrown when a file I/O operation performed by ScyllaFileUtil or its supporting subsystems fails for any reason.

FileExtensions

Extension methods that enable fluent, caller-friendly file I/O on common types. Rather than calling ScyllaFileUtil directly, these extensions allow data to be saved in a natural, object-oriented style (e.g. myBytes.SaveToFile(path) or texture.SaveAsPNG(path)).

Extensions are organized by the type they extend:

  • byte[] - write raw binary data, optionally with GZip compression or AES encryption.
  • string - write or append UTF-8 text, with optional encoding or FileSettings overrides.
  • Texture2D - encode and save Unity textures as PNG, JPG, WEBP, TGA, or EXR using ImageFileSettings presets or per-format convenience methods.
  • IEnumerable<string> - write or append a sequence of text lines.
  • Generic objects (T : class) - JSON-serialize an object and write it to a file, optionally with compression and encryption (secure save).

All synchronous methods throw FileException on failure. All asynchronous variants return a Task and accept an optional CancellationToken.

FilePathExtensions

Extension methods that expose FilePathUtil path operations directly on string instances, enabling a fluent style for common path manipulation tasks. Every method in this class delegates to its corresponding static method in FilePathUtil and inherits that method's documented behavior, null handling, and return-value contracts.

The extensions are organized into four groups:

  • Path Operations - normalize separators, convert to forward or back slashes.
  • Path Component Extraction - retrieve the parent directory, file name, file name without extension, extension, or drive/UNC root.
  • Path Validation - check whether a string is a valid path, an absolute path, a root path, or contains invalid path or file name characters.
  • Path Transformation - sanitize a file name by replacing invalid characters, or swap the file extension.

FilePathUtil

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

FileSettings

Encapsulates configuration options that govern how ScyllaFileUtil performs file I/O operations, including buffering, encoding, share modes, and write behavior.

ImageFileSettings

Encapsulates all configuration options that govern image encoding and decoding operations performed by ScyllaFileUtil.

Settings are divided into two concerns:

Several static preset properties are provided for common scenarios. These presets return shared singleton instances; do not mutate them directly. Use Clone() to create a mutable copy when you need to adjust a preset.

ScyllaFileUtil

Provides a unified, high-level API for file I/O covering text, binary, stream, image, compressed, encrypted, and serialized file operations.

Structs

ConfigFileProperty

Represents a single, immutable, typed property value stored within a ConfigFileGroup. The supported data types are defined by ConfigFilePropertyType: boolean, 32-bit integer, single- and double-precision float, string, nested group, and ordered array.

Instances must be created via the static factory methods (Bool(bool), Int(int), Float(float), Double(double), String(string), Group(ConfigFileGroup), Array(List<ConfigFileProperty>)) rather than via default or the parameterless constructor. A default-constructed instance has IsInitialized set to false and accessing any typed value accessor will throw InvalidOperationException.

Because ConfigFileProperty is a value type, it is copied by assignment. This is safe for all primitive types and strings. Group-typed and array-typed properties hold references to the underlying ConfigFileGroup or List<T> - the struct itself is copied, but the referenced heap objects are shared. Use Merge(ConfigFile, ConfigFile) (which deep-clones) if full isolation is required.

FileProgress

An immutable, value-type snapshot of progress for an in-flight file I/O operation. Instances of this struct are passed to IProgress<FileProgress> callbacks by ScyllaFileUtil async methods to report how many bytes have been transferred.

Enums

ConfigFilePropertyType

Identifies the runtime data type of a value stored in a ConfigFileProperty within a ConfigFile. This enum drives type-guarded accessor selection (e.g. BoolValue, IntValue) and controls how values are serialized by ToJSON().

When deserializing JSON via FromJSON(string), the type is inferred from the JSON token: boolean literals become Bool, integer literals within Int32 range become Int (larger integers become Double), floating-point literals become Double, string literals and JSON null become String, nested JSON objects become Group, and JSON arrays become Array.

FileErrorCode

Specifies structured error codes that classify the reason a file I/O operation failed.

ImageFileFormat

Specifies the image file formats supported by ScyllaFileUtil for loading and saving Texture2D assets.

Not all formats are available in every Unity version or on every platform. Use IsImageFormatSupported(ImageFileFormat) to query runtime availability before attempting to encode an image, particularly for WEBP, which requires Unity 2021.2 or later.

Format selection affects file size, image fidelity, transparency support, and dynamic range. See individual enum value summaries for guidance on choosing the appropriate format for a given use case.