The Sims 4 Modern Python Modding: Project Template

This is the tutorial for the project template I made which lays out the new project groundwork for you and comes with scripting to automate much of the modding process.

I’m using Windows, but this ~ should ~ be cross-platform compatible. Please let me know if it’s not either by leaving a comment on here or by filing an issue at the issue tracker here.

Major Updates have been made since I wrote this

Since I’ve written this article, many major updates have taken place and it will be continued to be updated into the future but I felt enough updates have happened that it warranted re-writing this tutorial.

Please check back from time to time at the project link below and download the latest updates. You can always update an existing project as well.

Step 1: Download the Project Template

The project is available on Github, it gets updated from time-to-time with new capabilities and fixes and it’s open source so it’s the perfect place to have it. Anyone is welcome to contribute or file an issue and I encourage people to do both. Download it Here.

Click the green Code button and then Download ZIP button. This downloads it to your computer. Next lets extract it, I use 7-zip because its convenient and super fast but you can use whatever you want. There’s a million zip extractor programs, even Android has more than a dozen lol.

Now this is the actual project template you’ll see

But we’re not quite done yet, first, lets move it to a folder where we store all of our modding projects at. You don’t have to, but it keeps things organized and the template is designed for something like that.

Step 2: Copy it somewhere and give it a name

I personally store all of my projects in Documents\Sims 4 Projects. Lets copy it there.

Now lets rename it, this represents a single project so lets name it to the project we’re working on. I’m going to call it Hello World because to keep things super simple I’m going to copy the files we worked on in part 2 for this example.

Step 3: Rename settings.py.orig

Now lets rename settings.py.orig to settings.py. I did this because you could have several people working on this project and everyone of them will have a unique settings file so best to kept their own personal settings file out of the project and just have a generic one instead.

Step 4: Open the project

Lets open up the project, there’s a million editors out there people use and to be honest I use most of them. Atom, Notepad++, Sublime, Visual Studio, Visual Studio Code , Notepad, etc… the list goes on. For this example though I’m going to use PyCharm but you definitely don’t have to use exactly what I’m using.

This is what it will open up to

Step 5: Set to use Python 3.7

As I stated in part 1 and part 2 of my tutorial, we need Python 3.7, no more, and no less. It has to be exactly that version and the latest 3.7 out at the time of this writing is 3.7.9 so we need to tell the editor to use that python version for this project. You have to have already downloaded and installed it and I covered that in part 1.

Open File > Settings

And change the editor to use the Python 3.7 version you downloaded in part 1.

Step 8: Tweak a few settings

The last step is to adapt the settings to fit your needs. I’m only going to go over the top-half of the settings file which is what you’ll often change, the rest of it can be changed but often won’t need to be. Lets go over this really quick.

Open settings.py

This is what you will see

• The creator_name is simply the username or real name you want prefixed before your mod name.
• The mods_folder is the path to your Sims 4 Mods folder. The default works fine for most Windows users. If you’re on a different platform like OSX or your Documents folder is located elsewhere on Windows you need to change this.

I’m going to go ahead and change it because my Documents folder is located on a different Hard Drive. Windows is weird, even though it’s the same Document folder you still have to change it if it’s been moved otherwise it won’t work and there won’t be any errors.

# Sims 4 mod folder location
mods_folder = "D:\\juneh\\Documents\\Electronic Arts\\The Sims 4\\Mods"

• The projects_folder is where all of your Sims 4 projects are, including the Python library and Tuning files. This is how I stay organized and the downside to using templates and boilerplate projects is it’s not easy to set it up to work a different way if you don’t want that workflow and setup.

In our case it’s where we dropped our Hello World project in. I placed mine inside of Documents\Sims 4 Projects so it already matches what’s inside of the settings.py file. However, remember, my Documents folder has been moved to a different drive so I still have to update it anyways.

# Location of folder to contain your projects
projects_folder = "D:\\juneh\\Documents\\Sims 4 Projects"

• game_folder refers to your Sims 4 Installation. I think most people will have it in the default path and won’t need to change this but if it is installed elsewhere you’d need to point this to your Sims 4 Game folder.

This is what I have so far, yours may be different and probably not exactly like mine.

Step 9: Decompile the python library if you haven’t already done so

Skip this step if you already have the Python files decompiled otherwise this will wipe them out and re-decompile them which isn’t bad if you don’t mind waiting 1 or more hours to re-decompile them.

If you’re using PyCharm, right-click and run decompile.py. This will begin a long process that took my machine an hour but yours may take longer or shorter.

I worked very hard to make the decompilation screen as compact, useful, and pretty as I could get it. Many files won’t decompile successfully and that’s normal which I explained in part 1.

Here we can see for base.zip 389 files decompiled successfully, 31 failed, and the process took 14 minutes. 92.62% of all 420 files decompiled correctly in base.zip. There are currently 4 modules that need decompiling. base.zip, core.zip, simulation.zip, and generated.zip. In all it will take a very long time.

Step 10: Add the decompiled files to your project

I already covered this in part 1 so I don’t want to repeat it here. After doing that you will have something that looks like this.

Step 11: Begin writing your mod scripts

You’ll find a starter file named main.py already there for you, you can change it and adjust where needed.

import sims4.commands
import services


