Class ScyllaLoggerConfiguration

ScyllaConfiguration asset that controls every aspect of the Scylla logging system: whether logging is active, the minimum severity level that passes the filter, whether log files are written to disk, how console and file entries are formatted, and how large the early-startup entry buffer may grow.

Inheritance
object
Object
ScriptableObject
ScyllaConfiguration
ScyllaLoggerConfiguration
Inherited Members
ScriptableObject.CreateInstance<T>()
Object.GetEntityId()
Object.GetHashCode()
Object.InstantiateAsync<T>(T)
Object.InstantiateAsync<T>(T, Transform)
Object.InstantiateAsync<T>(T, Vector3, Quaternion)
Object.InstantiateAsync<T>(T, Transform, Vector3, Quaternion)
Object.Instantiate(Object, Vector3, Quaternion)
Object.Instantiate(Object, Vector3, Quaternion, Transform)
Object.Instantiate(Object)
Object.Instantiate(Object, Scene)
Object.Instantiate<T>(T, InstantiateParameters)
Object.Instantiate<T>(T, Vector3, Quaternion, InstantiateParameters)
Object.Instantiate(Object, Transform)
Object.Instantiate<T>(T)
Object.Instantiate<T>(T, Vector3, Quaternion)
Object.Instantiate<T>(T, Vector3, Quaternion, Transform)
Object.Instantiate<T>(T, Transform)
Object.Destroy(Object)
Object.DestroyImmediate(Object)
Object.DontDestroyOnLoad(Object)
Object.FindAnyObjectByType<T>()
Object.FindAnyObjectByType<T>(FindObjectsInactive)
Object.FindObjectsByType<T>()
Object.FindObjectsByType<T>(FindObjectsInactive)
Object.ToString()
Object.name
Object.hideFlags
Namespace: Scylla.Core.Config
Assembly: ScyllaCore.dll
Syntax
[CreateAssetMenu(fileName = "Scylla Logger Configuration", menuName = "Scylla/Core/Logger Configuration", order = 1)]
public sealed class ScyllaLoggerConfiguration : ScyllaConfiguration
Remarks

Asset creation: Use the Unity Project window context menu Create -> Scylla -> Core -> Logger Configuration to create an asset, then assign it to the ScyllaBootstrap Inspector field. If no asset is assigned, LoadDefault() is called automatically, which looks for an asset named CONFIG_FILENAME inside a Resources/Config/ folder.

Runtime apply: Calling Apply() immediately updates IsEnabled and FilterLevel. File logging receiver registration is intentionally deferred to ScyllaBootstrap because it requires constructing a FileLog instance.

Config file overrides: When config file support is enabled for the current build type, ApplyConfigFileOverrides(ConfigFile) maps JSON properties from a ConfigFile onto the Inspector fields, allowing field-level overrides without reimporting the asset. The full property set can be exported via ExportToConfigFile().

Inspector validation: Validate() produces ConfigurationValidationResult entries that are displayed in the custom Inspector. Recommendations use the private validation range constants to produce context-aware guidance for each setting.

Fields

CONFIG_FILENAME

Filename for auto-loading this configuration asset from Resources/Config/ via LoadDefault(). Also used as the default asset name when creating the asset through the Unity context menu.

Declaration
public const string CONFIG_FILENAME = "Scylla Logger Configuration"
Field Value
Type Description
string

GROUP_FILE_LOGGING

Config file group name for file logging behavior settings (FileLoggingSettings: rotation, disk space, batching).

Declaration
public const string GROUP_FILE_LOGGING = "File Logging"
Field Value
Type Description
string

GROUP_FILE_LOG_FORMATTING

Config file group name for file log formatting settings (FileLogFormattingSettings, excluding rotation/batching fields).

Declaration
public const string GROUP_FILE_LOG_FORMATTING = "File Log Formatting"
Field Value
Type Description
string

GROUP_GENERAL

Config file group name for general logging settings (KEY_ENABLE_LOGGING, KEY_LOG_LEVEL, KEY_ENABLE_FILE_LOGGING, KEY_MAX_EARLY_LOG_BUFFER_SIZE).

Declaration
public const string GROUP_GENERAL = "General"
Field Value
Type Description
string

GROUP_UNITY_CONSOLE_OUTPUT

Config file group name for Unity console output formatting settings (ConsoleLoggingSettings).

Declaration
public const string GROUP_UNITY_CONSOLE_OUTPUT = "Unity Console Output"
Field Value
Type Description
string

KEY_BATCH_SIZE

