Modding:StatShifter

From Caves of Qud Wiki
Jump to navigation Jump to search
This page is about modding. See the modding overview for an abstract on modding.
This page is about modding. See the modding overview for an abstract on modding.
For best results, it's recommended to have read the following topics before this one:

Shifting Stats

Anything that inherits from IPart or Effect has utility methods for tracking stat shifts applied to targets. This can be very helpful for not needing to remember if you've shifted the stats already or not. The StatShifter API takes care of the book keeping of the "current shift" for you, giving convenient RemoveStatShifts, or the ability to SetStatShift again to overwrite a previous shift with a new value.


StatShifter API

All of these methods have been designed to be safe to call with empty/null objects, an amount of 0, or other cases that would result in no stat shifts applied at all. This avoids you needing to error check your values before passing them along.

StatShifter.SetStatShift(GameObject target, string stat, int amount, bool baseValue = false)

The main way of setting a stat shift on a target, from your part or effect you can call StatShifter.SetStatShift to set the stat shift value. You can call SetStatShift again with a different amount, and it will remove the previous and apply the new. The baseValue option is provided in case you want to stat shift the HitPoints stat as the "BaseValue" is your max instead of the normal "Value" used for everything else. This version takes a target allowing a Part on a piece of armor/worn inventory to target the wearer, instead of boosting stats of the armor object by default.

StatShifter.SetStatShift(string stat, int amount, bool baseValue = false)

This version of SetStatShift assumes that the shift will apply to the Owner of the StatShifter, which for a part or mutation would be ParentObject and for an effect Object, either way, the object that owns the part / effect.


StatShifter.RemoveStatShift(GameObject target, string stat)

Remove a single stat shift previously applied to the target.

StatShifter.RemoveStatShifts(GameObject target)

Remove all stat shifts applied to the target by this shifter.

StatShifter.RemoveStatShifts()

Remove all stat shifts applied by this shifter to all objects.

StatShifter "Descriptions"

The StatShifter also takes care of creating a "description" for the shift. It defaults to the GetDescription() of the Effect, and "" for a part. The "owner" of the shifter is compared with the "target" of the shift. When they differ it will look like "{Owner}'s {DefaultDisplayName}" - When they are the same, it will just be set to DefaultDisplayName ... This "DisplayName" for the shift is used with the Debug option that shows stat shifts as well as the showstatshifts wish. We may eventually add UI to let players see the source of these shifts on their stats.

You can set the StatShifter.DefaultDisplayName to something else on a part for specificity, I.E. the grassy yurtmat's +2 DV shift looks like

private void CheckCamouflage()
{
    GameObject User = ParentObject.pPhysics.Equipped;
    if (User == null) return;
    if (User.pPhysics.CurrentCell != null)
    {
        if (User.pPhysics.CurrentCell.HasObjectWithPart("PlantProperties"))
        {
            StatShifter.DefaultDisplayName = "camouflage";
            StatShifter.SetStatShift(User, "DV", Bonus);                        
        }
        else
        {
            StatShifter.RemoveStatShifts(User);
        }
    }
}
public override bool FireEvent(Event E)
{

    if (E.ID == "EnteredCell")
    {
        CheckCamouflage();
        return true;
    }

    if (E.ID == "Equipped")
    {
        GameObject GO = E.GetParameter<GameObject>("EquippingObject");
        GO.RegisterPartEvent(this, "EnteredCell");
        CheckCamouflage();
        return true;
    }

    if (E.ID == "Unequipped")
    {
        GameObject GO = E.GetParameter<GameObject>("UnequippingObject");
        StatShifter.RemoveStatShifts(GO);
        GO.UnregisterPartEvent(this, "EnteredCell");
        return true;
    }
    return base.FireEvent(E);
}

This results in showstatshifts wish telling us +2 from Grassy Yurtmat's camouflage.