====== Companion Compatibility ======
Author: Eloise Shadowborn
Date: 4 December 2010

====== Overview ======
Ever been annoyed by the fact that enemies prefer to attack your companion, your horse, or your summon instead of you? While it is possible to create an individual companion in such a way that this is not an issue in the vanilla game, the wide variety of mods and possible combinations of mods makes it virtually impossible to remove this issue from a companion in a modded game � if you use companions with OOO or FCOM, you should know what I mean. That's where this plugin comes in. It will detect any player companions, minions or horses, and if an enemy targets them instead of the player, it will redirect them to attack the player. There are also optional settings to extend this functionality to summoned creatures, and companion minions (such as Beau's scamp from CM Partners).

====== Compatibility ======
This plugin has been tested with:
CM Partners
Companion Share & Recruit
Companion Vilja

This plugin has been tested in both Tamriel and the Shivering Isles.

====== Requirements ======
Oblivion 1.2.0416
OBSE 19b (or newer)

====== Installation ======
Extract the archive to your Oblivion/Data folder. Select the plugin. Load the game. Simples.

====== Load Order ======
It doesn't really matter where this plugin is placed in the load order. It is completely self-contained. I have it placed directly after the companion mods � for BOSS users, it's right at the bottom of the Companions group, which is just before the Race Overrides.

====== Settings ======
This plugin uses a settings file, imaginatively called 'Companion Compatibility.ini', which is installed in the Oblivion/Data/Ini folder. This file is read each time a game is started or loaded. The settings are:

DebugCompComp: When set to 1, this enables debug messages. Should only be set for troubleshooting, as it writes a shed-load of messages to the console.

IncludeSummons: When set to 1, this extends the plugin's functionality to summoned creatures. On by default, so turn it off if you want to use your summons as meat shields.

ExtraFollowers: When set to 1, this extends the plugin's functionality to followers of companions � for example, Beau's scamp minion in CM Partners. If IncludeSummons is also set to 1, this will also include anything that any of your followers summon.

ChainReaction: EXPERIMENTAL! When set to 1, this will change the way that enemies are redirected when they attack a follower. Normal behaviour (when this is set to 0) is that any enemies who attack a follower will be redirected to attack the player. When this is set to 1, they will instead be redirected to whoever the follower is following. For example, if you have Beau and his scamp minion following you, and an enemy attacks the scamp minion, they will be redirected to attack Beau. Of course, as Beau is following the player, they will then be redirected to attack the player, but each redirect takes time (see below), so if you have a number of companions following each other in a chain, setting this on may make it easier to 'swarm' powerful enemies.

CycleFrequency: Sets the frequency with which this plugin's script will cycle through the actors in the vicinity, checking whether they are companions or are enemies who are attacking companions. The default is 2.5 seconds.

====== Technical Details ======
This plugin uses OBSE's ref-walking functionality to cycle through all actors in the current cell. If the actor has a 'Follow' AI package with a target of the player, they will be considered a companion. If the actor is owned by the player (e.g. a player-owned horse), they will be considered a companion. Actors that are considered a companion are added to a companion faction, which has no relationship modifiers with any other faction and should therefore be completely invisible.

If IncludeSummons is set, and the actor has the 'Summon Creature Defend' package with a target of the player, they will be considered a companion. If ExtraFollowers is set and the actor has a 'Follow' AI package with a target who who is in the companion faction, they will also be considered a companion. If both IncludeSummons and ExtraFollowers are set, and the actor has the 'Summon Creature Defend' package with a target who who is in the companion faction, they will also be considered a companion.

There are three special cases:
Companion Share and Recruit allows you to organise followers into squads. Due to the way that the squads work � squad members follow an invisible object that shadows the squad leader � it is necessary to identify the squad leader (who will be detected as a normal follower) by colour and specifically check for other members of that faction by the fact that they are following the invisible object associated with that colour.

CM Partners don't follow the player reference. Rather, they follow the player object. This means that GetPackageTarget returns zero. To cater for this, an array of actor references in the current cell and their base object ids is built, and OBSE 19's GetPackageTargetData is used to retrieve the target object id and cross-reference it to the relevant reference.

Some companions have horses. These are detected using GetHorse and GetTravelHorse. From testing with Vilja, it appears that GetHorse only returns an object when she is preparing to mount Bruse (her horse). However, as an actor only has to be detected as a companion once, this should be sufficient to detect Bruse. Other companions may differ in this, though.

When it comes to enemies, this plugin checks if an actor is attacking a member of the companion faction. If they are, it then checks that the attacking actor is hostile to the player and has detected the player. If both of these are true, the attacking actor is redirected to attack the player, or whoever the companion is following if ChainReaction is set on.

====== Version History ======
0.1 Initial version for testing.
0.5 Incorporated OBSE 19 functions to better check for CM Partners.
1.0 Initial public release.

====== Credits & Thanks ======
Thanks to the OBSE team for providing the functionality that makes this plugin possible.
Thanks to Arkngt for testing.
Thanks to Emma & CDCooley for Vilja, who was the main reason I created this plugin.
Thanks to H0bbs for the bits of scripting from Shadow Ranger that I borrowed.

====== Permissions ======
You are free to modify the script contained within this plugin, or borrow bits from it, for your own personal use or for your own mods. However, please do not upload this plugin, or a modified version of this plugin, anywhere without first seeking my permission.