Sims 4: Guides

Last updated: 09-02-2023

Note: This page contains severely outdated information, especially in regard to script modding and Python script decompilation. These guides may or not be updated in the future.

Modding Guides(Sims 4)

Here you find the guides for making your own mods to The Sims 4, basically animations and specially WickedWhims.

Decompile .ts4script files

These are simply a .zip format file containing a python script mod, renamed to .ts4script. So, to open it, just rename the file to ".zip" and extract.

You will find compiled ".pyo" files, in order to be modified you may need to decompile those. Finally you'd be able to edit them, than compile and archive again.

Requirements

1. Python v3.3.3
2. A text editor (Like Notepad++)
3. This python script (unpyc3.py).

Steps

Install Phyton. Create a working folder, and put a copy of the desired .pyo files in it. Open the script link, copy the whole text, paste it into your text editor and save it to filename "unpyc3.py" Put "unpyc3.py" in your folder. Create a .bat file in the same folder with the following content: @echo off for /r %%i in (*) do unpyc3.py "%%i" > %%i.py pause 6.(Optional) Create a second .bat in the same folder with the following: for /r . %%i in (*.pyo) do del "%%i" for /r . %%i in (*.pyo.py) do ren "%%i" "%%~ni" for /r . %%i in (*.pyo) do ren "%%i" "%%~ni.py" pause 7. Run the first .bat file. You'll see some errors, but that's okay. 8. Then run the second .bat file.

Now you got all your .py files into your folder, the second .bat deletes the .pyo files.

Mod modding guide

By Alec15
This is a short description of the method I use to decompile (and recompile) (script) mods. It is not meant to be a complete step-by-step guide, where you are guaranteed to end up with a working result. Every mod is different, and this is an outline of the process to get you on the right track and highlight the possible obstacles.

I wont be going into details about individual steps, since I assume, that if you are capable of modding a script, you are also capable of completing these steps on your own.

Requirements

• Python 3.3.5
• A text editor (Notepad++)
• unpyc3.py
• uncompyle6
• Easy Python Decompiler
• Comparison tool (WinMerge)
• The mod you want to mod

Initial process

This is done once to set everything up.

