Upgrade Mod Guide for Permanent TF

In r54, permanent transformation was added. This guide documents mod changes needed for mods to understand permanent TF.

While I already updated all species in the mod database to support it, this guide will illustrate steps you can apply if you have any non-uploaded species mods -- or if you are a mod author curious as to how this was performed.

By making these changes, your mod will understand when the player is in various permanent TF states and react accordingly, as well as for other game content to understand when your own custom transformations is in permanent TF.

Updating custom monsters

• Simple mobs (ex: created via SCLab) must now have defeat text, but most (all?) already do.  
  • (Mobs previously didn't show the defeat text ever because it was preempted by the TF scene. It will now show the defeat text if the player is already that form or cannot TF because they're permanently locked to another species.  It looks like simple mobs already had defeat text specified as this was already a field in SCLab.)
• Advanced mobs:  Recommended to check shouldAttemptTransformation() on the species prior to causing a transformation.
  • (I did not yet do this for existing advanced mobs)

Updating custom species (transformations)

I updated all existing mod species in the database on 3/12/2025, so these steps have already been performed on all species mods in the database.

• Update getIsFullyTransformed():
  • Species should make sure they defined a getIsFullyTransformed as that is now relied on by ShouldAttemptTransformation.  (Not defining one might result in tf sequences that don't tf the player)
  • getIsFullyTransformed now also should check feminization/gender TF.  Some species (ex: mermaid) will always feminize player.  But most species will only force feminize the player if the relevant game option was chosen during character creation.  The new checkFullyFeminizedIfShould() function can be used to simplify this check.        
  • If there are other custom reasons your transformation should not be called (ex: multi-phase TF with requirements not yet met), there are functions for CheckSpeciesTransformationAllowed + ShouldAttemptTransformation.  I have not exposed those to be overridden currently, but if you need them, let me know.
• Update causeTF():
  • At the start, call CheckSpeciesTransformationAllowed() and return if false, to make sure that the player's overall species hasn't been restricted to something else
  • Your TF can hook into the Always Feminize game option by checking the [[Species#[get only] bool feminize|feminize]] variable and feminizing player if it is set. (disregard if your TF is an always feminizing TF, since it should always feminize)  [ex: see pig tf's causeTF()/getIsFullyTransformed() for an optional gender TF based on feminize variable]
• Update each tfBodyPart function:
  • check CheckBodyPartTransformationAllowed to ensure it is allowed to transform that body part, before transforming it.
  • after successful transformation, call OnTransformed();  This will allow the game to detect the transformation and potentially register your species as the permanent overall species the player is locked to (if in that game mode)
  • See Giraffe TF for example