Use CastleLog unit and call InitializeLog to have logging enabled. Call WritelnLog or WritelnWarning to log stuff.

Some engine functions also automatically write to this log. For example, initializing the OpenGL context logs the OpenGL and GPU features detected.

An example:

{$ifdef MSWINDOWS} {$apptype GUI} {$endif}
uses CastleLog, CastleWindow, CastleColors, CastleControls;
  Window: TCastleWindowBase;
  Lab: TCastleLabel;
  WritelnLog('My Log Message');
  WritelnLog('My Category', 'My Log Message');
  WritelnWarning('My Warning');
  // display the LogOutput value in a window
  Window := TCastleWindowBase.Create(Application);
  Lab := TCastleLabel.Create(Application);
  Lab.Caption := 'Logging to ' + LogOutput;
  Lab.Color := White;

'My Category' is useful to easily spot your messages later. There are no hard rules about it, you're free to just invent your own category names here, whatever works for you.

Where is the log stored?

  • When running from CGE editor, the log is displayed in the bottom editor panel.

  • When running using CGE build tool castle-engine run command, the log is displayed as the standard output.

  • When running the application as a normal user:

    • On Unix (Linux, macOS...), and for Windows console applications, logging by default goes to the standard output. This is the standard behavior for Unix and console apps.

      Users can redirect it by running the application from the command-line like my_game > log_file.log. The nice thing about it is that it avoids users asking questions "where is the log file".

      You can avoid this by setting LogEnableStandardOutput to false.

    • For Windows GUI applications, or if you set LogEnableStandardOutput := false, we log to the file in the user config directory.

      • On Windows the file name looks like C:\Users\<user-name>\AppData\Local\<application-name>\<application-name>.log.

      • On Unix the file name looks like $HOME/.config/<application-name>\<application-name>.log.

      The exact logic to determine the user config directory follows FPC GetAppConfigDir. This uses the suitable OS-specific mechanism (e.g. asks the Windows API function, or follows xdg-user-dirs conventions).

      You can display the LogOutput value to show user on screen where is the log file.

    • On Android the log goes to the standard device log. It that can be viewed using various Android tools, like adb logcat.

    • On iOS, Nintendo Switch it goes to the standard log facility for these devices.

  • You can pass a parameter to InitializeLog to generate log to any stream.

    You can also set LogFileName variable before calling the InitializeLog. This way you force using specific filename for logging, overriding the OS-specific auto-detection mechanism described above.

    User can also call the application with --log-file=c:/tmp/my_log_name.txt command-line option to set the location (and filename) explicitly. In fact, this way user sets the LogFileName variable. It will work if you call in your main program file Application.ParseStandardParameters;.