Skip to content

mwseLogger⚓︎

A class to facilitate printing log messages. A new one can be constructed by simply calling mwse.Logger.new(). See the Quickstart Guide for more information.

Properties⚓︎

abbreviateHeader⚓︎

If set to true, the header portion of all logging messages will be shortened. For example, suppose the following log message is written on line 20 of the file My Mod/Skills/Player/Combat/swords.lua. 

log("My message")
Then the resulting output to MWSE.log would be: 
-- abbreviateHeader == true:
[My Mod | s/p/c/swords:20  | D] My message
-- abbreviateHeader == false:
[My Mod | skills/player/combat/swords.lua:20  | DEBUG] My message
This does not affect how the "body" of log messages are displayed.

Returns:

  • result (boolean)

filepath⚓︎

The path to the file this mwseLogger was created in. This will be relative to the modDir.

For example, if this mwseLogger was constructed in mods/My Mod/main.lua, then the filepath will be main.lua.

Returns:

  • result (string)

formatter⚓︎

This is an advanced option and should be used with care. It allows specifying a custom formatter, allowing for more fine-tuned control over how log messages are printed. If supplying a formatter, you are responsible for also including the "header" portion of the log. These can be created by calling the protected makeHeader method.

Some examples can be found in the logger/formatters.lua folder of the core library.

Returns:

includeTimestamp⚓︎

If set to true, all the logged messages will include a timestamp.

Returns:

  • result (boolean)

level⚓︎

The current logging level.

Returns:

  • result (mwseLogger.logLevel)

logToConsole⚓︎

If true, all the logged messages will also be logged to the in-game console.

Returns:

  • result (boolean)

modDir⚓︎

The directory that your mod lives in. This is relative to Data Files/MWSE/mods.

Returns:

  • result (string)

modName⚓︎

Name of the mod, also counts as unique id of the logger.

Returns:

  • result (string)

moduleName⚓︎

Associates a logger with a particular "module". The moduleName will be printed in logging messages next to the modName. What does and does not constitute a "module" is entirely subjective. Use this field as you please. This can be useful if the filepath alone is not enough to distinguish what code is reponsible for issuing a log message. For example, the MWSE dependency management system uses a moduleName to alert the user about which mod had a dependency problem.

outputFile⚓︎

Determines where logging messages are printed. If false, log messages are printed to MWSE.log. If it's a string, then logging messages will be printed to Data Files/MWSE/logs/<log.outputFile>.log.

Setting this to true is the same as writing log.outputFile = log.modDir.

Returns:

  • result (string, boolean)

Methods⚓︎

assert⚓︎

Assert a condition and log an error if it fails.

myObject:assert(condition, message, ...)

Parameters:

  • condition (boolean)
  • message (string)
  • ... (any): Optional. Formatting arguments. These are passed to string.format.

debug⚓︎

Log a DEBUG message. This will only be printed if the current logging level is DEBUG or higher. If multiple arguments are passed, then they will be passed to string.format.

All table or userdata arguments will be prettyprinted. You can also pass a function as the first or second parameter to lazily evaluate log statements. See the Writing More Useful Log Messages and Passing Functions to Logging Methods sections of the Logging Guide for more information.

Shorthand Syntax

This method can also be called by writing log(message, ...) instead of log:debug(message, ...).

myObject:debug(message, ...)

Parameters:

  • message (string, fun(...): ...)
  • ... (any): Optional. Formatting arguments. These are passed to string.format. Tables and userdata values are pretty printed.

error⚓︎

Log an ERROR message. This will only be printed if the current logging level is ERROR or higher. If multiple arguments are passed, then they will be passed to string.format.

All table or userdata arguments will be prettyprinted. You can also pass a function as the first or second parameter to lazily evaluate log statements. See the Writing More Useful Log Messages and Passing Functions to Logging Methods sections of the Logging Guide for more information.

myObject:error(message, ...)

Parameters:

  • message (string, fun(...): ...)
  • ... (any): Optional. Formatting arguments. These are passed to string.format. Tables and userdata values are pretty printed.

getLevelString⚓︎

Gets a string representation of the current logging level.

local levelString = myObject:getLevelString(level)

Parameters:

  • level (mwseLogger.logLevel): Optional. If provided, a string representation of this logging level will be returned. If nil, then a string representation of the current logging level will be returned.

Returns:

  • levelString (string)

info⚓︎

Log an INFO message. This will only be printed if the current logging level is INFO or higher. If multiple arguments are passed, then they will be passed to string.format.

All table or userdata arguments will be prettyprinted. You can also pass a function as the first or second parameter to lazily evaluate log statements. See the Writing More Useful Log Messages and Passing Functions to Logging Methods sections of the Logging Guide for more information.

myObject:info(message, ...)

Parameters:

  • message (string, fun(...): ...)
  • ... (any): Optional. Formatting arguments. These are passed to string.format. Tables and userdata values are pretty printed.

setAbbreviateHeader⚓︎

Changes the abbreviateHeader field of this logger.

This function does exactly the same thing as log.abbreviateHeader = newAbbreviateHeader. Use whichever one you prefer.

myObject:setAbbreviateHeader(newAbbreviateHeader)

Parameters:

  • newAbbreviateHeader (boolean)

setFormatter⚓︎

Changes the formatter field of this logger.

This function does exactly the same thing as writing log.formatter = newFormatter. Use whichever one you prefer.

myObject:setFormatter(newFormatter)

Parameters:

