Class CompressionSettings

Encapsulates all parameters that govern how a ScyllaCompression operation is executed, including the algorithm, compression level, buffer size, parallelism, file filtering, encryption password, and file-collision behaviour.

Inheritance
object
CompressionSettings
Inherited Members
Namespace: Scylla.Core.Util.Compression
Assembly: ScyllaCore.dll
Syntax
public sealed class CompressionSettings
Remarks

Three ready-to-use presets are provided as static properties and cover the most common scenarios:

  • Default - GZip with Normal. A balanced choice suitable for the majority of game data.
  • Fast - GZip with Fastest and a large buffer. Use when compression latency matters more than output size (e.g., runtime save data or streaming assets).
  • MaxCompression - GZip with Maximum. Use for offline asset packing or archival where file size is critical.

When the SCYLLA_HAS_SHARPZIPLIB define is active, a fourth preset ZipArchive is available for multi-file ZIP operations.

Preset instances are shared and must not be mutated. Call Clone() to obtain a mutable copy with the same values before customising individual properties.

Call Validate() before passing a manually constructed instance to compression methods to surface configuration errors early.

Constructors

CompressionSettings()

Initializes a new CompressionSettings instance with all properties set to their documented defaults: GZip, Normal, 64 KB buffer, parallelism enabled, and no password or file filter.

Declaration
public CompressionSettings()

CompressionSettings(CompressionSettings)

Initializes a new CompressionSettings instance by deep-copying all property values from an existing instance. Equivalent to calling Clone() on other.

Declaration
public CompressionSettings(CompressionSettings other)
Parameters
Type Name Description
CompressionSettings other

The settings instance to copy from. When null, the new instance is initialized with default values (identical to the parameterless constructor).

Fields

DEFAULT_BUFFER_SIZE

The default I/O buffer size used when copying between streams during compression or decompression, equal to 65,536 bytes (64 KB). Used by Default and MaxCompression presets.

Declaration
public const int DEFAULT_BUFFER_SIZE = 65536
Field Value
Type Description
int

LARGE_BUFFER_SIZE

A larger I/O buffer size suitable for high-throughput streaming of large files, equal to 262,144 bytes (256 KB). Used by the Fast preset and by GetOptimalBufferSize(long) for files larger than 100 MB.

Declaration
public const int LARGE_BUFFER_SIZE = 262144
Field Value
Type Description
int

LARGE_FILE_THRESHOLD

The byte threshold above which GetOptimalBufferSize(long) selects a 128 KB buffer instead of the default 64 KB, equal to 10,485,760 bytes (10 MB).

Declaration
public const long LARGE_FILE_THRESHOLD = 10485760
Field Value
Type Description
long

MAX_BUFFER_SIZE

The largest permitted value for BufferSize, equal to 16,777,216 bytes (16 MB). Validate() throws a CompressionException with InvalidSettings if BufferSize exceeds this value.

Declaration
public const int MAX_BUFFER_SIZE = 16777216
Field Value
Type Description
int

MIN_BUFFER_SIZE

The smallest permitted value for BufferSize, equal to 1,024 bytes (1 KB). Validate() throws a CompressionException with InvalidSettings if BufferSize is set below this value.

Declaration
public const int MIN_BUFFER_SIZE = 1024
Field Value
Type Description
int

Properties

Algorithm

Gets or sets the compression algorithm to use for the operation.

Declaration
public CompressionAlgorithm Algorithm { get; set; }
Property Value
Type Description
CompressionAlgorithm

Defaults to GZip. Set to Zip (requires SCYLLA_HAS_SHARPZIPLIB) to enable multi-file archive operations via IArchiveProvider.

BufferSize

Gets or sets the size of the I/O buffer used when copying data between streams during compression or decompression, in bytes.

Declaration
public int BufferSize { get; set; }
Property Value
Type Description
int

Defaults to DEFAULT_BUFFER_SIZE (64 KB). Must be in the range MIN_BUFFER_SIZE (1 KB) to MAX_BUFFER_SIZE (16 MB), enforced by Validate(). Larger buffers improve throughput for large sequential reads at the cost of additional memory; use LARGE_BUFFER_SIZE (256 KB) for files greater than 10 MB.

Default

Gets a shared preset that provides a balanced combination of compression ratio and speed using GZip at Normal with a 64 KB buffer. This is the algorithm and level selected when no explicit settings are passed to ScyllaCompression methods.

Declaration
public static CompressionSettings Default { get; }
Property Value
Type Description
CompressionSettings
Remarks

Do not mutate this instance. Call Clone() to obtain a mutable copy.

Fast

Gets a shared preset optimised for minimum processing latency at the cost of a lower compression ratio. Uses GZip at Fastest with a 256 KB buffer for higher throughput on large inputs.

Declaration
public static CompressionSettings Fast { get; }
Property Value
Type Description
CompressionSettings
Remarks

Suitable for runtime scenarios where compressing data on the hot path is necessary (e.g., compressing network payloads, streaming save data). Do not mutate this instance. Call Clone() to obtain a mutable copy.

FileFilter

