Unity Logging Extensions & Tag Formatter¶

Bring structured, color-coded logs to any Unity project without sprinkling Debug.Log everywhere. WallstopStudiosLogger adds extension methods (this.Log, this.LogWarn, this.LogError, this.LogDebug) that automatically capture component metadata, thread info, timestamps, and user-defined tags rendered by UnityLogTagFormatter.

• Thread-safe: Logs are marshaled back to the Unity main thread when required (via UnityMainThreadDispatcher / UnityMainThreadGuard).
• Readable output: Pretty mode prefixes time|GameObject[Component] when logging on the main thread and inserts |thread| only when background workers emit messages, keeping logs deterministic without extra noise.
• Tag formatter: Apply rich text decorations inline ($"{name:b,color=cyan}") without string concatenation. Tags deduplicate automatically and can be stacked in any order.

These helpers live in Runtime/Core/Extension/WallstopStudiosLogger.cs and Runtime/Core/Helper/Logging/UnityLogTagFormatter.cs. Tests at Tests/Runtime/Extensions/LoggingExtensionTests.cs demonstrate every supported scenario.

Sample Scene¶

• Import the Logging – Tag Formatter package sample and open Samples~/Logging - Tag Formatter/Scenes/LoggingDemo.unity.
• Press Play to use the on-screen toggles (global logging, component logging, pretty output) and emit Info/Warn/Error logs that showcase the decorators.
• Review LoggingDemoBootstrap (decorator registration) and LoggingDemoController (runtime toggles + this.Log* usage) to copy the patterns into your project.

Quick Start¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

using UnityEngine;
using WallstopStudios.UnityHelpers.Core.Extension;

public sealed class EnemyHUD : MonoBehaviour
{
    private void Start()
    {
        string mode = Application.isEditor ? "Test" : "Live";
        int hp = 42;

        this.Log(
            $"Player {"Rogue-17":b,color=orange} :: HP {hp:color=#FF4444} ({mode:italic})"
        );
    }
}

• Pass interpolated strings directly; the formatter applies tags before Unity renders the message.
• Use pretty: false if you only want the decorated text without the timestamp (or optional thread) prefix.
• Call this.LogWarn, this.LogError, or this.LogDebug for severity-specific output; all overloads accept Exception e to append stack traces.

Enabling logging in builds¶

ENABLE_UBERLOGGING is defined automatically for DEBUG, DEVELOPMENT_BUILD, and UNITY_EDITOR. Define it manually (or DEBUG_LOGGING / WARN_LOGGING / ERROR_LOGGING) in Player Settings if you need the extensions in release builds.

Default Tag Reference¶

• Combine tags using commas: $"{stats:json,b,color=yellow}" emits bold, colored JSON.
• Tags are applied in priority order and deduplicate automatically, so repeating :b has no effect.

Custom Decorations¶

Register project-specific tags at startup (for example, in an InitializeOnLoad editor script or a runtime bootstrapper):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

using WallstopStudios.UnityHelpers.Core.Extension;
using WallstopStudios.UnityHelpers.Core.Helper.Logging;

[InitializeOnLoad]
internal static class LoggingBootstrap
{
    static LoggingBootstrap()
    {
        UnityLogTagFormatter formatter = WallstopStudiosLogger.LogInstance;

        formatter.AddDecoration(
            predicate: tag => tag.StartsWith("stat:", StringComparison.OrdinalIgnoreCase),
            format: (tag, value) =>
            {
                string label = tag.Substring("stat:".Length);
                return $"<color=#7AD7FF>[{label}]</color> {value}";
            },
            tag: "StatLabel",
            priority: -10 // run before built-ins
        );
    }
}

Key APIs:

• AddDecoration(string match, Func<object,string> format, string tag, int priority = 0, bool editorOnly = false, bool force = false)
• AddDecoration(Func<string,bool> predicate, Func<string,object,string> format, string tag, int priority = 0, bool editorOnly = false, bool force = false)
• RemoveDecoration(string tag, out Decoration removed) to swap or disable decorators at runtime.
• UnityLogTagFormatter.Separator (',') controls how stacked tags are parsed.

Use negative priorities for “outer” wrappers (run earlier) and higher numbers for final passes. Setting force: true replaces existing tags with the same name.

Extension Method Cheat Sheet¶

Additional behavior:

• Thread routing: If a log originates off the main thread, the extension tries UnityMainThreadDispatcher.TryDispatchToMainThread first. If unavailable, it falls back to UnityMainThreadGuard.TryPostToMainThread and, if that fails, emits an “offline” log with a [WallstopMainThreadLogger:*] prefix.
• Pretty output: Keeps logs uniform (timestamp|GameObject[Component]|message on the main thread, inserting |thread| only for worker threads). Pass pretty: false when emitting data the Unity console already decorates (for example, performance CSV dumps).
• Context awareness: Unity context objects are forwarded to Debug.Log*, preserving click-to-focus navigation even when logs originate from pooled helper classes.

Best Practices¶

1. Register tags once — Use static constructors or [RuntimeInitializeOnLoadMethod] to register project-wide tags. Avoid allocating per-frame delegates.
2. Prefer interpolation — $"{health:json}" keeps minimal formatting allocations compared to string.Format.
3. Use pretty: false for exporters — When writing to files or parsing logs, disable prefixes to simplify downstream tooling.
4. Gate release builds — If you plan to leave logging enabled in production, explicitly define ENABLE_UBERLOGGING (or DEBUG_LOGGING / WARN_LOGGING / ERROR_LOGGING) and make sure log volume is acceptable (or wrap noisy calls in your own #defines).
5. Leverage tests — Tests/Runtime/Extensions/LoggingExtensionTests.cs covers every default tag and stacking scenario. Copy those patterns when adding new decorations to ensure behavior stays deterministic.

Related Topics¶

• Unity Main Thread Dispatcher — Ensures background logs can find the main thread safely.
• Helper Utilities Overview — Highlights other runtime helpers.