CLogger

Using CLogger in Your Game Engine

The CLogger system provides a structured way to log information during the development and execution of your game engine. This guide will walk you through setting up and using CLogger effectively within your engine.

Table of Contents

• Introduction
• Setting up CLogger
• Basic Logging
  • Info Logs
  • Warning Logs
  • Debug Logs
  • Error Logs
  • Fatal Logs
  • Lifecycle Logs
• Async Logging
• Contextual Logging
• Logging Exceptions
• Customizing Logger
  • Log Format
  • Log Level
  • Global and Local Loggers

Introduction

CLogger is designed to help game developers track important information while the game engine runs. It supports different logging levels, async logging, and customizable formats. Whether you are debugging, tracking engine lifecycles, or managing errors, CLogger provides a flexible and powerful solution.

---

Setting up CLogger

1. Create an instance of the logger
   Each class in the engine can have its own logger instance. You can create a logger using the CLoggerSystem:

   CLogger logger = CLoggerSystem.logger(MyGameEngine.class);

2.Set up logging in your engine's main class Use the singleton pattern for global logging:

public class MyGame {
    private static final CLogger logger = CLoggerSystem.logger(MyGame.class);
    
    public static void main(String[] args) {
        logger.info("Game Engine started");
        // Other game logic
    }
}

Basic Logging

Info Logs

Use info() to log general informational messages.

logger.info("loaded image successfully from --> "+path);

Warning Logs

To log potential issues, use warn():

logger.warn("scene is changed to -> "+scene.getName());

Debug Logs

For debugging purposes, debug() logs can provide detailed insights during development:

logger.debug("creating helper for -> "+path);

Error Logs

When a non-critical issue occurs, use error():

logger.error("Failed to load texture");

Fatal Logs

For critical issues that require immediate attention:

logger.fatal("Unhandled exception occurred");

Lifecycle Logs

Log lifecycle events to track the state of your engine:

logger.lifecycle("Game Engine initialized");

Async Logging

You can log asynchronously to avoid blocking the main thread during logging operations. This is useful in performance-critical scenarios like game loops:

logger._ainfo("Loading assets asynchronously");

Async logging is available for all log levels by prefixing the method with an underscore (_), such as _ainfo(), _awarn(), _adebug(), etc.

Contextual Logging

Use CLoggerContext to log with context-specific information. This helps organize logs by associating them with different game states, objects, or actions.

logger.info(EngineContexts.DISPOSE, "finished");

This will include context-specific data in your logs, making it easier to track the source of log messages.

Logging Exceptions

CLogger makes it easy to log exceptions with additional context:

try {
    // Some code that throws an exception
} catch (Exception e) {
    logger.exc(e, "Error occurred during player movement");
}

If you want to log exceptions without throwing them again, use excFalse():

try {
    // Code that may throw an exception
} catch (Exception e) {
    logger.excFalse(e, "Non-critical error");
}

Customizing Logger

Log Format

You can customize how logs are formatted by modifying the CLoggerFormatter:

CLoggerFormatter formatter = CLoggerFormatter.getDefaultFormatter();
// Customize the formatter's elements
formatter.getElements().put("dateFormat", new ElementWithType<>("df:", "yyyy-MM-dd HH:mm:ss"));
CLogger logger = new CLogger(MyGameEngine.class, formatter);

every logger use engines default loggerformatter but you can change it.

formatter is a class that holds every data in log for example date,log-level,namespace of engine,etc. normal log of engine look like this:

{2024$10/22/12/43;::;12.43.52.447+03:00}--[cakilgan;::;CLogger]--[CEngine]--(INFO)--cengine/dispose#--> finished

1. date
2. namespace
3. class that holds logger
4. level
5. context
6. msg

you can remove or add a new element for formatter.

you can make it simple by removing namespace,changin date format or something like that its up to you!

Log Level

You can control the level of logs that get output. For instance, you might only want to log warnings and above:

logger.setLogLevel(Level.WARNING);

You can also set global log levels that apply to all instances of CLogger:

CLogger.setGlobalLogLevel(Level.INFO);

Global and Local Loggers

You can have a global logger for system-wide events and local loggers for class-specific events. Use CLoggerSystem to manage these loggers centrally:

CLogger globalLogger = CLogger.getInstance();
CLogger localLogger = CLoggerSystem.logger(MyGameComponent.class);

The global logger can be used for overarching game engine logs, while the local loggers can be specialized for different components.