Mod #1 - CAS Trait

Finally. Finally. Let’s make our first mod.

We’re going to make a simple trait mod. The trait won’t actually do anything for now other than appear in CAS, but we’ll give it a custom name, description, and icon to show how resource linking works.

Tip

The point of this tutorial isn’t to learn about traits, it is about learning to link different resource types together to form a working mod.

We’ll talk about figuring out how things work in the next tutorial.

Getting Started

While it is possible to write tuning XML from scratch, we’ll be using tdesc.lot51.cc to get started since it is much easier when learning and will handle SimData syncing for us.

Firsts, let’s set up a new tdesc editor.

1. Head to tdesc.lot51.cc.
2. If the sidebar on the left isn’t open, click the icon in the top left of the page to toggle it.
3. Search trait, then select Traitsfolder, then select Trait.
4. This opens a new tuning editor tab.

Lot51 Tuning Builder

The tuning builder can seem a bit overwhelming at first, so let’s take a quick tour.

At the top center of the editor, you can set your creator name, custom tuning name, and an optional DLC requirement. The DLC requirement is stored in the tuning resource key’s Group field.

Your creator name and tuning name are used to generate a unique tuning ID automatically, which is stored in the XML’s root node as the s attribute. We’ll look more at this later in case we ever need to do it manually.

Below this is a UI for editing every possible field the current tuning supports, and on the right will be the final tuning XML. Explore the different buttons and icons. You can toggle nodes, expand list and object nodes, add values to lists, select references, and more.

If we look at the first node for a trait, we see animation_overlays has a type L for list. Expanding it, we see the list contains U nodes (objects), and each object has a single T field _overlay_animation (T is used for single values of any type).

Clicking on any node will show the node’s description on the right, below the XML view.

The final XML will appear on the right.

A large part of learning how to mod is exploring tuning descriptions, reading about how things work, and just trying stuff out.

S4E also has a description browser that works offline (but doesn’t generate XML), as well as some other cool features for exploring game files that we’ll look at in the next tutorial. For now, let’s get back on track.

Lot51 Tabs

Lot51 uses tabs at the top of the page when opening tuning. If your tuning is full of test XML from the previous step, just close this tab and open a new one.

Making the Tuning

If you haven’t already, make sure to set your Creator Name and Tuning Name in the top center.

Resource References

When we need to use resources like images and strings, we’ll reference game resources to test with, then replace these with our own resources in a later step.

If you use game references if your final mod, be mindful of what DLC they reference. Avoid adding DLC dependencies your mod doesn’t already have.

Now let’s add the minimum required fields to get our trait to show up in CAS.

1. display_name - The name of the trait. Use 0x2D8777C7 for Awesome!
2. trait_description - Tooltip description. Use 0x89F40002 for I trust in my awesomeness.
3. ages - List of ages that can have the trait. Required for CAS.
4. species - Species that can have this trait. Required for CAS. Add HUMAN.
5. occults - Occults that can have the trait. Required for CAS. Add HUMAN.
6. icon - The icon. Use 2f7d0004:00000000:cfc547bc4742a87a for trait_CoolGuy.png.
7. tags - There are hundreds of tags for different things. We need to one to define the CAS trait category. Add one of the following:
   • TraitGroup_Emotional, TraitGroup_Hobbies, TraitGroup_Lifestyle, or TraitGroup_Social
   • TraitGroup_Emotional is first, so it’s easiest to test with

Here’s a look at the final XML:

<?xml version="1.0" encoding="utf-8"?>
<I c="Trait" i="trait" m="traits.traits" n="ZMilla:AwesomeTrait" s="1131508133">
  <L n="ages">
      <E>YOUNGADULT</E>
      <E>ADULT</E>
      <E>ELDER</E>
  </L>
  <T n="display_name">0x2D8777C7<!--Awesome!--></T>
  <T n="icon" p="InGame\UI\Icons\CAS\Traits\trait_CoolGuy.png">2f7d0004:00000000:cfc547bc4742a87a</T>
  <L n="occults">
      <E>HUMAN</E>
  </L>
  <L n="species">
      <E>HUMAN</E>
  </L>
  <L n="tags">
      <E>TraitGroup_Emotional</E>
  </L>
  <T n="trait_description">0x89F40002<!--I trust in my awesomeness.--></T>
</I>

Tuning Name

The name of your tuning is stored as in the root node’s n attribute. This can be set in Lot51 and should be in the format CreatorCreator:TuningName which is ZMilla:AwesomeTrait for me. The tuning’s ID is stored as an integer in the s attribute. This should be either the FNV32 or FNV64 of the tuning name.

32bit vs 64bit

FNV32 returns a 32 bit int, while FNV64 returns a 64 bit long. Either can be used, but 64 bit reduced the chance of a conflict with other mods. However, it isn’t supported by all tuning types.

Lot51 handles this automatically, and also marks which tuning types are 32 bit only. S4E currently does not. You only need to do this manually if you make a tuning from scratch inside S4E.

Making the Mod

Finally, to actually create the mod:

1. In lot51.tdesc.cc, click Download Tuning AND Download SimData
2. (Optional) In Sims 4 Editor, you can create a new empty environment for easier testing.
3. In Sims 4 Editor, open the package editor, enable editing, then create a new package in your Mods folder
4. Click Import and import both files from step 1, then save

That’s it! A working mod! Our package contains tuning XML that defines a new trait, points to existing game resources, and is backed by SimData.

And behold… our final masterpiece in game.

Troubleshooting

If you have any issues up to this point, here are some things to try.

• Your mod must be in the mods folder
• In Sims 4, select Game Options > Other > View Custom Content. Make sure your mod appears in the custom content list
• Make sure you are looking in the right CAS trait category
• Make sure your XML matches the example above
• SimData fields must match their corresponding XML fields

Modding the Mod

Having a working mod is awesome, and you should feel proud if you’ve made it this far. Congratulations!

There’s a small problem though… this mod just points to existing game data. That’s boring. Let’s fix it!

String Tables

Let’s customize the trait’s name and description using string tables.

1. In the S4E package editor, click Create and change the type to String Table.
2. (Optional) When making a mod you plan to release, use the All Languages option to create linked tables for all languages.
3. Select the English (or your native language) table, and click the + button to create new entires. New entries are added to all linked tables.
4. Create two entries, one for the trait name, one for the description.
5. In both the XML and SimData resources, update the display_name and trait_description fields with the keys you just created. You can copy keys from the string table editor.
   • <T n="display_name">0xADFD2D36</T>
   • <T n="trait_description">0x02AEC635</T>
6. You can delete the comments related to “Awesome” as they were documentation for the original references.

Language Sync

When creating a new entry using S4E, an entry will automatically be created for every language.

Because traits are sorted alphabetically, your trait will likely have moved in the list.

Test

Test, test, test some more. While it may be tempting to jump straight to the next step, it is good to test often. The more change you make between tests, the harder it is to know what change caused something to break.

DDS Images

Sims 4 supports several image types. The most common type is DDS, which in turn has many subtypes. This image format was made for the DirectX, but is supported by software like GIMP, Photoshop, S4E, and S4S. Trait thumbnails use DDS images with the DXT5/DST5 subtype. You don’t need anything else about images than this for the tuning tutorial, but there is a work in progress article about image types used by Sims 4.

We’ll export the image we’ve already been referencing, edit it, then reimport it with a new resource key.

Export and Edit

1. In the tuning XML, the icon field is a resource key. Copy the instance, which is cfc547bc4742a87a
2. From the S4E homepage, open the Global Resource Browser, and search cfc547bc4742a87a.
3. Right click the image and export to a DDS.
4. Edit the image with an external program like GIMP or photoshop.

Since I’m a programmer and not an artist, I’ll hit it with the classic hue shift in GIMP and call it a day.

More Icons

To find more icons, you can search dds in the global resource browser, but this returns all dds images and not just icons. Warning, this is kinda fun and may cause you to get extremely sidetracked. Stay vigilant!

Generating an Instance

In the future, S4E will allow importing resources with any file name, but for the time being we need to add our desired resource key to the file name. This gives us an excuse to see how ID generation works.

Lot51 handled our tuning ID, S4E handled our string table IDs, now let’s generate our own ID for the image.

1. On the S4E homepage, select Utility > Hash Utility.
2. Input something completely unique. Suggestion: CreatorName:PackageName:FileName
3. Copy the FNV64 hex value.

I’ll use ZMilla:AwesomeTrait:CoolGuy.png for an instance of 0xE7D367714A02CDB2, but use your own info for this step.

Recall that resource keys use the format Type:Group:Instance unless otherwise stated. DDS images have a type of 0x00B2D882 and the group is unused, so my final resource key is 0x00B2D882:0x00000000:0xE7D367714A02CDB2

However, file names don’t support :, so we need to replace those with ! as the next best thing. If using Sims 4 Studio, the file name needs to be the resource key only. When using Sims 4 Editor, the resource key can be anywhere in the file name, so my final file name will be CoolGuy-0x00B2D882!0x00000000!0xE7D367714A02CDB2.dds.

Reimporting and Referencing

Finally, let’s import our edited, correctly named dds file.

1. Click Import and select your edited DDS file.
2. Update the icon field in the tuning XML and SimData with the new DDS resource key.
3. Only the instance changed, so just editing the last part of the key is enough.
4. The “path” node is purely documentation. You can change the value to store the image name, or remove it.

Example XML: <T n="icon">0x2f7d0004:0x00000000:0xE7FC3D714A258B10</T>

Finally, a fully customized tuning mod!

Image Type

You may have noticed that DDS images use the type 0x00B2D882, but Lot51 generated an icon resource key with type 0x2f7d0004 which is a UI PNG Image. Which is correct?

From my testing, the icon’s type is completely ignored, and even 0x00000000 works. My guess is that the icon was originally a PNG, was automatically converted to a DDS for optimization, and the game just loads all icon tuning references as DDS without checking the type.

The Takeaway

I want to hammer in the fact that what we just did literally, making a trait, isn’t nearly as what we did conceptually. We added custom resources to a package, then made those resources reference each other using string keys and resource keys. Other resource types may also be referenced by string, tuning ID, or enum, but the concept remains the same.

That is the heart of Sims 4 modding. Even when making custom items or clothing, things like models, textures, and animations are just resources that can be referenced via resource key, and other resources like CASPart or CatalogObject do exactly that to define new objects!

It’s turtles resources, keys, and references all the way down.

The Magic

I glossed over one major thing. With so many fields to choose from, how did I know which ones were required for a CAS trait? How do we figure out how stuff works in general?

The general answer is to find examples of existing files that do something similar to what you want as a starting point, then experiment. This will be the entire focus of the next tutorial.

The specific answer is that I found files for other CAS traits, looked for fields shared by many traits, then removed fields one by one until I had only required fields remaining.