DCS_MissionDev/Moose_CTLD_Pure/LOGGING_GUIDE.md

Moose_CTLD Logging System

Overview

A comprehensive logging system has been implemented to control the verbosity of log output in production environments.

LogLevel Configuration

Add to your CTLD configuration:

local ctld = CTLD:New({
  LogLevel = 2,  -- Set desired logging level (0-4)
  -- ... other config
})

Log Levels

Level	Name	Description	Use Case
0	NONE	No logging at all	Production servers where logging causes performance issues
1	ERROR	Only critical errors and warnings	Production - only see problems
2	INFO	Important state changes, initialization, cleanup	Default for production
3	VERBOSE	Detailed operational info (zone validation, builds, MEDEVAC events)	Debugging missions
4	DEBUG	Everything including hover checks, detailed spawns	Deep troubleshooting

Default Setting

LogLevel = 2 (INFO) - Recommended for production servers

• Shows initialization, catalog loading, cleanup
• Shows errors and warnings
• Hides verbose MEDEVAC details, zone validation, debug info

Changing Log Level In-Mission

Players with access to F10 menus can change logging on-the-fly:

Group Menus (per-player):

• F10 → CTLD → Admin/Help → Debug → [Select Level]

Coalition Menus:

• F10 → CTLD → Debug Logging → [Select Level]

Options:

• Enable Verbose (LogLevel 4) - Full debug output
• Normal INFO (LogLevel 2) - Default production level
• Errors Only (LogLevel 1) - Minimal logging
• Disable All (LogLevel 0) - No logging

What Gets Logged at Each Level

Level 0 (NONE)

• Nothing

Level 1 (ERROR)

• Missing Moose library
• Catalog loading failures
• Missing configured zones
• Menu errors
• MEDEVAC spawn failures
• Critical system errors

Level 2 (INFO) - RECOMMENDED

• All ERROR level messages
• System initialization
• Catalog merging
• Troop type loading
• MEDEVAC system init
• Cleanup/shutdown messages
• Salvage system operations
• Mobile MASH deployment

Level 3 (VERBOSE)

• All INFO level messages
• Zone state changes (activation/deactivation)
• Zone validation summary
• MEDEVAC crew spawning
• MEDEVAC crew pickup/delivery
• Vehicle respawn
• MASH zone registration
• Smoke pop events

Level 4 (DEBUG)

• All VERBOSE level messages
• Config merge details
• MASH zone existence checks
• Crate cleanup
• Troop group cleanup
• Troop spawn details
• Detailed MEDEVAC event processing
• Catalog search operations
• Position extraction attempts
• Crew composition details
• Immortality/invisibility toggles
• Crew movement AI
• Hover detection (if implemented)

Examples

Production Server (Minimal Logging)

local ctld_blue = CTLD:New({
  CoalitionSide = coalition.side.BLUE,
  LogLevel = 1,  -- Errors only
  -- ... rest of config
})

Development/Testing (Full Logging)

local ctld_blue = CTLD:New({
  CoalitionSide = coalition.side.BLUE,
  LogLevel = 4,  -- Everything
  -- ... rest of config
})

Typical Production Setup

local ctld_blue = CTLD:New({
  CoalitionSide = coalition.side.BLUE,
  LogLevel = 2,  -- INFO - good balance
  -- ... rest of config
})

Migration from Old Debug Flag

The old Debug = true/false flag is now replaced by LogLevel:

Old way:

Debug = false  -- or true

New way:

LogLevel = 2  -- 0=NONE, 1=ERROR, 2=INFO, 3=VERBOSE, 4=DEBUG

Performance Notes

• LogLevel 0 (NONE) has zero overhead - no string formatting occurs
• LogLevel 1-2 have minimal overhead - only critical/important messages
• LogLevel 3-4 can generate significant log output - use for debugging only
• All logging goes to DCS.log file (not in-game messages)

Remaining Manual Replacements

Due to the large number of logging statements (150+), the following categories still use env.info() directly and should be replaced when needed:

1. MEDEVAC System (~80 statements) - Most verbose part

   • Event processing, crew spawning, pickup/delivery
   • Recommend: ERROR for failures, VERBOSE for operations, DEBUG for detailed state

2. Salvage/Build System (~10 statements)

   • Recommend: VERBOSE level

3. Cleanup System (~5 statements)

   • Recommend: INFO level

4. Troop System (~10 statements)

   • Recommend: VERBOSE for spawns, DEBUG for details

5. MASH Zones (~15 statements)

   • Recommend: VERBOSE for registration/operations, DEBUG for checks

To complete the migration, search for remaining env.info calls and replace with:

• _logError() for failures
• _logInfo() for important state changes
• _logVerbose() for operational details
• _logDebug() for troubleshooting info

Summary

The logging system is now in place with core functions defined. The most critical parts (initialization, zone validation, menu errors) have been updated. The remaining ~150 log statements (primarily MEDEVAC system) can be migrated incrementally as needed. For production use, simply set LogLevel = 1 or LogLevel = 2 to dramatically reduce log output.