Config file property key for BatchSize within the GROUP_FILE_LOGGING group.

Declaration
public const string KEY_BATCH_SIZE = "BatchSize"
Field Value
Type Description
string

KEY_ENABLE_FILE_LOGGING

Config file property key for the EnableFileLogging flag within the GROUP_GENERAL group.

Declaration
public const string KEY_ENABLE_FILE_LOGGING = "EnableFileLogging"
Field Value
Type Description
string

KEY_ENABLE_LOGGING

Config file property key for the EnableLogging flag within the GROUP_GENERAL group.

Declaration
public const string KEY_ENABLE_LOGGING = "EnableLogging"
Field Value
Type Description
string

KEY_FLUSH_INTERVAL_MS

Config file property key for FlushIntervalMs within the GROUP_FILE_LOGGING group.

Declaration
public const string KEY_FLUSH_INTERVAL_MS = "FlushIntervalMs"
Field Value
Type Description
string

KEY_FORMAT

Config file property key for the LogFileFormat enum value (stored as a string, e.g., "PlainText" or "JSON") within the GROUP_FILE_LOG_FORMATTING group.

Declaration
public const string KEY_FORMAT = "Format"
Field Value
Type Description
string

KEY_LOG_LEVEL

Config file property key for the LogLevel enum value (stored as a string, e.g., "Trace", "Warning") within the GROUP_GENERAL group.

Declaration
public const string KEY_LOG_LEVEL = "LogLevel"
Field Value
Type Description
string

KEY_LOG_SUBFOLDER

Config file property key for LogSubFolder within the GROUP_FILE_LOGGING group.

Declaration
public const string KEY_LOG_SUBFOLDER = "LogSubFolder"
Field Value
Type Description
string

KEY_MAX_EARLY_LOG_BUFFER_SIZE

Config file property key for the MaxEarlyLogBufferSize integer within the GROUP_GENERAL group.

Declaration
public const string KEY_MAX_EARLY_LOG_BUFFER_SIZE = "MaxEarlyLogBufferSize"
Field Value
Type Description
string

KEY_MAX_LOG_BUFFER_SIZE

Config file property key for MaxLogBufferSize within the GROUP_GENERAL group.

Declaration
public const string KEY_MAX_LOG_BUFFER_SIZE = "MaxLogBufferSize"
Field Value
Type Description
string

KEY_MAX_LOG_FILES

Config file property key for MaxLogFiles within the GROUP_FILE_LOGGING group.

Declaration
public const string KEY_MAX_LOG_FILES = "MaxLogFiles"
Field Value
Type Description
string

KEY_MAX_LOG_FILE_SIZE_MB

Config file property key for MaxLogFileSizeMB within the GROUP_FILE_LOGGING group.

Declaration
public const string KEY_MAX_LOG_FILE_SIZE_MB = "MaxLogFileSizeMB"
Field Value
Type Description
string

KEY_MAX_LOG_HISTORY_SIZE

Config file property key for MaxLogHistorySize within the GROUP_GENERAL group.

Declaration
public const string KEY_MAX_LOG_HISTORY_SIZE = "MaxLogHistorySize"
Field Value
Type Description
string

KEY_MIN_FREE_DISK_SPACE_MB

Config file property key for MinFreeDiskSpaceMB within the GROUP_FILE_LOGGING group.

Declaration
public const string KEY_MIN_FREE_DISK_SPACE_MB = "MinFreeDiskSpaceMB"
Field Value
Type Description
string

KEY_SHOW_CATEGORY

Config file property key for the ShowCategory boolean, shared by both GROUP_UNITY_CONSOLE_OUTPUT and GROUP_FILE_LOG_FORMATTING groups.

Declaration
public const string KEY_SHOW_CATEGORY = "ShowCategory"
Field Value
Type Description
string

KEY_SHOW_CODE_LOCATION

Config file property key for the ShowCodeLocation boolean, shared by both GROUP_UNITY_CONSOLE_OUTPUT and GROUP_FILE_LOG_FORMATTING groups.

Declaration
public const string KEY_SHOW_CODE_LOCATION = "ShowCodeLocation"
Field Value
Type Description
string

KEY_SHOW_LABEL

Config file property key for the ShowLabel boolean, shared by both GROUP_UNITY_CONSOLE_OUTPUT and GROUP_FILE_LOG_FORMATTING groups.

Declaration
public const string KEY_SHOW_LABEL = "ShowLabel"
Field Value
Type Description
string

KEY_SHOW_PREFIX

