f8-features-log-workflow

name	f8-features-log-workflow
description	Use when implementing or troubleshooting Log feature workflows — logging, file writing, error reporting, LogViewer, and debug commands in F8Framework.

Log Feature Workflow

⚠️ IMPORTANT: Before using this feature, you MUST formally initialize F8Framework in the launch sequence. Ensure ModuleCenter.Initialize(this); has run first, then create the required module, for example FF8.LogWriter = ModuleCenter.CreateModule<F8LogWriter>();.

Use this skill when

• The task is about logging, debug output, file-based log writing, or error reporting.
• The user asks about LogViewer, cheat codes, or debug commands.

Path resolution

1. Prefer project source at Assets/F8Framework.
2. For usage docs, read: Assets/F8Framework/Tests/Log/README.md

Sources of truth

• Runtime module: Assets/F8Framework/Runtime/Log
• Test docs: Assets/F8Framework/Tests/Log

Key classes and interfaces

Class	Role
LogF8	Static logging class. Multiple log channels and utility methods.
LogWriter	Module for file-based log writing. Access via FF8.LogWriter.
Function	LogViewer command system.

API quick reference

Basic logging

LogF8.Log(message);                    // General log
LogF8.Log("Format {0}", 1);           // Formatted log
LogF8.Log("Message", this);            // With object context (clickable in Console)
LogF8.LogNet("Network {0}", "data");   // Network channel
LogF8.LogEvent(data);                  // Event channel
LogF8.LogConfig(data);                 // Config channel
LogF8.LogView(data);                   // View channel
LogF8.LogEntity(data);                // Entity channel
LogF8.LogStackTrace("Stack trace");    // With stack trace

Thread-safe logging

LogF8.LogToMainThread("From background thread");
LogF8.LogErrorToMainThread("Error from background thread");

Log control

LogF8.EnabledLog();    // Enable logging
LogF8.DisableLog();    // Disable logging

File writing

FF8.LogWriter.OnEnterGame(); // Start writing logs to file

Error capture

LogF8.GetCrashErrorMessage(); // Start capturing error logs

Performance monitoring

LogF8.Watch();                // Start monitoring
LogF8.Log(LogF8.UseMemory);   // Memory usage
LogF8.Log(LogF8.UseTime);     // Time elapsed

LogViewer commands

// Add debug command to LogViewer
Function.Instance.AddCommand(this, "MethodName", new object[] { param });

// Add cheat code callback
Function.Instance.AddCheatKeyCallback((cheatKey) =>
{
    LogF8.Log("Cheat: " + cheatKey);
});

LogViewer activation

• Keyboard: press tilde key ~
• Mobile: five-finger long press for 1 second

Workflow

1. Use LogF8.Log() for general-purpose debug output.
2. Use channel-specific methods for organized logging (Net, Event, Config, View, Entity).
3. Enable file writing with FF8.LogWriter.OnEnterGame() for production logging.
4. Add GetCrashErrorMessage() for crash error capture.
5. Add LogViewer to scene for runtime debug console.
6. Register debug commands via Function.Instance.AddCommand().

Common error handling

Error	Cause	Solution
Logs not appearing	DisableLog() was called	Call EnabledLog()
File write permission	No write access to log directory	Ensure persistentDataPath is writable
Background thread log crash	Using Unity API from background thread	Use LogToMainThread() instead
LogViewer not showing	Component not in scene	Add LogViewer GameObject or load as asset

Cross-module dependencies

• None — Log is a foundational utility used by all modules.

Output checklist

• Logging pattern selected (channel-based, file-based, error capture).
• LogViewer configuration documented.
• Files changed and why.
• Validation status and remaining risks.