Curing Stuff with the EE Fixpack (for a given value of "stuff")

[CamDawg]

A brief overview

There are any number of items and spell that reverse adverse conditions: antidote potions to cure poison, restoration to reverse level drain, free action to counter hold, etc. These work on the major effects (and their portrait icons) but they're not always consistent on cleaning up ancillary effects such as visuals or expiration sounds. A well-known example of this is Horror, which (in addition to a fear effect) plays a spinning animation over the creatures panicking. Curing the fear removes the fear, but doesn't clear the spinny animation. The EEs addressed this in an ad hoc fashion by adding effects (opcode 321) to outright remove all effects of the Horror spell when fear is cured. While this does effectively end the animation, it's a bit cumbersome and not very extensible.

Using 321s against lingering effects works, but decentralizing them to every item that reverses an effect is a recipe for future bugs--any mod that adds something that cures fear would have to determine which items and spells need 321s, or update every item that cures fear to account for their new fear-inducing item. Imagine iterating this through several mods, and you can see there's phenomenal potential to get things (lots of things) wrong.

(As an aside, if you're looking at ways to properly prevent or provide immunity to effects, there's already a tutorial for that.)

Enter the EE Fixpack

EEFP introduces a series of subspells, each one dedicated to reversing a specific effect:

• #cureber.spl - Berserk
• #curebld.spl - Blind
• #curecon.spl - Confusion
• #curedef.spl - Deafness
• #curedis.spl - Disease
• #curedrk.spl - Drunkenness
• #curefer.spl - Fear
• #curefbm.spl - Feeblemind
• #curehol.spl - Hold
• #cureinv.spl - Invisibility
• #cureldr.spl - Level Drain
• #curendt.spl - Non-Detection
• #curepse.spl - Pause Caster
• #curepsn.spl - Poison
• #curesil.spl - Silence
• #cureslp.spl - Sleep
• #curestn.spl - Stun

The list was built to be thorough so not everything is really useful--e.g. modders shouldn't be curing Caster Pause, and nearly every level drain is permanent without time-limited effects--but they're made available for completeness. Every one of these cure spells will, at a minimum, cure the main effect, remove its normally associated icons via op 240, and add 321s as relevant. For example, the fear cure (#curefer) cures fear via opcode 161, removes the panic (36) portrait icon, and then has a series of 321s to remove all effects from some spells, e.g. Horror is removed via 321 to get rid of the spinny head animation.

The idea is that something that cures fear will apply #curefer via opcode 146 instead of directly curing it with opcode 161. This gives a centralized resource for addressing fear that any mod can tap into.

Modders need to be aware of this on both ends. A new item/spell that cures fear should cast #curefer instead of using opcode 161. An item/spell that causes fear may need to be added to the list of 321s in #curefer. It's important to note that anything which causes fear does not necessarily need to be added: if you add a sword that causes panic on its target and shows a portrait icon, there's no need to add it since these are already covered by ops 161 and 240. If the sword plays a visual effect that lasts with the fear, or an expiration sound, or some other effect like a THAC0 penalty from the fear, then it needs to be added so that those effects also go away when the fear is cured. Short-term or instant effects (like a two-second visual or brief sound effect to show the target has been panicked) don't necessitate coverage in a #curefer 321.

Some practical examples from Item Upgrade (IU)

Let's first look at some items which cause reversible effects. IU adds Teleomortis (c2bow01.itm), a bow that causes confusion on hit. If the bow only caused confusion with a portrait icon, there would be no need to add it to #curecon. However, because it plays an animation to accompany the confusion, a 321 is needed--otherwise the confusion could be cured, but the animation would continue to play for the original confusion duration. The code is simple enough:

COPY_EXISTING ~#curecon.spl~ ~override~ // if using EEFP's cure spell setup, have it also cure confusion from teleomortis
  LPF ADD_SPELL_EFFECT INT_VAR opcode = 321 target = 2 timing = 1 parameter2 = 2 STR_VAR resource = c2bow01 END
  BUT_ONLY IF_EXISTS

The 321 targets the item (c2bow01.itm). The IF_EXISTS clause covers games without EEFP, so this can be added without additional checks such as FILE_EXISTS or MOD_IS_INSTALLED.

Item Upgrade also adds an updated Celestial Fury, which can stun its target. In this case, we don't have to patch #curestn because the upgraded weapon causes stun, a portrait icon, and combat feedback of 'Stunned'. With no lingering effects or expiration audio, there's nothing that needs to be removed aside from the stun itself and the portrait icon, which are handled directly by #curestn.

On the other side we have an updated version of Keldorn's sword, which now dispels magic on hit. Among its other effects dispel magic cures both feeblemind and deafness:

COPY ~itemupgrade/itm/c2keld02.itm~ ~override~
  // other code removed for clarity
  PATCH_IF FILE_EXISTS_IN_GAME ~#curedef.spl~ BEGIN // ee fixpack
    LPF ALTER_EFFECT INT_VAR match_opcode = 81 opcode = 146 parameter1 = 0 parameter2 = 2 STR_VAR resource = ~#curedef~ END
    LPF DELETE_EFFECT INT_VAR match_opcode = 240 match_parameter2 = 112 END
  END
  PATCH_IF FILE_EXISTS_IN_GAME ~#curefbm.spl~ BEGIN // ee fixpack
    LPF ALTER_EFFECT INT_VAR match_opcode = 77 opcode = 146 parameter1 = 0 parameter2 = 2 STR_VAR resource = ~#curefbm~ END
    LPF DELETE_EFFECT INT_VAR match_opcode = 240 match_parameter2 = 48 END
  END

The code is straightforward: if the cure spells exist, convert the existing cure opcode (81 for deafness, 77 for feeblemind) into 146 for the spells. We also remove the 240s for the associated icons (112 for deaf, 48 for feebelmind) as redundant since the icon removal is also handled by the cure spells. 

Another important thing to note is that, like the effect immunities, you may have to move specific effects into subspells since opcode 321 targets the entire resource. An example of this is Creeping Chaos, an updated version of Haer'Dalis's sword Chaos. Creeping Chaos causes the target to lose dexterity, as well as a chance to be confused (like Teleomortis, this confusion includes a visual that runs for its duration). If we simply updated #curecon with a 321 vs. the item, it means that anything that cured confusion would also roll back the dexterity drain, an unrelated effect. In this case we farm out the confusion to a separate spell, and target the separate spell with the 321 instead:

COPY ~itemupgrade/itm/c2hd2.itm~ ~override~
  // code removed for clarity

COPY ~itemupgrade/spl/c2hd2con.spl~ ~override~ // confusion effect from creeping chaos
  // code removed for clarity

COPY_EXISTING ~#curecon.spl~ ~override~ // if using EEFP's cure spell setup, have it also cure confusion from creeping chaos
  LPF ADD_SPELL_EFFECT INT_VAR opcode = 321 target = 2 timing = 1 parameter2 = 2 STR_VAR resource = c2hd2con END
  BUT_ONLY IF_EXISTS

The item applies confusion via c2hd2con.spl on hits, which #curecon.spl in turn cures. Since the dexterity drain is still sourced directly from the weapon (c2hd2.itm) any confusion cures do not affect it.

Some final notes

The examples above are also examples of where the old method would have failed. If someone was confused by Teleomortis and had the confusion cured via Restoration or Spiritual Clarity, the spinning animation would persist. While EE Fixpack (as of this post) is not yet released, the code above can be added now so that mods will seamlessly integrate when it becomes available.