Class Log

Provides centralized logging functionality for the Scylla framework. This static class allows logging at various levels of severity, from system-level messages to fatal errors, and supports message categorization and filtering.

Conditional Compilation:

The following log methods support conditional compilation to remove log calls at compile time:

  • Trace and Debug: Conditionally compiled with DEBUG symbol. Calls are automatically removed in release builds (when DEBUG is not defined), providing zero runtime overhead.
  • System, Info, Notice, Warning, Error, Fatal: Always compiled (critical or production-level logs).

Benefits: Zero runtime overhead for Trace/Debug in release builds, smaller binary size, better performance.

Inheritance
object
Log
Inherited Members
Namespace: Scylla.Core
Assembly: ScyllaCore.dll
Syntax
public static class Log

Fields

FilterLevel

The minimum LogLevel a message must meet or exceed to be processed and dispatched to registered receivers. Messages with a level strictly below this value are dropped before any formatting or allocation occurs. Defaults to Trace so that all messages pass through by default.

Note: System messages bypass this filter entirely and are always delivered when IsEnabled is true.

Declaration
public static LogLevel FilterLevel
Field Value
Type Description
LogLevel

IsEnabled

Controls whether the logging system is active. When false, all logging methods return immediately without processing or dispatching any messages, including System and Fatal messages. Set to true by default. Toggle this field to globally silence all Scylla log output without unregistering receivers.

Declaration
public static bool IsEnabled
Field Value
Type Description
bool

LABEL_DEBUG

The bracketed severity label inserted into log messages at Debug level. Value: [DEBUG].

Declaration
public const string LABEL_DEBUG = "[DEBUG]"
Field Value
Type Description
string

LABEL_EMPTY

The label string used when no severity label should appear in a log message. Resolves to a single space so that message alignment is preserved across all levels.

Declaration
public const string LABEL_EMPTY = " "
Field Value
Type Description
string

LABEL_ERROR

The bracketed severity label inserted into log messages at Error level. Value: [ERROR].

Declaration
public const string LABEL_ERROR = "[ERROR]"
Field Value
Type Description
string

LABEL_FATAL

The bracketed severity label inserted into log messages at Fatal level. Value: [FATAL].

Declaration
public const string LABEL_FATAL = "[FATAL]"
Field Value
Type Description
string

LABEL_INFO

The bracketed severity label inserted into log messages at Info level. Value: [INFO].

Declaration
public const string LABEL_INFO = "[INFO]"
Field Value
Type Description
string

LABEL_NOTICE

The bracketed severity label inserted into log messages at Notice level. Value: [NOTICE].

Declaration
public const string LABEL_NOTICE = "[NOTICE]"
Field Value
Type Description
string

LABEL_SYSTEM

The bracketed severity label inserted into log messages at System level. Value: [SYSTEM].

Declaration
public const string LABEL_SYSTEM = "[SYSTEM]"
Field Value
Type Description
string

LABEL_TRACE

The bracketed severity label inserted into log messages at Trace level. Value: [TRACE].

Declaration
public const string LABEL_TRACE = "[TRACE]"
Field Value
Type Description
string

LABEL_WARNING

The bracketed severity label inserted into log messages at Warning level. Value: [WARNING].

Declaration
public const string LABEL_WARNING = "[WARNING]"
Field Value
Type Description
string

LOG_PREFIX

The framework-wide log prefix prepended to every log message to identify it as originating from Scylla. Formatted as [Scylla] using the framework short name defined in ScyllaCore.Meta.SHORT_NAME.

Declaration
public const string LOG_PREFIX = "[Scylla]"
Field Value
Type Description
string

Properties

IsHistoryEnabled

Gets whether log history storage is currently enabled. History is disabled after being consumed via ConsumeLogHistory().

Declaration
public static bool IsHistoryEnabled { get; }
Property Value
Type Description
bool

MaxBufferSize

Maximum number of log entries to buffer when no receivers are registered. Prevents unbounded memory growth during initialization.

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

MaxHistorySize

Maximum number of log entries to retain in the permanent history. Prevents unbounded memory growth while keeping recent logs available.

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

Methods

Clear()

Clears the log of any registered log receiver.

Declaration
public static void Clear()

ClearLogBuffer()

Clears the log buffer without flushing entries to receivers. Useful for clearing buffered logs that are no longer needed.

