This is an easy to use front-end script for decompiling The Sims 4 scripts using the two available Python 3.7.0 decompilers. The script has been tested on both Windows and Mac installations. One or both of these decompilers must be obtained from their maintainers.
py37dec is a new program written by Fogity and is available for Windows and Mac from the Foggy Frontier web site.
unpyc3 has been heavily repaired, overhauled and updated by Andrew from Sims 4 Studio to work with Python 3.7.0 and his decompiler script is available from his GitHub repository.
You will need to download and install Python 3.7.0. Newer or older versions of the Python environment can produce invalid results and the script tests to ensure that you are running version 3.7.0.
Create a work folder on your computer where you can place the decompiler.py script from this post, and one or both of the decompilers listed above. The script will look for these decompilers in the same folder, or it will search your executable path (for py37dec) and your Python include path (for unpyc3) to find them.
You may want to edit some of the defaults in the decompiler.py script to suit your environment. The editable defaults are near the top of the script, prior to the DO NOT EDIT BELOW warning in the script.
GAME_ZIP_FOLDER should point to the location where the game's zipped scripts are installed. The default should find those scripts on a standard The Sims 4 installation on both Windows or Mac.
DEFAULT_PY_DEST_FOLDER allows you to set what folder will be created in your work folder to store newly decompiled scripts.
DEFAULT_DECOMPILER can be set to either 'unpyc3' or 'py37dec' to set which decompiler is used if no choice is made on the command line.
DEFAULT_MAX_THREADS may need to be reduced if you have a slow computer, particularly if it is only dual core. Too high a thread count won't hurt anything, but could bog down your system noticeably during the decompilation.
In most cases you can simply open a command prompt terminal window in your work folder and run the script using the command python -m decompiler. The game scripts will be extracted from your game into the destination folder, and decompiled using the default decompiler. The decompiled script is then recompiled and tested to verify it's accuracy. Finally, as each .pyc file is decompiled, it will be removed to leave only the resulting .py files. The first line of each decompiled script will indicate the results of the decompilation. It may indicate that:
The decompilation was perfect - meaning that the result .py file, when recompiled, produces the exact same compiled script as the original from the game.
The decompilation contains inaccuracies - meaning that the resulting .py file can be recompiled, but does not produce exactly the same results as the original. It may work correctly if used in your mod, or it may not matter much if you are only calling any of the methods and not rewriting them. The results are generally good, but only human inspection and experience can tell you how close they are to what the EA scripts are actually intending to do.
The decompiled file has syntax errors - meaning the resulting .py file cannot be recompiled and it is impossible to tell how accurate the results are. Much of the decompiled code is likely perfect or good, but something didn't get interpreted right by the decompilers as decompilation of Python scripts is not an exact science.
The decompilation process failed - meaning no results are available as the decompiler crashed trying to perform the decompilation.
The decompilation timed out - this only occurs with the py37dec decompiler and for a reasonable timeout (the default is 5 seconds) there should be only one file that fails due to taking too long.
Command Line Options
There are several command line options that can be specified to control the decompilation process. The -h option to the decompiler will list all available options. To specify these options, simply add them on after the above command. Most of these options are of limited use unless you are working on improving one of the decompilers themselves. However, I'll mention several of the options here that you may commonly use:
If you have both the unpyc3 and py37dec decompilers available, you can choose which to run as follows:
python -m decompiler -P # will use py37dec
python -m decompiler -U # will use unpyc3
Rather than obtaining the .pyc files from the game's zip files, you can use the -s option to specify a source folder. The destination folder can also be overriden with the -d option. If the same folder is used for each, the .pyc files will be removed after decompilation - however if separate folders are used, then the .pyc files will be left untouched. For example:
# Decompile all the files in the srcFolder of your work folder using py37dec, and
# put the results in pyFolder (will not remove the original .pyc files since source != destination):
python -m decompiler -P -s srcFolder -d pyFolder
The -r option can be used to specify an output filename for a CSV file containing the results of all decompiled files. The filename is optional and will default to creating a file named results.csv.
The -S option will create separate subfolders in the destination folder based on the results for the various .py files: perfect, good, syntax or decompile_failure. For example:
# Decompile everything in srcFolder using unpyc3 into the ts4_scripts_unpyc3 folder
# Create subfolders in the destination folder for perfect, good, syntax and decompile_failure results.
python -m decompiler -U -s srcFolder -d ts4_scripts_unpyc3 -S
$ python -m decompiler -h
usage: decompiler.py [-h] [-z ZIP_FOLDER] [-s SOURCE_FOLDER] [-d DEST_FOLDER]
[-S] [-p] [-t N] [-r [FILENAME]] [-L [N]]
[-c none|detail] [-U] [-P] [-T SEC]
-h, --help show this help message and exit
-z ZIP_FOLDER location of installed game zip files
-s SOURCE_FOLDER get compiled scripts from folder instead of zip files
-d DEST_FOLDER destination folder for decompilaed files
-S create subfolders of DEST_FOLDER by result
-p prefix output filenames with [RESULT]
-t N number of simultaneous decompile threads to use
-r [FILENAME] create CSV file containing results for decompiled files
-L [N] code objects with >N bytes will not be analyzed
-c none|detail prefix decompiled files with test results comment (default brief)
-U use unpyc3 for decompilation
-P use py37dec for decompilation
-T SEC py37dec only: override timeout in seconds (0=no limit, default 5)
That's about it, I guess, other than the usual "If you run into any issues or questions just yell here or you can always ask on Deaderpool's Discord where I'm known to hang out."
I put a lot of work into this, but the authors of the decompilers themselves, Andrew and Fogity, put in much much more work. Big BIG "Thank You's" are due to them for the time and effort they've expended to make this possible, from myself and I'm sure the entire TS4 scripting community.
Last edited by scumbumbo : 27th Feb 2019 at 4:34 AM.
Reason: Updated link to unpyc3
8 users say thanks for this.
[ Click here to view a longer list ]