INFO

This is a script mod which modifies the logging functions in The Sims 4 to enable the game log file features. I'm not sure why no one has ever enabled the logging features of the game, or if they have they haven't released a script for it. So I decided to write one up for myself and share it with all of you. This is probably most useful for script modders; however, there is a lot of information logged that can be useful for tuning modders as well.

- Scumbumbo

INSTALL

This is a script mod, so to install it you should extract the Scumbumbo_SimsLogEnabler.ts4script file from the zip you downloaded into your Mods folder. It may be placed into a subfolder if desired, but it must not be more than one subfolder away from your Mods folder.

Don't forget that script mods must be enabled in your game options!

Additionally, to use an application for live view of the logs, extract the Sims Log Enabler UI.exe file from the zip you downloaded into the same folder as the Scumbumbo_SimsLogEnabler.ts4script file.

The actual log files will be placed into the folder with the Scumbumbo_SimsLogEnabler.ts4script file.

EXTRA

Usage

There is a HUGE amount of logging going on in the game and logging is enabled by default. There are two cheat console commands to enable and disable logging, but if you need logging disabled from the start there is a configuration variable (“ENABLE_LOGGING_AT_STARTUP”) that can be set for that in the sims_log_enabler.cfg file.

The two commands are:
logs.enable (to enable logging)
and
logs.disable (to disable logging)

Wow, almost too simple! There is one option that can be specified to the enable command. By default, when a log file is opened it will be overwritten because otherwise the log files can grow to huge sizes. Typically you will want this behavior. However, if you want to append to existing log files, you can specify the append flag on the enable command:
logs.enable append

Log files aren't actually created or opened until they are used. There are many log groups used in the game, and each group will have it's own log file. Some of these logs are more useful than others, and some you'll probably never use.

Each of the log files can contain entries at the specific log levels INFO, DEBUG, WARN, and ERROR. The log level for each entry is noted at the start of the line in square brackets. Immediately following that you may see an optional "owner" tag in square brackets, this is just the user at EA who is responsible for the particular section of code that is producing that log info. Not very useful, but I included it for completeness.

Configuration

There are eight configuration variables in the sims_log_enabler.cfg file which can be altered freely. Since these are processed when the game initially loads the mod they will only take effect when the game is restarted (so change them before starting the game).

ENABLE_LOGGING_AT_STARTUP
A lot of information is logged at the game startup, for example when the XML tuning is loaded any errors or warnings found in the XML is logged.

To disable logging at startup, simply alter the ENABLE_LOGGING_AT_STARTUP entry as follows:

Code:

"ENABLE_LOGGING_AT_STARTUP": false,

LAUNCH_UI_AT_STARTUP (Windows Only)

The UI application for live view of logs is turned on automatically on game startup by default.

To turn off the UI application from being turned on at the game startup, alter the LAUNCH_UI_AT_STARTUP entry as follows:

Code:

"LAUNCH_UI_AT_STARTUP": false,

INCLUDE_TIMESTAMPS
Including timestamps will add the current system time to each line of the logs. This can be helpful when determining the order of events when comparing multiple log group files, or if you are appending to existing logs.

To turn off timestamps, alter the INCLUDE_TIMESTAMPS entry as follows:

Code:

"INCLUDE_TIMESTAMPS": false,

(note that the UI needs enabling timestamps separately)

INCLUDE_OWNER_INFO
By default, owner info is not included on each log line. Enabling this option will add the ownership tags ti log lines, so you will see the usernames of EA coders who are responsible for various sections of the code.

To enable ownership info, alter the INCLUDE_OWNER_INFO entry as follows:

Code:

"INCLUDE_OWNER_INFO": true,

USE_LINE_BUFFERING
By default, line buffering is off. Using line buffering will slow down logging a bit, but will enable other programs (for instance Notepad++) which can detect that a file has changed and reload it on the fly. Without line buffering on, changes to the log files will not be apparent to these programs until the log file has been closed and reopened.

To turn on line buffering, alter the USE_LINE_BUFFERING entry as follows:

Code:

"USE_LINE_BUFFERING": true,

ENABLE_AUTO_FLUSH
This option is of limited use and is primarily intended for script modders. The only reason you will want to enable this mode is if you are concerned with losing log entries due to the game crashing to desktop. Enabling auto flush will cause the log files to be flushed to disk every time a log entry is written. This option will slow down logging a bit.

To turn on auto flush, (you guessed it) alter the ENABLE_AUTO_FLUSH entry as follows:

Code:

"ENABLE_AUTO_FLUSH": true,

Script

Disabling Specific Log Levels
If you have no interest in a particular log level, they can be disabled (or re-enabled) by modifying them at the end of the script. Simply comment out the log levels you wish to turn off. For instance, to disable the INFO and DEBUG log levels, you would modify these lines to appear as follows:

Code:

# sims4.log.Logger.info = info
# sims4.log.Logger.debug = debug
sims4.log.Logger.warn = warn
sims4.log.Logger.error = error

The two lines immediately after these log level settings should not be changed. These enable some missing code in the SimInfo class of the game so that the logs will contain the full name of sims instead of a blank.

Creating Your Own Log Group

Script modders may wish to utilize the game's log file processing now that it is accessible via this mod. Creating your own log file group is very easy and will allow you to include log entries in your mod and leave them in when packaging the mod for players. Your mod will only produce actual logging when you have this mod installed, and if it's not installed (or enabled) the game's empty logging features will simply ignore the log entries without the possibility of creating exception errors.

To create your own log group, you simply include the sims4.log module and create an instance of the Logger class. I suggest using the EA standard and calling the log "logger". If you want your log entries to include an owner tag, include that in the default_owner argument to the Logger class. For instance:

Code:

import sims4.log
logger = sims4.log.Logger('My Mod Name', default_owner='Scumbumbo')

In your code, you can then call any of the log level methods (info, debug, warn or error) to produce log output, like so:

Code:

import sims4.log
logger = sims4.log.Logger('My Mod Name', default_owner='Scumbumbo')

def my_function(value, obj=None):
    if obj is None:
        logger.warn('my_function called with no obj')

    # You can specify formatting and arguments to the logger functions, too
    logger.debug('Setting object {} value {}', obj, value)

    if not obj.do_something(value):
        logger.error('do_something failed')

    # Watch out for extraneous {}'s in a log entry.
    some_dict = {'red': 1, 'blue': 2}
    my_message = 'This will throw an exception: some_dict={}'.format(some_dict)
    logger.info(my_message, owner='me')

    # I consider the above a bug; however, it is consistent with the game's logging code.  To work
    # around this, EA does the following: If you must preformat a line that contains 
    # the {} characters you must not have a default_owner or owner keyword arg included,
    # and you must not include other formatting and arguments.
    logger.info('If we include {} here, we can safely log this', some_dict, owner='okaytouseowner')
    logger.info('The next one will work too (assuming no default_owner is present) as no args are included')
    logger.info(my_message)

# Finally, logging lines which run when the module is loaded may or may not work
# depending on what script gets loaded first.  I haven't found any method to guarantee
# that sims_log_enabler gets loaded first.
logger.info('This log entry probably won\'t show up as sims_log_enabler has not loaded yet')

I think that covers mostly everything.