Config file property key for the ShowPrefix boolean, shared by both GROUP_UNITY_CONSOLE_OUTPUT and GROUP_FILE_LOG_FORMATTING groups.

Declaration
public const string KEY_SHOW_PREFIX = "ShowPrefix"
Field Value
Type Description
string

KEY_SHOW_TIMESTAMP

Config file property key for the ShowTimestamp boolean, shared by both GROUP_UNITY_CONSOLE_OUTPUT and GROUP_FILE_LOG_FORMATTING groups.

Declaration
public const string KEY_SHOW_TIMESTAMP = "ShowTimestamp"
Field Value
Type Description
string

Properties

ConsoleLogging

Gets the ConsoleLoggingSettings object that controls which metadata components (timestamp, code location, prefix, label, category) appear in Unity console output produced by the UnityConsoleLog receiver.

Declaration
public ConsoleLoggingSettings ConsoleLogging { get; }
Property Value
Type Description
ConsoleLoggingSettings

A ConsoleLoggingSettings instance. Never null when the asset is properly initialized.

EnableFileLogging

Gets whether the FileLog receiver should be created and registered by ScyllaBootstrap on startup.

Declaration
public bool EnableFileLogging { get; }
Property Value
Type Description
bool

true if log files are written to disk; false if file logging is entirely disabled for the session.

EnableLogging

Gets whether the Scylla logging system is active. When this is false, Apply() sets IsEnabled to false and all subsequent log calls in Log are no-ops regardless of level.

Declaration
public bool EnableLogging { get; }
Property Value
Type Description
bool

true if logging is enabled; false if all output is suppressed.

FileFormatting

Gets the FileLogFormattingSettings object that controls the output format and metadata components written to each entry in disk log files by FileLog.

Declaration
public FileLogFormattingSettings FileFormatting { get; }
Property Value
Type Description
FileLogFormattingSettings

A FileLogFormattingSettings instance. Never null when the asset is properly initialized.

FileLogging

Gets the FileLoggingSettings object that is passed to the FileLog constructor to configure rotation, disk-space protection, write batching, and the log subdirectory.

Declaration
public FileLoggingSettings FileLogging { get; }
Property Value
Type Description
FileLoggingSettings

A FileLoggingSettings instance. Never null when the asset is properly initialized.

LogLevel

Gets the minimum LogLevel required for a message to be forwarded to registered receivers. Messages with a severity strictly below this value are discarded before reaching any receiver.

Declaration
public LogLevel LogLevel { get; }
Property Value
Type Description
LogLevel

A LogLevel value. Defaults to Trace (all messages pass). Set to Maximum to suppress all output.

MaxEarlyLogBufferSize

Gets the maximum number of log entries that Log will buffer internally before the first receiver is registered during early framework startup. Once a receiver is available, all buffered entries are replayed in order. If more entries arrive than this limit allows, the oldest entries are dropped silently.

Declaration
public int MaxEarlyLogBufferSize { get; }
Property Value
Type Description
int

A positive integer in the range [100, 10000]. Defaults to 1000. Values below 500 risk dropping early startup messages; values above 2000 increase boot-time memory allocation.

MaxLogBufferSize

Gets the maximum number of log entries the pre-receiver buffer will hold. When no receivers are registered, log entries are buffered up to this limit. Once full, the oldest entries are dropped.

Declaration
public int MaxLogBufferSize { get; }
Property Value
Type Description
int

MaxLogHistorySize

Gets the maximum number of log entries retained in permanent history. The permanent history allows late-initializing components (like DebugConsole) to retrieve log entries that occurred before they were ready.

Declaration
public int MaxLogHistorySize { get; }
Property Value
Type Description
int

Methods

Apply()

Immediately applies the subset of logger configuration settings that can be changed at runtime without recreating any receivers. Specifically, sets IsEnabled from EnableLogging and FilterLevel from LogLevel.

Declaration
public override void Apply()
Overrides
Remarks

This method does not start, stop, or reconfigure the FileLog receiver. File logging changes require ScyllaBootstrap to tear down and recreate the receiver, which is not safe to do at arbitrary runtime points. Formatting and batching settings are similarly read only once at FileLog construction time and are not hot-reloaded here.

In the Unity Editor this method is called automatically by the base class ScyllaConfiguration whenever an Inspector value changes during play mode, enabling live log level adjustments without restarting the game.

ApplyConfigFileOverrides(ConfigFile)

