ReadMe for the NPC PotionSaver code by DinkumThinkum:
*****************************************************

This readme provides a general overview of the PotionSaver code for modders and
mod users.  The file "PotionSaver_ModderInfo.txt" contains the actual code, as
well as tips and more detailed information for modders who want to use the code
in their own mods.

Players: you don't have to read all of this, but I do recommend at least reading
item #4 (and #5 if you're planning to edit or update a mod that uses the
PotionSaver code).

Modders: feel free to include this readme in any mods of yours that use the
PotionSaver code.  If you don't include this entire text file, I would recommend
including at least the information from item #4 in your mod's documentation.

Updated this readme August 5, 2005: added or updated information about updating
mods that use this code, contact information, and permission for using the code.

----------------------------------------------------------------------------

1. What's the PotionSaver?

If you've played with companions in your game, you may have noticed that any
Restore Health potions in their inventory get used up very quickly. This is
caused by a bug in the game's AI.

This PotionSaver code fixes the problem for Exclusive, Quality, and
Standard Restore Health potions, which should be enough to make a major
difference in the game.

Bargain and Cheap Restore Health potions are not handled; they're too weak to be
worth the extra coding required to deal with them. And there's no way to code
for potions created in the game using the Alchemy skill.

2. The bug:

When an NPC is in combat and their health falls below 50% of maximum, the game's
AI will cause them to automatically drink Restore Health potions if they have
them in their inventory.

However, Restore Health potions don't work instantaneously, but heal the NPC
gradually over time.

The bug is that the game's AI doesn't allow them time to work. So the AI may
cause an injured NPC to drink several potions one after another in one big rush,
without giving the first one time to take effect.

In my testing, I sometimes saw NPCs using five or ten potions at a time, even
when the first one was all that they actually needed to completely restore their
health.

End result is a large number of potions wasted.

Note: this game bug also affects Restore Fatigue potions, but my code just
handles Restore Health potions, which are the ones most critical to keeping a
companion alive.

3. The fix:

The NPC PotionSaver is a block of code inserted into the existing local script
on a companion NPC, where it controls the rate at which the companion can drink
Exclusive, Quality, and Standard Restore Health potions.

How it works:

When your companion is alive, conscious, and the game is not in menu mode (i.e.,
you're on the main game screen), the PotionSaver code removes all but one potion
from the companion's inventory. When the companion drinks that potion, the code
replaces it after a very short time delay (currently 1 second; can easily be
adjusted by modders).

The time delay allows the potion time to take effect before the NPC is given
another one. This prevents the game's AI from wasting potions by drinking them
too fast.

When the companion dies, becomes unconscious, or the game is in menu mode, all
the potions will be returned to the companion's inventory. This allows the
player to view, remove, etc. the potions using Companion Share or by looting the
dead/unconscious companion's body.

This swapping of potions in and out of the companion's inventory should be
completely invisible to the player: any time you view your companion's
inventory, their full supply of potions will always be there.

Note: the PotionSaver code does not cause the companion to drink potions; that's
handled by the game's AI programming. All PotionSaver does is add a short delay
to prevent potions from being wasted by too-fast consumption.

4. Tips for players:

a. The PotionSaver code is set up so the companion will use Exclusive Restore
Health potions first, as long as they have them; Quality and Standard potions
are ignored when the companion has Exclusive potions available. If they don't
have any Exclusive potions, then the companion will use Quality potions. The
companion will only use Standard potions when they're out of Exclusive and
Quality potions.

So if your character is just starting out (i.e., still at low level) I'd suggest
just giving your companion Standard potions. They're fairly cheap, but should
be enough to keep your companion alive while fighting low level opponents. Wait
until you level up and have more money (and are facing tougher opponents) before
you give Exclusive or Quality potions to your companion.

b. A potential exploit: because the potions are removed from inventory when the
game is not in menu mode, their encumbrance isn't figured in when the companion
is moving or fighting. So you can give your companion 10,000 Restore Health
potions without the weight slowing them down.

Obviously, whether or not you take advantage of this is up to you. The
encumbrance shown on the Companion Share screen will be the correct value (i.e.,
including the weight of the potions); use that as a reference to see if your
companion's load is realistic.

If you decide to exploit this to use your companion as a potion packhorse, keep
in mind that the game does have limits on how many inventory items it can
handle. I did some quick testing and didn't see any obvious problems with
several thousand potions in a companion's inventory, but I don't recommend
pushing your luck. Exploit at your own risk...

NOTE: This is not related to the various encumbrance bugs in the game. This is
just a harmless side effect of the script: it has no effect on the player's
encumbrance, and the only effect on the companion is that the potions will
appear weightless outside menu mode.

5.  Installing updated versions of mods that use the PotionSaver code:

If you update a mod that you're already using in your saved games, remove any
Restore Health potions from your companion's inventory before installing the
updated mod and save your game before you install the update.

You can put the potions in your own character's inventory or just drop them on
the ground.  You just want to temporarily remove them from the companion before
installing the update, to eliminate any chance of the potions being lost in the
update process.

Once you reload the game with the new version of the mod installed, give the
potions back to your companion.

(Updating or modifying a mod that's already part of your saved game is always
risky, but this should at least keep your companion's potions safe.)


6. The time delay:

To get an idea how short the one second time delay is, the swirling graphics and
sound effects you see when an NPC uses a potion last several seconds. So when
your companion uses a potion, they'll already have a replacement while the
graphics and sound effects for the one they just used are still being displayed.

But, short as that one second delay is, it's enough for the potion to start
healing them and to keep the game's AI from causing them to guzzle more potions
they don't need.

7.  Support for the PotionSaver code:

I'm active as DinkumThinkum on several Morrowind-related web forums, and you
should be able to reach me by PM on any forum where you see me posting
regularly.  I should always be reachable at Bethesda's official TES forums.

-------
Credits:
-------

Grumpy, Emma, and The Other Felix for ideas and inspiration that led to this
bug workaround. GhanBuriGhan for "Scripting for Dummies", without which I'd
never have been able to do anything like this. Bethesda for Morrowind and the
whole TES series.

------------
Permissions:
------------

I wrote this code as a modders' resource: something for modders to use in their
own mods.  I do ask that you give me credit when you use this in your own mods,
but you don't need to ask me for permission.

You're also free to adapt or modify my code as needed for your own mods, but
please document what you change, in case any problems come up and we need to
figure out what's what.




