punkfuncgames/.claude/skills/log-module

LogModule Skill

Module Overview

Centralized logging service replacing all direct Debug.Log usage. Provides log levels, category tags, reactive log stream, configurable minimum level, and ring-buffer history.

Package: com.punkfuncgames.log | Define: PUNKFUNC_LOG

Directory Structure

Packages/com.punkfuncgames.log/Runtime/PunkFuncGames.Log/
  ├── Model/LogLevel.cs           # Log level enum (Trace→Off)
  ├── Model/LogEntry.cs           # Immutable log entry struct
  ├── Config/LogSettings.cs       # ScriptableObject configuration
  ├── Service/ILogService.cs      # Public interface
  ├── Service/LogService.cs       # Implementation
  └── Installer/LogInstaller.cs   # VContainer installer

Key Types

LogLevel Enum

Trace(0) < Debug(1) < Info(2) < Warning(3) < Error(4) < Fatal(5) < Off(6)

• Messages below MinimumLevel are suppressed
• Trace/Debug stripped in release builds via #if !UNITY_EDITOR && !DEVELOPMENT_BUILD

LogEntry (readonly struct)

public readonly LogLevel Level;
public readonly string Category;
public readonly string Message;
public readonly DateTime Timestamp;

ILogService Interface

public interface ILogService : IService
{
    ReadOnlyReactiveProperty<LogLevel> MinimumLevel { get; }
    Observable<LogEntry> LogStream { get; }
    IReadOnlyList<LogEntry> History { get; }

    void SetMinimumLevel(LogLevel level);

    void Trace(string category, string message);
    void Debug(string category, string message);
    void Info(string category, string message);
    void Warning(string category, string message);
    void Error(string category, string message);
    void Fatal(string category, string message);
    void Log(LogLevel level, string category, string message);
}

LogSettings (ScriptableObject — Config + Data Pattern)

Thin wrapper: public LogSettingsData data; Access fields via _settings.data.fieldName.

LogSettingsData ([Serializable] public struct, camelCase fields):

minimumLevel: LogLevel (default: Debug)
historyCapacity: int (default: 256)
enableTimestamps: bool (default: true)
enableCategoryPrefix: bool (default: true)
timestampFormat: string (default: "HH:mm:ss.fff")

Installation

// In ProjectLifetimeScope — registered FIRST before all other modules
LogInstaller.Install(builder, _logSettings);

Usage Patterns

Constructor Injection (pure C# services)

public class MyService : IMyService
{
    private const string LOG_CATEGORY = "MyModule";
    private readonly ILogService _logService;

    public MyService(ILogService logService)
    {
        _logService = logService;
    }

    public void DoWork()
    {
        _logService.Info(LOG_CATEGORY, "Starting work...");
        _logService.Debug(LOG_CATEGORY, $"Processing {count} items");
    }
}

[Inject] Method Injection (MonoBehaviours)

public class MyView : MonoBehaviour
{
    private ILogService _logService;

    [Inject]
    public void Construct(ILogService logService = null)
    {
        _logService = logService;
    }

    private void OnError(string msg)
    {
        _logService?.Error("UI", msg);
    }
}

Optional Injection (infrastructure classes)

public class MyUtility
{
    private readonly ILogService _logService;

    public MyUtility(ILogService logService = null)
    {
        _logService = logService;
    }

    private void OnProblem(string msg)
    {
        _logService?.Warning("Utility", msg);  // null-safe
    }
}

Subscribing to Log Stream

_logService.LogStream
    .Where(e => e.Level >= LogLevel.Warning)
    .Subscribe(entry => debugUI.AddEntry(entry))
    .AddTo(_disposables);

Reading History

foreach (LogEntry entry in _logService.History)
{
    console.AppendLine($"[{entry.Level}] [{entry.Category}] {entry.Message}");
}

Category Conventions

| Category | Used By | |----------|---------| | "Bootstrap" | BootstrapOrchestrator, all bootstrap phases | | "Save" | SaveMigrator, BinarySerializer, AesEncryption | | "Pool" | PoolService | | "Wallet" | WalletService | | "Stats" | StatsService | | "Time" | TimeService | | "FloatingText" | FloatingTextService | | "Localization" | LocalizedImage, LocalizedAudio |

Dependencies

• R3: ReactiveProperty, Subject, Observable
• Core: IService interface

Console Output Routing

| LogLevel | Unity Method | |----------|-------------| | Trace, Debug, Info | Debug.Log() | | Warning | Debug.LogWarning() | | Error, Fatal | Debug.LogError() |

Test Helpers

• MockFactory.CreateLogService(LogLevel minimumLevel = LogLevel.Trace) — NSubstitute mock
• TestFixtures.CreateLogSettings(...) — ScriptableObject fixture with data struct initialized
• Tests: Packages/com.punkfuncgames.log/Tests/EditMode/LogServiceTests.cs