• Install python
• Install text editor
• Install comparison tool
• Install Easy Python Decompiler
• Put unpyc3.py and uncompyle6.py in your C:\Python33 folder.
• Associate the .ts4script file type with you unarchive utility (7-zip in my case)
• Make sure your windows shell (cmd og ps) uses UTF-8 (unpyc3 won't work on the some files if the stdout is not UTF-8)
• Create an uncompyle3.bat file to use for decompilation. Save it somewhere where you can find it again. It should contain the following:

@echo off
rem Batch file to decompile TS4 Python code with unpyc3
rem
rem Place in folder, you want to decompile
rem
echo Decompiling base folder PYO files. Press any key to start.
pause
for /r %%f in (*.pyo) do (
echo Decompiling %%f
python C:\Python33\unpyc3.py "%%f" > "%%~dpnf.py"
del "%%f"
)
echo Done

• Create an uncompyle6.bat file to use for decompilation. Save it somewhere where you can fin it again. It should contain the following:

@echo off
rem Batch file to decompile TS4 Python code with uncompyle6
rem
rem Place in folder, you want to decompile
rem
echo Decompiling base folder PYO files. Press any key to start.
pause
for /r %%f in (*.pyo) do (
echo Decompiling %%f
uncompyle6 "%%f" > "%%~dpnf.py"  
del "%%f"
)
echo Done

Decompilation process

• Download the mod you want to mod
• Make a copy of the folder (append the name with something like .org). Steps below this will be in this folder unless otherwise indicated.
• Unarchive the .ts4script file
• Make 2 copies of the new unarchive folder (append them with something like .unpy3 and .unpy6)
• In your .unpy3 folder place a copy of uncompyle3.bat and run it
• In your .unpy6 folder place a copy of uncompyle6.bat and run it
• Make a copy of the .unpy3 folder (change the suffix to something liked .merged)
• Go though the files in your .merged folder and delete all the files you do not intend to change.
• Use your comparison tool to compare (first) the .merged and (second) the .unpy6 folders.
• Use the comparison process below to merge changes into the .merged folder
• Do a recompilation test described below.
• Copy the whole .org folder (change the suffix to something like .working). Steps below this will be in this folder unless otherwise indicated.
• Delete the unarchived folder, the .unpy3 and the .unpy6 folders.
• Now you can start working on the files in the .merged folder. You will always have working copies of the original to fall back to.

Comparison process

This is not a step-by-step process. You have to go through all the files, which have differences and look through each difference and decide which is the better option.

In my experience:

• unpyc3 will always decompile a script
• uncompyle6 will decompile between 50-80% and does a better job
• Easy Python Decompiler will decompile between 10-50% and does a decent job

When having all 3 decompilations of a file, it will give you more confidence in which version is correct, since 2 of them will most likely agree.

Since unpyc3 always decompiles I use this as the base and add in any changes from the other decompilations. The problems I have encountered most often in uncpy3:

• Will swap some if statements for while statements
• Will insert while true loops
• Will swap some continue for pass
• Will sometimes not decrease indentation for some if statements
• Will sometimes state globals twice

These aren't the only issues, but if none of the other versions decompiled properly, you need to search through the file by hand and find these kind of problems and correct them.

Recompilation test

This is done to make sure that your decompilation process has worked and you can safely start changing the mod. If you skip this step and you get an exception later after adding your own changes, you wont know where it came from. You wont know if it is your changes, or bad decompilation. In my experience it's often bad decompilation.

• Follow the steps in the Recompilation process below, using the .org version and not the .working version.
• Place the resulting mod in you mods folder and start The Sims 4.
• Test the mod and confirm that all features (your are going to work with) are still working.
• Confirm that the mod doesn't crash and leaves no exception files.
• If your are experiencing problems, use the exceptions to go through the Comparison process again.
• Repeat this test until it works

I don't use Easy Python Decompiler unless I have to, since it's very cumbersome to use and often fails. It does however sometimes help to find problems with certain files.

• In your .org folder, make a new copy of the unarchived folder (append it with something like .easy)
• In the .easy folder, use Easy Python Decompiler on the files you are working on.
• Delete all other files in the .easy folder except the ones you have decompiled.
• Use your comparison tool to compared (first) the .merged and (second) the .easy folders.
• Use the comparison process to merge changes into the .merged folder

Recompilation process

Once you are done with your changes in the scripts, follow this process to recompile your newly modded mod.

• Open a Powershell in the .merged folder.
• Compile your scripts:

  python -O -m compileall .\

• Rename the files in the newly created "__pycache__" folder:

  dir | rename-item -NewName ($_.name -replace ".cpython-33", "")

• Open the .ts4script with you unarchiver and replace the files you have just compiled.

Converting existing adult WW animations

By Alec15

This is a tutorial for converting existing WW animations into child animations.

If you want to create animations from scratch, follow TURBODRIVERs tutorial on the original WW page. You can use the rigs provided here.

Below are two methods for converting animations. The first uses normal rigs, and the second uses IK rigs. The IK rig method is faster and gives good results, but can be a bit tricky. If you don't know what IK rigs are, I suggest using the first method.

This tutorial is meant as a starting point for conversions. It wont give you a finished conversion, you will have to fiddle with the adjustments until you like them

Requirements

• Basic knowledge of Blender
• Basic knowledge of the Dope Sheet, F-Curve Editor and Keyframes. See TURBODRIVER's Tutorial
• Blender
• Sims 4 Studio
• Edited animator's rigs (You can inquire them in the ATF WW Mods or Sims 4 General Discussion topics on the Forums.)

Method 1

Exporting Animations

Make a working folder in your Documents\Sims 4 Studio\Mods folder. Find the WW animation you want to convert and put a copy of it in your working folder. Make another copy of the animation in the working folder. I'll refer to this copy as the working copy. Open your working copy in S4S. Click the Warehouse tab. Click the first Clip or Clip Header in the list on the left. On the right find the field called Name or SourceFileName. One of these will hopefully indicate, if it is a male or female animation. Make a note of that. Click the Studio tab. Chose Adult Male or Adult Female depending on your note. Click Export and save the file. Go back to the Warehouse and delete both the Clip and Clip Header (with the same Name field) and Save. Go back to the Main Menu in S4S and open the same file again. Repeat this process for every Clip and Clip Header pair in the working copy.

You should now have a .blend file for each actor in each animation. Make working copies of each, so that you can always revert to the original, if you make a mistake later on.

Importing rigs into Blender

Each complete WW animation has a .blend file for each actor. If the original mod creator has been orderly with the naming you should easily, be able to recognise which files make up a complete animation.

Open one of your working copies .blend file for the animation you want to work on. Append (File->Append) the Scene for the next actor for that animation. Save! Repeat for every additional actor in the complete animation. You should now have a Scene in Blender for each actor. Example I'm using TURBODRIVERs builtin animations from WW here The complete cowgirl animation consists of: TURBODRIVER_cowgirl_1_male.blend TURBODRIVER_cowgirl_1_female.blend Open TURBODRIVER_cowgirl_1_male.blend Append TURBODRIVER_cowgirl_1_female.blend\Scene\Scene If you mistakenly exported a rig with the wrong gender, don't worry you can fix this now. You need to import the rigs for all the actors you want in your final animation. Append the Scene for each rig. If you are going to use an adult male, append the Edited Male Rig. If you are going to use an adult female, append the Edited Female Rig. If you are going to use an child male, append the Edited Child Male Rig. If you are going to use an child female, append the Edited Child Female Rig.

Exchanging Rigs and Animations in Blender

Find the Scene in the Outliner of one of the actors (not animations) you have appended. Expand the rig. Make sure, that all elements (rig and meshes) are visible and selectable. Switch to Object Mode and Select All in 3D View. Copy (ctrl-C). Select the top Scene in the Outliner. Switch to Object Mode and paste (ctrl-v). Repeat for each actor you need in your final animation.

You should now have all the actors you need for your final animation in the top Scene. Click the original animated actor rig in the top Scene of the Outliner. Change the Context Editor (it's the dropdown to the left of the Key menu) in the Dope Sheet to Action Editor. Note the Action (to the left of the Context Editor). Click the actor rig of the imported actor, whom you want to have this animation in the Outliner. Click Browse in the Action (up/down arrows) and select the animation. Right click the original actor in the Outliner and select Delete Hierarchy. Note! you might just want to hide the actor or move it to another layer, if the animation is on an object, like a bed, so that you can adjust the hight of your actors correctly. Go to the next Scene in the Outliner to repeat for every actor in the final animation. Delete all Scenes in the Outliner except the top one. Save!

You should now have your actors in one scene with the original animations applied.

Manipulating Animations

Check the animation in the Dope Sheet to see, when the final frame is and make sure, that your End frame in the Timeline is the same. Start moving your actors around. I recommend staring from the top most bone (ROOT) and working your way down. Except for the ROOT bone, I recommend only trying to change the rotation and not the position. Work as much as you can on the bones, that have only the initial keyframe. For bones with only the initial keyframe: Make sure, you are on frame 1 and adjust the bone in the 3D View and key it. For bones with animations: Create another window under the Dope Sheet and change it to Graph Editor. Select the bone or pair (R/L) of bones you are working on. Expand the Channels for the bones int the Graph Editor. Deselect the X, Y and Z Location and deselect all but one Rotation. Select all points of the curve. Move the Curve up/down (g, y) to see how this rotates your bone press ESC. Find the high/low points of the curve and see if it needs to go up or down at each point. If it needs to go in the same direction at each point, Move the Curve. If it needs to go in opposite direction Scale (s, y) the Curve and then Move it. Repeat from the top bone and work your way down until your are happy with your animation. Save!

Turning you animation into a WW animation

Follow TURBODRIVERs tutorial on how to put together a WW animation. If you have used Method 2, don't worry about the additional bones and constraints. S4S will recognise your rig and animation correctly. Once you get to the WW XML file open the original WW animation in S4S and copy the values from there (unless you have changed something from how the original animation worked), except your name, animation name and text string references. Once you have put together your own WW animation package you need to open the original WW animation again in S4S. Go to the Warehouse tab and select the first Clip. On the right find the field named Events and click on Edit items... A new window will open and you will see one or more Sound items in the list. For each item note the SoundName and Timecode on the left. Also not which Clip (actor) it belongs to. Repeat for all Clips. Open your WW animation in S4S and find the corresponding Clips in the Warehouse, that you have just noted. For each Clip find the Events field and Edit Items... Replace the values SoundName and Timecode of the existing Sound, with the ones you have noted. Add more sounds if needed by selecting SoundEvent in the dropdown on the right and click Add. Repeat for each Clip. Click Save. You now have your own WW animation. Put it in your Mods folder and test it.

Method 2

Exporting Animations

Same as Method 1

Importing rigs into Blender

Follow the step "Importing rigs into Blender" from Method 1, but use the following rigs instead of the ones listed in the requirement: Edited Male IK Edited Female IK Edited Child Male IK Rig Edited Child Female IK Rig

Exchanging Rigs and Animations in Blender

Same as Method 1

Manipulating Animations

Once you have done all the rough changes using the procedure above, you can adjust the details of the rig using IK. You might want to turn off the eye controllers, if the eyes look all weird. You can do this by digging down in the rig in the outliner to the b__L/R_Eye__, b__L/R_LoLid__ and b__L/R_UpLid__ and disable (eye button in the Bone Constraints) the Copy Rotation. The IK rigs have IK chains in the spine, neck, head, jaw, arms and legs. From the clavicle to the hand and thigh to foot. Adjust the general animation: Go the frame 1. Place the bone where you want it to be in that frame. Select all the bones in that chain. Insert Keyframe for VisualLocRot (i). (See example bellow)" While all bones in the chain ar still selected go to the Graph Editor: Disable (eye icon) all but the top most graph. Select all keyframes except the first. Zoom in, so that you can see the full length (plus a bit more) of the animation and very close to the height of the first couple of ##frames. Place the (Graph Editor) curser at the first frame, making sure, that it has the exact same height (y direction). Move the remaining frames (g, y), so that the ending height of the graph is the same as the beginning, using the curser as guide. Repeat for all graphs. For the location graphs, there should only be the first keyframe and you can skip this procedure for those Play the animation (alt-a), it should look much better now. Example (using the left hand): Place the left hand where you want it to be. Select Left Hand, Left Forearm, Left UpperArm and Left Clavicle. Insert Visual LocRot There might still be some points at the extremes of a movement, that don't look right. Adjust extreme points: Find the frame with the extreme, that needs to be adjusted. Place the bone where you want it to be in that frame. Select all the bones in the chain Insert KeyFrame for VisualRotation (i) While all bones in the chain are still selected go to the Graph Editor: Disable (eye icon) all but the top most rotation graph. Select all keyframes except the first and the one you ar adjusting. If there are only those two keyframes in the graph. Select the one you are on and delete it. Move on to the next rotation graph. Zoom in, so that you can see the full length (plus a bit more) of the animation and very close to the height of the first couple of frames. Place the (Graph Editor) curser at the first frame, making sure, that it has the exact same height (y direction). Scale the remaining frames (s, y), so that the current frame fits nicely into the graph. Move the remaining frames, so that the ending height of the graph is the same as the beginning, using the curser as guide. You may need to repeat scale/move a couple of time to get it right. Repeat for all rotation graphs. If the keyframe you are adjusting is the last one in a graph. Do not scale the graph! Select your current keyframe and move it back in line, so that it lines up with the first one. Play your animation, the extreme points should now have been reduced. You can repeat this for other extreme points in the animation, just remember, which frames you have already adjusted. Always deselect these when scaling or moving the graphs and always make sure, that the graph ends up aligning to all the keyframes you have adjusted. If you need to do this for several extreme points, you might need to adjust parts of the graph individually. Example (you have keyed two extremes and the first frame): Select the graph except the points you have keyed. Adjust (scale and move) the graph so that it fits between the two extremes Select the graph between the first frame and the first extreme. Adjust this, so it fits between the two frames. Select the graph after the last extreme. Adjust this, so it fits between the extreme and places the last frame on the same level as the very first. Example (you have keyed several similar extremes and the first frame): Place the cursor on the first frame or at 0,0. The similar extremes will mostly fall on the same side of the horizontal line. Select the graph on this side of the horizontal, except for the frame you have keyed. Adjust this side of the graph until it fits all you keyed frames. Save!

Turning you animation into a WW animation

Same as Method 1