@sims4.commands.Command('hellow', command_type=sims4.commands.CommandType.Live)
def _hellow(_connection=None):
    output = sims4.commands.CheatOutput(_connection)
    output('This is my first script mod')

Step 12: Enter Dev Mode

Only on Windows so far, Mac and Linux are planned in the future

Dev Mode is a special mode that allows you to connect your project files you see in the editor directly into the running game. This means as you make changes you can reload them while the game is still running from within the game.

Run devmode.py and you may be greeted by this unexpected and very confusing error message.

This is PyCharm being very annoying, it expects all the Python files across the entire project and external libraries like The Sims 4 to be completely perfect which isn’t this case so it throws a fit and displays a very vague and confusing message. More importantly none of these files have anything to do with devmode.py which is even more annoying.

Thankfully it seems PyCharm has gotten a slew of complaints about this so they’ve implemented an option to make this go away.

After you try to run the script for the first time and it displays this error message you’ll then find an option to edit the script. Click Edit.

Then uncheck Add content roots to PYTHONPATH and Add source roots to PYTHONPATH .

Click OK and now when you run devmode.py it should work now.

If you have a look inside your mods folder, something interesting has happened. You’ll find a folder with your creator name and the Mod Name

Opening it reveals this

This is called a managed folder, it’s recommended to not interact with this folder and to instead let the project template interact with it. When your in Dev Mode, Scripts is the link between the project folder and the running game. devmode-cmd.ts4script is the mod that allows you reload project files live via an in-game cheat code, devmode.reload

Step 13: Playtest it with Dev Mode

Open the game and enter hellow . You should see something like this.

Now, while the game is running, lets change it. Remove the first and replace it with second like below in main.py .

def _hellow(_connection=None):
    output = sims4.commands.CheatOutput(_connection)
    output("This is my second script mod")

Now re-enter the game and type in devmode.reload main . This tells the game to reload just main.py . You can just use devmode.reload if you want to reload the entire project or devmode.reload path.to.folder to reload a specific folder. It’s pretty flexible.

Now lets retry that same command

Awesome! Lets now leave Dev Mode and package up your mod. Go ahead and close the game now.

Step 14: Compile it

Run compile.py this exits Dev Mode if you’re in it and re-creates the folder to be more of a normal folder that contains a ts4script file that players would download. It also places this file in the build folder within your project.

Note that this is the first time we’re running this script as well so it’d likely result in an error so you’d have to go through the same process described above.

It pretty much describes what it did and that it exited Dev Mode. Looking inside the mods folder this is what you will see now.

Very different than before. Scripts is gone along with the Dev Mode mod. In it’s place is your newly packaged mod. You’ll also see this in your project folder under build.

Lets look inside it, I’m using 7-zip but you can use any zip extractor. Most zip extractors, though, may require you to rename it from .ts4script to .zip but thankfully 7-zip doesn’t require that.

So it appears to have just copied your src folder and compiled any Python files it found next to the source code.

This is important, the reason it does this is because when the game loads it can either compile your mod for you on start or you compile it beforehand. While the latter sounds better, the former is actually better.

If the games python version changes in the future, then your mod will survive, however if you didn’t include the source code then your mod will likely not load on a major game update like that. This keeps your mod flexible.

What about package and tuning files?

I didn’t cover package and tuning files because they’re not related to scripting however your not left in the dust. Many mods have a combination of package files, custom tuning files, and scripting.

Inside your project folder is an assets folder. This is where you place all of your package file assets and package files itself.

Once when you run devmode.py or every time you run compile.py it will sync your packages to the Mods Folder. You can manually sync anytime though by running sync_packages.py

It only searches the first-level of assets for package files, this allows you to have package files in sub-directories and they won’t be synced. So if your having an issue where no package files are being synced this would be the first thing to look for.

Often I will have temporary package files or backups or originals, etc… that’s not part of my main project so I place them in sub-folders so they aren’t synced.

Planned features in the future is to have xml tuning files to also be a part of Dev Mode.

Any help with Tuning File Names?

By default it looks for Tuning files in Sims 4 Projects\__util\Tuning but this can be adjusted in settings. If you use Sims 4 Studio and Extract Tuning Files using Sub Folders then you’ll get many folders of files that have names like this.

03B33DDF!00000000!0D94E80BE40B3604.sims.loan_tuning.Tuning.xml

what this does is change the above to

sims_loan_tuning.xml

It’s not a big thing, but it makes it prettier. I’m well aware there are other programs and tools out there that do similar things but many people use Sims 4 Studio so I just wanted an easy in-house solution to fix the naming.

Step 15: You’re done

The mod and package files will be placed in a build folder as well

Now, if you’ve been following this example you won’t have a package file there. I’m just trying to demonstrate the asset capabilities of the project template.

Step 16: Final Packaged Test

It’s advised to do a final test of the mod in packaged form just to make sure it works the way you want it to. Run compile.py and head on over to the game to test it out.

And done! It works great and you’re ready to publish the mod.

This is the end of the tutorial

I hope you enjoyed and learned from it, I had a lot of fun making this boilerplate project and spent many hours building it so enjoy!

Be sure to check out the debugging update.

I wrote a second tutorial that discusses an exciting new feature, debugging, and made an update to the boilerplate project to automate most of it. Link Here.