Logging Standards
This project enforces a unified logging system through the GameLog service. This ensures high performance (via ZString) and consistent prefixing for easy filtering in the Unity Console.
🛑 Technical Protocol (MANDATORY)
NEVER use UnityEngine.Debug directly in feature code.
All logging must go through _ArchSurvivor.Core.Utilities.GameLog.
1. Unified API Mapping
| Legacy Call | Standard Replacement | Purpose |
|---|---|---|
Debug.Log | GameLog.Info | General information, state transitions. |
Debug.LogWarning | GameLog.Warning | Non-critical issues, potential bugs. |
Debug.LogError | GameLog.Error | Critical failures, missing components. |
| (New) | GameLog.Verbose | High-frequency data (Drawn with grey color). Automatically stripped in production builds. |
2. Performance (ZString)
GameLog internally uses ZString.Concat to merge the global prefix [ArchSurvivor] with your message. This prevents string allocations (GC pressure) during logging.
🎨 Best Practices
1. Contextual Prefixing
Add a module prefix in square brackets to your message for better readability:
- •✅
GameLog.Info("[KCC] Player initialized"); - •✅
GameLog.Error("[FSM] State transition failed");
2. High-Frequency Logs
For logs that run in Update or FixedUpdate, strictly use GameLog.Verbose. This ensures they are compiled out of the final game, maintaining peak performance for players.
3. Rich Text Usage
Use standard Unity rich text tags to highlight important values:
- •
GameLog.Info($"Damage applied: <b>{amount}</b>"); - •
GameLog.Warning($"<color=orange>Cooldown active</color>");
🚀 Automation (/log)
Use the /log workflow to automatically scan the current file or specific directory and migrate legacy Debug.Log calls to GameLog.
Verification Checklist
Before committing code:
- • No references to
UnityEngine.Debug(except in low-level core utilities). - • Correct severity level chosen (Info vs Warning vs Error).
- • High-frequency logs shifted to
Verbose. - • Descriptive prefixes added to all log messages.