Declaration
public static void ClearLogBuffer()

ClearLogHistory()

Clears the permanent log history without disabling future storage. Use this when you want to reset the log history (e.g., on scene reload). To also disable future storage, use ConsumeLogHistory() instead.

Declaration
public static void ClearLogHistory()

ConsumeLogHistory()

Retrieves all log history entries, clears the history, and disables future storage. This is the preferred method for components like DebugConsole that need the initial log history but will receive subsequent logs through the receiver system. After calling this method, no further entries will be added to the history.

Declaration
public static LogEntry[] ConsumeLogHistory()
Returns
Type Description
LogEntry[]

An array containing all log entries in the history, oldest first.

CreateLogEntry(object, string, LogCategory, LogLevel, bool?, string, int)

Creates a LogEntry for testing purposes. This method formats the entry similar to FormatLogEntry but can be called without registered receivers.

Declaration
public static LogEntry CreateLogEntry(object data, string label, LogCategory category, LogLevel logLevel, bool? includeLabel = null, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The data or message to be logged.
string label

The label associated with the log message.
LogCategory category

The category of the log.
LogLevel logLevel

The severity level of the log message.
bool? includeLabel

Whether to include the label (defaults to true if logLevel >= LogLevel.Minimum).
string filePath

The source file path where the log call was made. Optional for testing.
int lineNumber

The line number in the source file where the log call was made. Optional for testing.
Returns
Type Description
LogEntry

A formatted LogEntry value object.

Debug(object, LogCategory, string, int)

Logs a debug-level message with the specified log category. This method is conditionally compiled - calls are removed at compile time unless DEBUG is defined. In release builds, Debug log calls have zero runtime overhead.

Declaration
[Conditional("DEBUG")]
public static void Debug(object data, LogCategory category, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The data or message to be logged.
LogCategory category

The category associated with the log message, indicating the context or purpose of the log.
string filePath

The source file path where the log call was made. Automatically populated by compiler.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by compiler.

Debug(object, string, int)

Logs a message at the Debug severity level without associating it with any LogCategory. Debug messages carry developer-facing diagnostics that are useful during development and testing but should not appear in production logs. Unlike Trace(object, string, int), debug messages are typically more structured and may persist across multiple iterations of a feature before being removed.

This method is conditionally compiled with the DEBUG symbol. In release builds the entire call site is eliminated by the compiler, producing zero runtime overhead.

Declaration
[Conditional("DEBUG")]
public static void Debug(object data, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The message or object to log. If null, the string "null" is written. Non-string objects are converted via ToString().
string filePath

The source file path where the log call was made. Automatically populated by the compiler via CallerFilePathAttribute.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by the compiler via CallerLineNumberAttribute.

Delimiter(LogCategory, string, int)

Logs a delimiter line to the specified log category at the system log level. Delimiters are not affected by filtering.

Declaration
public static void Delimiter(LogCategory category, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
LogCategory category

The category to which the delimiter line should be logged.
string filePath

The source file path where the log call was made. Automatically populated by compiler.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by compiler.

Delimiter(string, int)

Logs a delimiter line to the output if logging is enabled. Delimiters use System level and are not affected by filtering.

Declaration
public static void Delimiter(string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
string filePath

The source file path where the log call was made. Automatically populated by compiler.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by compiler.

EnableLogHistory()

Re-enables log history storage. Call this if you need to start collecting history again after it was consumed. Typically used when reinitializing the logging system (e.g., after domain reload).

Declaration
public static void EnableLogHistory()

Error(object, LogCategory, string, int)

Logs an error message with the specified category and data when a critical issue occurs.

Declaration
public static void Error(object data, LogCategory category, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The data or message to be logged, providing detailed information about the error event.
LogCategory category

The category of the log message, providing additional context about the source or area of the issue.
string filePath

The source file path where the log call was made. Automatically populated by compiler.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by compiler.

Error(object, string, int)

Logs an error message with the default log category.

Declaration
public static void Error(object data, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The message or object to log as an error.
string filePath

The source file path where the log call was made. Automatically populated by compiler.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by compiler.

Fatal(object, LogCategory, string, int)

Logs a message with the "Fatal" log level, which indicates a critical error that requires immediate attention and may terminate the application.

Declaration
public static void Fatal(object data, LogCategory category, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The content of the log message, typically describing the fatal issue for debugging or troubleshooting purposes.
LogCategory category

The category under which the log entry should be recorded, providing context to the source or type of the log.
string filePath

The source file path where the log call was made. Automatically populated by compiler.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by compiler.

Fatal(object, string, int)

Logs a message with the fatal error level.

Declaration
public static void Fatal(object data, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The message or object to log as a fatal error.
string filePath

The source file path where the log call was made. Automatically populated by compiler.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by compiler.

GetBufferedLogCount()

Gets the number of log entries currently buffered (waiting for receivers to be registered).

Declaration
public static int GetBufferedLogCount()
Returns
Type Description
int

The number of buffered log entries.

GetLogHistory()

Gets a copy of the permanent log history without modifying it. For most use cases, prefer ConsumeLogHistory() which also clears and disables history storage to avoid redundant memory usage.

Declaration
public static LogEntry[] GetLogHistory()
Returns
Type Description
LogEntry[]

An array containing all log entries in the history, oldest first.

GetLogHistoryCount()

Gets the number of log entries in the permanent history.

Declaration
public static int GetLogHistoryCount()
Returns
Type Description
int

The number of entries in the history.

Info(object, LogCategory, string, int)

Logs an informational message with the specified category and data. This method is always compiled (not conditionally compiled).

Declaration
public static void Info(object data, LogCategory category, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The data or message to be logged.
LogCategory category

The category of the log message.
string filePath

The source file path where the log call was made. Automatically populated by compiler.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by compiler.

Info(object, string, int)

Logs a message at the Info severity level without associating it with any LogCategory. Info messages are intended for production logs that confirm normal application behavior - successful initialization, configuration values loaded, expected state transitions - and should remain useful to operators after release. This method is always compiled and present in release builds; it respects FilterLevel.

Declaration
public static void Info(object data, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The message or object to log. If null, the string "null" is written. Non-string objects are converted via ToString().
string filePath

The source file path where the log call was made. Automatically populated by the compiler via CallerFilePathAttribute.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by the compiler via CallerLineNumberAttribute.

Notice(object, LogCategory, string, int)

Sends a log message at the "Notice" log level with the specified category. This method is always compiled (not conditionally compiled).

Declaration
public static void Notice(object data, LogCategory category, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The data or message to be logged.
LogCategory category

The category of the log message.
string filePath

The source file path where the log call was made. Automatically populated by compiler.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by compiler.

Notice(object, string, int)

Logs a message at the Notice severity level without associating it with any LogCategory. Notice messages are a step above Info(object, string, int) in visibility: they describe noteworthy events - significant milestones, unexpected but benign conditions, or state changes that deserve extra attention - without implying that anything has gone wrong. This method is always compiled and present in release builds; it respects FilterLevel.

Declaration
public static void Notice(object data, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The message or object to log. If null, the string "null" is written. Non-string objects are converted via ToString().
string filePath

The source file path where the log call was made. Automatically populated by the compiler via CallerFilePathAttribute.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by the compiler via CallerLineNumberAttribute.

RegisterLogReceiver(ILogReceiver)

Registers a log receiver to receive logging output with default priority (100). Lower priority numbers indicate higher priority (0 = highest priority). If there are buffered log entries (from before receivers were registered), they will be flushed to the newly registered receiver.

Declaration
public static void RegisterLogReceiver(ILogReceiver logReceiver)
Parameters
Type Name Description
ILogReceiver logReceiver

The log receiver to be registered for handling log messages.

RegisterLogReceiver(ILogReceiver, int)

Registers a log receiver to receive logging output with a specified priority. Receivers are called in priority order (lower numbers first), then by insertion order for receivers with the same priority. This allows critical receivers (e.g., file logging) to receive logs before less critical ones (e.g., in-game console). If there are buffered log entries (from before receivers were registered), they will be flushed to the newly registered receiver.

Declaration
public static void RegisterLogReceiver(ILogReceiver logReceiver, int priority)
Parameters
Type Name Description
ILogReceiver logReceiver

The log receiver to be registered for handling log messages.
int priority

The priority of the receiver. Lower numbers indicate higher priority (0 = highest priority). Default is 100. Receivers with the same priority maintain insertion order.
Remarks

Priority ordering is useful for scenarios where:

  • File logging should receive logs before in-game console (file logging = priority 0, console = priority 200)
  • Critical error handlers should process logs first
  • Receivers that filter/modify logs should process before receivers that display them

System(object, LogCategory, string, int)

Logs a message with System log level and the specified log category.

Declaration
public static void System(object data, LogCategory category, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The data or content to be logged.
LogCategory category

The category of the log message, representing the context of the log.
string filePath

The source file path where the log call was made. Automatically populated by compiler.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by compiler.

System(object, string, int)

Logs a message at the System severity level without associating it with any LogCategory. The System level is reserved for Scylla infrastructure messages - module lifecycle events, framework initialization, and subsystem status reports. Unlike all other levels, System messages bypass the FilterLevel check and are always delivered to receivers as long as IsEnabled is true. This method is always compiled and present in release builds.

Declaration
public static void System(object data, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The message or object to log. If null, the string "null" is written. Non-string objects are converted via ToString().
string filePath

The source file path where the log call was made. Automatically populated by the compiler via CallerFilePathAttribute.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by the compiler via CallerLineNumberAttribute.

Test()

Shortcut method used for testing the logger and any registered log receivers.

Declaration
public static void Test()

Trace(object, LogCategory, string, int)

Logs a message with the trace log level and specified category. This method is conditionally compiled - calls are removed at compile time unless DEBUG is defined. In release builds, Trace log calls have zero runtime overhead.

Declaration
[Conditional("DEBUG")]
public static void Trace(object data, LogCategory category, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The information or data to be logged.
LogCategory category

The category under which the log message should be classified.
string filePath

The source file path where the log call was made. Automatically populated by compiler.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by compiler.

Trace(object, string, int)

Logs a message at the Trace severity level without associating it with any LogCategory. Trace is the lowest production-visible level and is intended for short-lived instrumentation: inspecting a single property value, confirming a code path is entered, or emitting a temporary message during active development. These calls should be removed before merging to a shared branch.

This method is conditionally compiled with the DEBUG symbol. In release builds the entire call site is eliminated by the compiler, producing zero runtime overhead.

Declaration
[Conditional("DEBUG")]
public static void Trace(object data, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The message or object to log. If null, the string "null" is written. Non-string objects are converted via ToString().
string filePath

The source file path where the log call was made. Automatically populated by the compiler via CallerFilePathAttribute.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by the compiler via CallerLineNumberAttribute.

Unity(object, LogLevel)

Outputs a log message to Unity's console using the specified log level. This method bypasses the framework's internal logging system and directly invokes Unity's logging API.

Declaration
public static void Unity(object data, LogLevel logLevel = LogLevel.Debug)
Parameters
Type Name Description
object data

The log message or object to be outputted to Unity's console.
LogLevel logLevel

The severity level of the log message, defaulting to Debug. Determines the log handling behavior in Unity's console.

UnregisterAllReceivers()

Unregisters all log receivers. Useful for testing or cleanup.

Declaration
public static void UnregisterAllReceivers()

UnregisterLogReceiver(ILogReceiver)

Unregisters a log receiver from receiving logging output.

Declaration
public static void UnregisterLogReceiver(ILogReceiver logReceiver)
Parameters
Type Name Description
ILogReceiver logReceiver

The log receiver to unregister.

Warning(object, LogCategory, string, int)

Logs a warning message with the specified category and data.

Declaration
public static void Warning(object data, LogCategory category, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The data or message to be logged as a warning.
LogCategory category

The category associated with the log message.
string filePath

The source file path where the log call was made. Automatically populated by compiler.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by compiler.

Warning(object, string, int)

Logs a message at the Warning severity level without associating it with any LogCategory. Warnings signal that a non-critical problem occurred but the application can continue operating. Common uses include recoverable errors, deprecated API usage, missing optional resources, or conditions that may worsen over time and should be addressed. This method is always compiled and present in release builds; it respects FilterLevel.

Declaration
public static void Warning(object data, string filePath = "", int lineNumber = 0)
Parameters
Type Name Description
object data

The message or object to log. If null, the string "null" is written. Non-string objects are converted via ToString().
string filePath

The source file path where the log call was made. Automatically populated by the compiler via CallerFilePathAttribute.
int lineNumber

The line number in the source file where the log call was made. Automatically populated by the compiler via CallerLineNumberAttribute.