The Sims 4 Modern Python Modding: Ultimate Loading Guide

This is the ultimate loading guide to how the game loads your script files. I sat down and tested numerous different combinations of trial and error in figuring out the loader. Here’s what I discovered:

Folder Structure

/Mods/

The top-level mods folder is meant only for packaged mods that end in ts4script or zip. If any folders are in this they are presumed to be a mod folder for extra organization, if any files are in this they are completely ignored.

The special Scripts folder mentioned below is treated like normal mod folder here. Thus Scripts/Scripts would still work but Scripts would not.

/Mods/Name of Mod

The folder directly underneath /Mods/ is presumed to to a mod folder for extra organization. This folder is given a special perk though. Like /Mods/ only ts4script or zip files are loaded and all files are ignored but unlike /Mods/ 1 additional folder is allowed in here and that is the Scripts folder.

Any other folders inside this are entirely ignored meaning extra organization can only go as deep as this one folder and no sub-folders.

/Mods/Name of Mod/Scripts

This is a special folder only allowed in the mod folder and intended to be for development only, files inside the Scripts folder can be nested many levels deep (only tested to 3 levels). The folder is recursively scanned for py files and, when found, are automatically loaded.

Any other files of any kind such as pyc, ts4script, or zip are completely ignored as they don’t belong in the special Scripts folder.

Another development benefit of this folder is you can re-load files from it anytime within a script while the game is running.

Packaged script files

The game loads only zip files, this includes zip files renamed to ts4script.

Only .py files

If you only have .py files in your zip folder then the game will not load them and will instead treat your mod as an empty mod.

Only .pyc files

If you only have .pyc files they are loaded as normal by the game.

Each version of python has a different code for .pyc this means if the games python version changes then your script will be attempted to load. Testing on incorrect python compilations revealed the game actually loaded the wrong compilation version sometimes successfully and strangely enough it has a higher success chance of loading the wrong compiled version if it’s in the /Mods/ folder and not a /Mods/Mod Folder sub-folder.

Most of the time, though, if your pyc file is compiled with the wrong version the game won’t be able to load it in which case it defaults to loading the py files. Since there are no py files in this case your mod will crash.

.py and .pyc files

If you have both .py and .pyc files then your mod is highly flexible but larger as it now contains duplicate code for every file (a compiled file and a source file).

This follows the same rules as above except the game will always load the py file. The pyc file will first be imported and then promptly deleted in memory followed by the compilation of the py file to a pyc file which will be imported to memory.

1. Game imports pyc to memory
2. Game deletes pyc from memory
3. Game compiles py to pyc internally
4. Game imports internally compiled pyc to memory

Since this is doing loading and deleting followed by compiling and loading and given the py file is going to be used anyways you might try and create an empty pyc file, especially since we already know the game will default to py if it can’t load the pyc. Unfortunately, an empty pyc file in this case results in a bigger crash and instead of the py file loading, your entire mod crashes. It defaults to py only if the pyc is a valid compiled file but the wrong compilation version.

.py and .pyo files

This is, strangely, your best option. When the game encounters a pyo file, even if it’s a phony/empty pyo file, the game solidly ignores it. It doesn’t try to import pyo, it skips it and jumps straight to importing the py file because it assumes it’s there.

1. Game sees pyo
2. Game compiles py to pyc internally
3. Game imports internally compiled pyc to memory

This means you can add your py source files along with an empty pyo file next to each one and the game will jump straight to loading the py files. It means your mod is flexible, is much smaller (no source and compiled files together), loads faster (compiled is not uselessly loaded first and then deleted and then compilation and loading of py files.), and survives game python updates.

In fact the only issue you’d run into with this situation is this depends on the pyo backwards compatibility so in the future if they remove the pyo loading backwards compatibility because it’s too out-of-date then your mod will not load.

Take this into consideration, the normal procedure is to add pyc files and py files to a mod even though the pyc files are never used. This is what EA expects going forward so take caution if you take advantage of a backwards compatibility feature to have smaller mods as eventually the code for it will be dropped, the pyo files will eventually be ignored, and your mod will stop loading.

.pyd files

The game completely ignores and doesn’t look for pyd files.

I hope this helps

I felt there was some confusion or too much vague information out there so I wanted to do many tests of my own to figure this out. I hope this helps you decide what to do.