setIncludeTimestamp⚓︎

Changes the includeTimestamp field of this logger.

This function does exactly the same thing as log.includeTimestamp = newIncludeTimestamp. Use whichever one you prefer.

myObject:setIncludeTimestamp(newIncludeTimestamp)

Parameters:

  • newIncludeTimestamp (boolean)

setLevel⚓︎

Set the log level. You can pass in either a string representation of a logging level, or the corresponding numerical constant found in the mwse.logLevel table. The options are: "TRACE", "DEBUG", "INFO", "WARN", "ERROR" and "NONE".

This function does exactly the same thing as writing log.level = newLogLevel. Use whichever one you prefer.

myObject:setLevel(newLogLevel)

Parameters:

  • newLogLevel (mwseLogger.logLevel, mwseLogger.logLevelString)

setModName⚓︎

Changes the modName field of this logger.

This function does exactly the same thing as writing log.modName = newModName. Use whichever one you prefer.

myObject:setModName(newModName)

Parameters:

  • newModName (string)

setModuleName⚓︎

Changes the moduleName field of this logger.

This function does exactly the same thing as writing log.moduleName = newModuleName. Use whichever one you prefer.

myObject:setModuleName(newModName)

Parameters:

  • newModName (string)

setOutputFile⚓︎

Set the output file. If set, logs will be sent to a file of this name.

This function does exactly the same thing as log.outputFile = newOutputFile. Use whichever one you prefer.

myObject:setOutputFile(outputFile)

Parameters:

  • outputFile (string, boolean): If true, then the modName field will be used as the filepath. If false, no custom output file will be used.

trace⚓︎

Log a TRACE message. This will only be printed if the current logging level is TRACE. If multiple arguments are passed, then they will be passed to string.format.

All table or userdata arguments will be prettyprinted. You can also pass a function as the first or second parameter to lazily evaluate log statements. See the Writing More Useful Log Messages and Passing Functions to Logging Methods sections of the Logging Guide for more information.

myObject:trace(message, ...)

Parameters:

  • message (string, fun(...): ...)
  • ... (any): Optional. Formatting arguments. These are passed to string.format. Tables and userdata values are pretty printed.

warn⚓︎

Log a WARN message. This will only be printed if the current logging level is WARN or higher. If multiple arguments are passed, then they will be passed to string.format.

All table or userdata arguments will be prettyprinted. You can also pass a function as the first or second parameter to lazily evaluate log statements. See the Writing More Useful Log Messages and Passing Functions to Logging Methods sections of the Logging Guide for more information.

myObject:warn(message, ...)

Parameters:

  • message (string, fun(...): ...)
  • ... (any): Optional. Formatting arguments. These are passed to string.format. Tables and userdata values are pretty printed.

writeInitMessage⚓︎

Writes an INFO message saying this mod has been initialized. If your mod has metadata file that specifies its current version, then that will also be included in the initialization message. You may also supply a version number directly as an argument to this method.

myObject:writeInitMessage(version)

Parameters:

  • version (string): Optional. The current version of your mod. If not provided, the logger will attempt to retrieve it from your mod's metadata file.

Functions⚓︎

get⚓︎

Gets a logger associated with a particular modDir. You can also filter by filepath as well.

local logger = mwseLogger.get(modDir, filepath)

Parameters:

  • modDir (string): The directory of mod to retrieve the loggers for. This argument corresponds to the lua-mod field of the mod's metadata file.
  • filepath (string): Optional. The filepath to retrieve the logger for. This is relative to modDir and corresponds to the filepath field of the logger to retrieve.

Returns:

  • logger (mwseLogger, nil): The logger, if it exists.

getLoggers⚓︎

Gets all the loggers registered to a particular modDir.

local loggers = mwseLogger.getLoggers(modDir)

Parameters:

  • modDir (string): The directory of mod to retrieve the loggers for. This argument corresponds to the lua-mod field of the mods metadata file.

Returns:

  • loggers (mwseLogger[], nil): The loggers, if they exist.

new⚓︎

Creates a new logger based on the input parameters.

local log = mwseLogger.new({ modName = ..., moduleName = ..., level = ..., logToConsole = ..., outputFile = ..., includeTimestamp = ..., abbreviateHeader = ..., formatter = ... })

Parameters:

  • params (table): Optional.
    • modName (string): Optional. The name of MWSE mod associated to this Logger. This will be retrieved automatically if not provided.
    • moduleName (string): Optional. The module this Logger is associated with. This can be useful for distinguishes which parts of your mod produce certain log messages. This will be displayed next to the name of the mod, in parentheses.
    • level (mwseLogger.logLevel, mwseLogger.logLevelString): Default: mwse.logLevel.info. The logging level for all loggers associated to this mod.
    • logToConsole (boolean): Default: false. Should the output also be written to the in-game console?
    • outputFile (boolean, string): Default: false. The path of the output file to write log messages in. This path is taken relative to Data Files/MWSE/logs/. If not provided, log messages will be written to MWSE.log. If true, then the modDir will be used as the output path.
    • includeTimestamp (boolean): Default: true. Should timestamps be included in logging messages? The timestamps are relative to the time that the game was launched.
    • abbreviateHeader (boolean): Default: false. Should the headers be abbreviated?
    • formatter (fun(self: Logger, record: mwseLogger.Record, ...: string|any|fun(...)): string): Optional. A custom formatter. This lets you customize how your logging messages are formatted. If not provided, the default formatter will be used.

Returns: