The Sims 4 Code Changes for Modders - Feb 3rd Base Game Update

Sul Sul, Mod creators,

For the upcoming Base Game update on February 3rd, the team has modified The Sims 4 Python code used for setting and checking the family relations between Sims. Some classes have changed their behaviour to be better aligned with the new genealogy goals, some methods changed their names and signatures, and some tunable fields changed their types to be in-line with the new architecture. This is not a comprehensive list of all code changes, but the changes that are most likely to significantly impact mod functionality.

As this is a large change to many systems, we wanted to provide as much detail ahead of time to help you update your mods and reduce friction for any Simmers who use them. We hope this information is helpful and welcome your feedback via the comments below. As a reminder, you can view The Sims 4 Mod Policy here.

Logic Changes

Key points:

• SimInfo object still exposes the main interface in Python for setting the individual’s existing sim’s family relations to other sims (existing and purged). The interface was slightly changed, see below. 
• GenealogyTracker object inside the SimInfo still exposes the main interface in Python for checking the individual’s existing sim’s family relations to other sims (existing and purged). The interface was slightly changed, see below. 
• From the Royalty & Legacy Expansion Pack Base Game update, it will not be possible to set any family relations in Python other than direct parental relations and partner relations for existing SimInfo objects. Any other (indirect) types of family relations (siblings, grandparents, cousins, in-laws, step-relatives etc) will be automatically deduced and managed by the new Family Tree Service, and can’t be set directly anymore, neither by code nor with tuning (loots, household templates etc).
• Family Tree Service keeps a persistent, always growing family tree graph for all sims in the save. It keeps the data about dead sims even after they get purged from the save (unless they were manually deleted in CAS). It replaced the genealogy_cache entirely. Every node in the graph is either lived or living sim, every edge of the graph is either parent/child relation or a marriage.
• On every loading, the game synchronizes the state of SimInfos with the family tree graph in the save and family relbits between all related sims.

The order of synchronization is the following:

 

Any legacy family relations recorded in Genealogy Tracker, other than direct parental relations, will only be used for portability between Python and client. Only direct parental relations will be used as the source of truth for the Family Tree graph during the loading-time synchronization.

Any family relbits, that has no corresponding relation represented in the family tree graph during loading, will be archived / removed from the game.

To provide better backward compatibility with legacy saves, that could have been changed by cheats and mods, the game attempts to reconstruct “unknown” parents in the family tree graph for parentless siblings and for grandchildren without parents, from just their relbits, to keep relations with such incorrectly configured siblings and grandparents valid after Royalty & Legacy Expansion Pack Base Game update. This always prioritizes safety, so it won’t run in all cases. 

Python API Changes

The following code should perform the described operations keeping SimInfo, Family Tree graph and relbits in sync if applied properly. Any other ways to modify and get family relations will likely give unexpected results and will provide a higher chance for breaking saves. 

Setting a Parent

You can only set a parent to a new SimInfo, that has no family relations yet. You can do it twice to set both parents. 

WARNING: Setting parents above doesn’t perform any checks for the appropriate and relative age of the parent! This is on the caller to identify a pair of sims which are appropriate for child/parent relationships. Setting a parent which is younger than its child is not recommended and can cause various unexpected issues.

Getting/Setting Spouse 

WARNING: Setting spouse above doesn’t perform any checks for age and inappropriate romance restrictions! This is on the caller to identify a pair of sims which are appropriate for marriage.

Getting Relatives 

The following genealogy methods return id generators for the mentioned groups of sims related to sim_info. Please note that you need to have a valid sim_info to run these methods, so it won’t work if you only have an id of the sim which was already purged (see Navigating Family Tree below instead).

Navigating the Family Tree (Read-only!)

The Family Tree graph’s traverse() method allows the code to navigate the entire family tree starting from sim id passed as the first parameter. By default it traverses through all linked nodes including those corresponding to already purged sims (which has no sim info in this save).

Every traversed node is either lived or living sim, every edge of the graph is either parent/child relation or a marriage. The caller can adjust the maximum depth of traversal with optional max_depth parameter (see below), which by default is set to 10. The caller can also choose which edges to not traverse with the help of a function passed into an edge_filter_function parameter.

Access to family tree node’s data happens in the visitor function passed by the caller into the visitor_function parameter. See the FamilyTreeNode’s fields available for reading below. 

WARNING: Please note that visited_node and analyzed_edge below are references to the actual Family Tree graph data in memory. In any circumstances don’t change any data inside the referred objects! Otherwise this will break the sync between Family Tree graph and the rest of the save, leading to the save corruption.

The caller can also choose which graph traversal order to choose - DEPTH_FIRST or BREADTH_FIRST, using the traversal_mode parameter.

In the edge filtering function, the following bit flags will be found combined in the analyzed_edge.edge_data bitmask:

Tuning Related Changes

• It’s not allowed to use relationship loots in tunings to set any family relbits other than parents. 
• It’s not allowed to use Relationship Map in premade_sim_relationships tuning to set up family relations between premade sims. New Family Relations Fixup should be used instead if family relations need to be created between households. For in-household relations between premades the household template tuning is used as before.
• The following tunables (fields) were changed in the following tuning types:
• whims.whim_set.GeneTargetFactory - “relationship” is now RelationshipType instead of FamilyRelationshipIndex.
• filters.tunable.GenealogyFilterTerm - “family_relationship” is now RelationshipType instead of FamilyRelationshipIndex.
• aspirations.aspiration_tuning.AspirationFamilialTrigger - “target_family_relationships” is now RelationshipType instead of FamilyRelationshipIndex.