Gets or sets a wildcard file filter pattern that restricts which files are included when creating a ZIP archive from a directory.

Declaration
public string FileFilter { get; set; }
Property Value
Type Description
string

A standard shell-style wildcard pattern such as ".txt" or "data_.bin". When null or empty, all files in the source directory are included without filtering. Pattern matching is case-insensitive on Windows and case-sensitive on macOS/Linux.

IncludeEmptyDirectories

Gets or sets a value indicating whether empty directories are included as explicit entries when creating a ZIP archive from a folder.

Declaration
public bool IncludeEmptyDirectories { get; set; }
Property Value
Type Description
bool

Defaults to true. Set to false to omit empty directory entries, reducing archive entry count when empty folders carry no meaning for the receiver. Only relevant to CreateArchive(string, string, CompressionSettings, IProgress<CompressionProgress>, CancellationToken) operations.

Level

Gets or sets the compression level that controls the trade-off between output size and processing time.

Declaration
public CompressionLevel Level { get; set; }
Property Value
Type Description
CompressionLevel

Defaults to Normal. See CompressionLevel for a description of how each value maps to the underlying provider's native level range.

MaxCompression

Gets a shared preset that produces the smallest possible output at the cost of the highest CPU usage and processing time. Uses GZip at Maximum with a 64 KB buffer.

Declaration
public static CompressionSettings MaxCompression { get; }
Property Value
Type Description
CompressionSettings
Remarks

Suitable for offline or build-time asset packing. On GZip and Deflate providers (which use System.IO.Compression), Maximum maps to the same Optimal tier as Normal, so the output size difference is provider-specific. Do not mutate this instance. Call Clone() to obtain a mutable copy.

MaxDegreeOfParallelism

Gets or sets the maximum number of files or byte arrays that may be processed concurrently during parallel archive and batch compression operations.

Declaration
public int MaxDegreeOfParallelism { get; set; }
Property Value
Type Description
int

Defaults to ProcessorCount. Must be at least 1, enforced by Validate(). Setting this to 1 forces strictly sequential processing regardless of the value of UseParallelProcessing. Only used when UseParallelProcessing is true.

OverwriteExisting

Gets or sets a value indicating whether an existing file at the destination path should be overwritten during archive extraction.

Declaration
public bool OverwriteExisting { get; set; }
Property Value
Type Description
bool

Defaults to false. When false, attempting to extract an entry to a path that already exists throws a CompressionException with FileExists. Set to true to silently replace existing files.

Password

Gets or sets the password used to encrypt entries in a ZIP archive with AES-256 encryption, or to decrypt entries when extracting a password-protected archive.

Declaration
public string Password { get; set; }
Property Value
Type Description
string

null or an empty string means no encryption is applied when creating an archive, and no password is supplied when extracting. Only relevant when Algorithm is Zip. Providing an incorrect password during extraction results in a CompressionException with WrongPassword.

PreserveTimestamps

Gets or sets a value indicating whether the last-modification timestamp of each file is stored in the archive as the entry's LastModified value.

Declaration
public bool PreserveTimestamps { get; set; }
Property Value
Type Description
bool

Defaults to true. Set to false to omit timestamps and reduce determinism variation when comparing archive bytes across builds. Only relevant to CreateArchive(string, string, CompressionSettings, IProgress<CompressionProgress>, CancellationToken) operations.

UseParallelProcessing

Gets or sets a value indicating whether archive and batch compression operations distribute work across multiple threads.

Declaration
public bool UseParallelProcessing { get; set; }
Property Value
Type Description
bool

Defaults to true. When true, ScyllaCompression uses Parallel.For and Task.WhenAll internally, bounded by MaxDegreeOfParallelism. Set to false to force single-threaded processing, which is useful for deterministic debugging or when the calling environment constrains thread usage.

ZipArchive

Gets a shared preset configured for multi-file ZIP archive operations using Zip at Normal. Only available when SCYLLA_HAS_SHARPZIPLIB is defined (requires com.unity.sharp-zip-lib 1.4.1+).

Declaration
public static CompressionSettings ZipArchive { get; }
Property Value
Type Description
CompressionSettings
Remarks

To enable password-based AES-256 encryption for archive entries, clone this preset and set Password to a non-empty string. Do not mutate this instance directly. Call Clone() to obtain a mutable copy.

Methods

Clone()

Creates an independent copy of this CompressionSettings instance with all property values duplicated. Use this to safely customize a preset without modifying the shared static instance.

Declaration
public CompressionSettings Clone()
Returns
Type Description
CompressionSettings

A new CompressionSettings instance whose properties have the same values as this instance. Subsequent changes to the clone do not affect the original.

Validate()

Validates this settings instance and throws a CompressionException if any property value is outside its permitted range.

Declaration
public void Validate()
Remarks

The following constraints are enforced:

ScyllaCompression calls Validate automatically before beginning any operation. Callers only need to call it explicitly when building settings objects and wanting to surface errors before passing them downstream.
Exceptions
Type Condition
CompressionException

Thrown with InvalidSettings when any validated constraint is violated, with a message identifying the specific property and its allowed range.

Extension Methods

See Also