Reads key/value pairs from configFile and applies any that match known property keys to the corresponding serialized fields on this asset. Unknown keys and groups are silently ignored. Invalid enum values for LogLevel and LogFileFormat emit a Warning(object, string, int) and leave the existing field value unchanged.

Declaration
public override int ApplyConfigFileOverrides(ConfigFile configFile)
Parameters
Type Name Description
ConfigFile configFile

The ConfigFile instance containing key/value override pairs. If null, the method returns 0 immediately without modifying any fields.
Returns
Type Description
int

The total number of individual properties successfully read and applied from the config file. Returns 0 if configFile is null or contains no matching keys.
Overrides
Remarks

Properties are read from the following groups:

ExportToConfigFile()

Serializes all current logger configuration field values into a new ConfigFile object, using the same group names and property keys defined by the GROUP_ and KEY_ constants. The resulting file can be saved to disk as JSON and later loaded to override this asset via ApplyConfigFileOverrides(ConfigFile).

Declaration
public override ConfigFile ExportToConfigFile()
Returns
Type Description
ConfigFile

A new ConfigFile populated with all current field values, ready for JSON serialization. Never returns null.
Overrides
Remarks

Every writable field is exported, including nested settings from FileLoggingSettings, ConsoleLoggingSettings, and FileLogFormattingSettings. Enum values are written as their string names (e.g., "Trace", "PlainText") to ensure human readability and forward-compatibility with future enum additions. Fields on nested objects are exported only when the object is non-null.

GetConfigFileName()

Returns the asset file name used by LoadDefault() and the base class config-file lookup pipeline to locate this configuration in the Resources system.

Declaration
public override string GetConfigFileName()
Returns
Type Description
string

The value of CONFIG_FILENAME ("Scylla Logger Configuration"), which the base class GetConfigFileBaseName() further strips to "Logger" for JSON config file lookups.
Overrides

LoadDefault()

Attempts to load the default ScyllaLoggerConfiguration asset from the Unity Resources system. The asset is expected to reside at Resources/Config/Scylla Logger Configuration (i.e., the CONFIG_FOLDER subdirectory inside any Resources folder in the project).

Declaration
public static ScyllaLoggerConfiguration LoadDefault()
Returns
Type Description
ScyllaLoggerConfiguration

The loaded ScyllaLoggerConfiguration asset, or null if no asset with the expected name exists at the expected path.

ResetToDefaults()

Resets every field on this configuration asset to the factory defaults used when the asset is first created. All nested settings objects are also reconstructed to guarantee no stale values remain from a previous session.

Declaration
public override void ResetToDefaults()
Overrides
Remarks

Default values restored by this method:

  • EnableLogging: true
  • LogLevel: Trace
  • EnableFileLogging: true
  • MaxEarlyLogBufferSize: 1000
  • FileLogging: MaxLogFiles=10, MaxLogFileSizeMB=1, MinFreeDiskSpaceMB=100, LogSubFolder="Logs", BatchSize=50, FlushIntervalMs=10
  • ConsoleLogging: ShowTimestamp=false, ShowCodeLocation=false, ShowPrefix=true, ShowLabel=true, ShowCategory=true
  • FileFormatting: Format=PlainText, ShowTimestamp=true, ShowCodeLocation=true, ShowPrefix=true, ShowLabel=true, ShowCategory=true

Validate()

Validates all logger configuration fields and returns a list of ConfigurationValidationResult entries describing any issues found. Results are purely advisory; the framework will run even if warnings are present. An Error-severity result is only produced for the empty LogSubFolder case, which would cause FileLog initialization to fail at runtime.

Declaration
public override ConfigurationValidationResult[] Validate()
Returns
Type Description
ConfigurationValidationResult[]

An array of ConfigurationValidationResult entries, each carrying a ValidationSeverity, a human-readable message, and the name of the related serialized field. Returns an empty array when all settings are within recommended ranges.
Overrides
Remarks

The following conditions are checked, in order:

  • _enableLogging = false: info result reminding the caller that all output is suppressed.
  • _logLevel = Maximum: warning that no messages will appear except explicitly forced ones.
  • File logging settings (MaxLogFiles, MaxLogFileSizeMB, MinFreeDiskSpaceMB, LogSubFolder, BatchSize, FlushIntervalMs): range and presence checks using the private MIN_RECOMMENDED_* / OPTIMAL_* constants.
  • _maxEarlyLogBufferSize: range check against MIN_RECOMMENDED_EARLY_BUFFER and MAX_RECOMMENDED_EARLY_BUFFER.

Extension Methods

See Also