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.
- Game imports
pyc
to memory - Game deletes
pyc
from memory - Game compiles
py
topyc
internally - 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.
- Game sees
pyo
- Game compiles
py
topyc
internally - 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.