==========================
MigMaster kinda ok API
version 1.3
==========================

Following is a description of the few features contained in the file MigMaster.esm, with some examples of how to use them in your own mods.
Unfortunately I don't have the time nor skills to put together a truly impressive API or readme like the ones from Fundament, but it's something...

=======================================================================
List of functions: formID for remote use:

(succcesses:int) migActorIdentFunction{string} 000808
(succcesses:int) migItemIdentFunction{form,string} 00081B
(succcesses:int) migItemCompareFunction{form,string} 00081C
(succcesses:int) migCellIdentFunction{form,string} 00081E

(copied actor:form) CreateActorCopyFunction{short,bool,short,bool} 000ED3

(result:float) migMathIsBetween{value,min,max} 00081A
(result:float) migMathMax{value1,value2} 000818
(result:float) migMathMin{value1,value2} 000817
(result:float) migMathTrim{value,min,max} 000819

(result:float) migDifficultyAdjust{float} 00081D
(result:float) migAVAdjust{float,string} 00087A
(icon:string) migGetIcon{form} 00087C

(block percentage: float) migCalcActorBlock{} 00087B
(damage potential:float) migCalcActorDamage{form} 00087D
(armor rating: int) migCalcArmor{form} 00087E
=======================================================================

==========================
Ini loading
=========================
The Migmaster.esm file will load ini files under Data\ini\Migck\ named as any of your currently loaded mods, with preference for those with a " - player's name" suffix
e.g. If you have a mod named DLCFrostcrag.esp loaded, MigMaster.esm will load the ini file Data\ini\Migck\DLCFrostcrag.esp.ini if it exists.
And if your character is named "Sir John", MigMaster.esm will instead load the ini file Data\ini\Migck\DLCFrostcrag.esp - Sir John.ini if it exists.
This is most useful for creating identifier lists that will be loaded together with your different mods.



==========================
Object Identifier Function
==========================
Create custom lists with parameters to be checked against various types of objects. There are functions to check for:
- actors: migActorIdentFunction (formID 000808)
- inventory objects: migItemIdentFunction (formID 00081B)
- object comparison: migItemCompareFunction (formID 00081C)
- cells: migCellIdentFunction (formID 00081E)

migActorIdentFunction must be called on actor references, and uses a list string as argument.
migItemIdentFunction and migItemCompareFunction use a base object and a list string as arguments, they are for checking base objects.
migItemIdentFunction must be called with items eligible for being in an inventory as the first argument.
migItemCompareFunction is intended as a simple comparison function, not terribly useful but simpler than the other two.
I have no idea if migCellIdentFunction actually works, or if it works well enough...

What can you enter in the lists and how does it work:

sListType - this is the name of the list, used when calling it for an actor, item, etc. No need to redeclare it for adding new stuff to the list, only to change to which list you add new stuff to

sListAdd is a string, built with sv_Construct.
+ For the migActorIdentFunction :
- If it contains the "M_" prefix, it will be compared against the calling actor's model path (the path to its skeleton file), and return true if it contains that string
- If it contains the "T_" prefix, it will be searched for in a calling creature's models list, and return true if the string is found in that list. Only works with full model filenames!
- If it contains the "K_" prefix, it will be searched for in the calling actor's toggled anims, if any, from its specialanims folder. Only works works with full model filenames!
- Otherwise it is simply checked against the calling actor's own name, and return true if the string is found in it
+ For the migItemIdentFunction:
- if it contains the "T_" prefix, it will be compared against the item's inventory icon, or against the armor or clothing's male (default) icon.
-- if it also has the "f_" prefix right afterwards, it will be compared against the armor or clothing's female icon.
- if it has the "M_" prefix, it will be compared against the item's model path. For armor and clothes, by default it checks the male biped path. You can use the following additional prefixes after M_:
-- "f_" for the female biped path.
-- "g_" for the male ground path.
-- "h_" for the female ground path.
- Otherwise it is simply checked against the object's name, if any.
+ For the migItemCompareFunction, if the object has a name it is compared against it, otherwise against its model path.
+ For the migCellIdentFunction, use an "N_" prefix to compare against the cell's name, otherwise it will check the cell's editorID.

rListAdd can be a lot of things:
+ For migActorIdentFunction:
- Reference, returns true if the calling actor is that reference
- Faction, returns true if the actor is in the faction
- Magic Effect, returns true if the actor is under it
- Script, returns true if that's the actor's own script
- Enchantment or Potion, returns true if the actor is under that magic item's effects
- Spell: for regular spells and powers, returns true if the actor has it in his spell list, for diseases and abilities, if he's under its effects
- Armor, Weapon, Arrow or Light, returns true if the actor has it equipped
- Apparatus, Book or Misc items, returns true if the actor has it in inventory
- Clothing: if it has 0 value & weight and is set as unplayable (a token), returns true if the actor has it in inventory, otherwise if he has it equipped
- Creature or NPC base record, returns true if it matches the actor's base object
- AI package, returns true if it's in the actor's package list
- Combat Style, returns true if that's the actor's combat style
- Leveled Spell list, returns true if it's in the actor's base spell list
- Shader Effect, returns true if the actor currently has that shader displaying
- Sound, returns true if it's found in the actor's sounds list (creatures only)
- Class, Hair, Eyes or Race, returns true if it matches the actor's own (NPCs only), note that some NPCs have no hair or eyes defined
+ For the migItemIdentFunction, references in the lists are used as their base object:
- Returns true if the item in the list and the item to check match, of course
- Enchantment, returns true if that's the item's enchantment
- Magic Effect, returns true if the item is a sigil stone or ingredient and has it, or if the item's enchantment does
- Script, returns true if that's the item's own script
- Container, NPC or Creature, returns true if that base container has the item in its inventory
- Leveled List, returns true if the item is found in it
+ For the migItemCompareFunction, only reference, base object or script matches are checked. It does accept object references comparisons
+ For the migCellIdentFunction:
- Reference, returns true if its parent cell is the cell being checked
- Cell, returns true if they match
- Water Type (???), returns true if that's the cell's water type
- Actor or Faction, returns true if that's the cell owner
- Climate, returns true if that's the cell's climate (presumably for cells that behave like exteriors only)
- In any other case, references in the cell will be checked and matches made for base objects that match with the objects in the list


Example for migActorIdentFunction:
set migMasterQ.sListType to sv_Construct "whatever" ;this is the name of the list, supply that name to the function to check the calling actor against what's in it

set MigMasterQ.sListAdd to sv_construct "M_John" ;an actor whose full model path includes "creatures\thisIsJohn\" will return positive when checked by the function for list "whatever"
set MigMasterQ.sListAdd to sv_construct "M_\John" ;an actor whose full model path includes "\Johnson\" will return positive when checked by the function for list "whatever"
set MigMasterQ.sListAdd to sv_construct "T_John.nif" ;a creature whose toggled on model list includes a file named "John.nif" will return positive when checked by the function for list "whatever"
set MigMasterQ.sListAdd to sv_construct "John" ;an actor named "Johnson" will return positive when checked by the function for list "whatever"

set MigMasterQ.rListAdd to (GetFormFromMod "ModName.esp|esm" "xxxxxx") ;see above, if the actor matches the form entered here by those rules, the function will return positive for him for list "whatever"

SetStage MigMasterQ 5 ;adds the form in rListAdd and string in sListAdd to the "whatever" comparison list, use it after each declaration of rListAdd and/or sListAdd


to use it in a script, it would look like:
int iSuccess
...
let iSuccess := .Call migActorIdentFunction "list you want to check"

if you don't want a MigMaster.esm dependency:
...
ref rScript
int iSuccess
...
if IsModLoaded "MigMaster.esm"
let rScript := GetFormFromMod "MigMaster.esm" 000808 ;for the other functions, check the formID at the beginning
let iSuccess := .Call rScript "list you want to check"
endif

iSuccess will be equal to the number of matches found in the list for the who called the function



=========================
Safe Cloning Function
=========================
A script function to be used in place of the CreateFullActorCopy function, to avoid some of its pitfalls.

to use it in a script, it would look like:
...
ref actorCopy
...
let actorCopy := .Call CreateActorCopyFunction
...

or if you don't want a MigMaster.esm dependency:
...
ref rScript
ref actorCopy
...
if IsModLoaded "MigMaster.esm"
let rScript := GetFormFromMod "MigMaster.esm" 000ED3
let actorCopy := .Call rScript
endif
...
What you do then with actorCopy is up to you.

what each is:
: 0 - no items will remain on the copy, 1 - only equipment from the original, 2 - all items are copied
: 0 - all factions removed from copy, 1 - factions from original reapplied
: 0 - removes all spells from copy, except racial ones, 1 - removes bound and summon spells, 2 - removes scripted spells, 3 - removes bound, summon and scripted spells, 4 - only removes player's custom made spells
: if other than 0, the script will dump to the console what's it doing in each step of the copying process


IMPORTANT
The included SafeCloningFunction - Filter.esp file patches scripts from Oblivion, Nehrim, Better Cities, bg's Magic and Integration mods to use this function.
It REQUIRES Wrye Bash to be merged in a bashed patch, or your game WILL crash if you try to load the game with it active



=========================
Math Functions
=========================
Some simple math shortcut functions to return the result of a number comparison, their names should be self-descriptive:
- migMathIsBetween{value,min,max} formID 00081A
- migMathMax{value1,value2} formID 000818
- migMathMin{value1,value2} formID 000817
- migMathTrim{value,min,max} formID 000819

... I suspect that if I could understand what OBSE's FMod function even does, these might not be so necessary...

=========================
Difficulty Calculator
=========================
Given a numeric value, returns it adjusted to the game's current difficulty. Useful for adjusting the damage done through a script before applying it to the player or from the player, since tose are the only instances that difficulty adjusts by default. Must be called by an actor reference, the script will adjust the value depending on whether it's the player or another actor calling it. Example:

float damage
...[after calculating damage in your script]
let damage := .Call migDifficultyAdjust damage

or use it remotely with formID 00081D



=========================
AVUncapper Shortcut
=========================
A commodity to calculate diminishing returns using AV Uncapper's formulae (http://www.nexusmods.com/oblivion/mods/34841). It uses a number and a string as arguments. The string must be one of the game settings that AV Uncapper adds to the game to enable/disable diminishing returns. Basically if the setting is on, will return the number adjusted to that setting's diminishing returns formula, otherwise returns it as is.
The settings it recognizes are:
- iavuMagicEffectResistUseDR
- iavuMagicItemResistUseDR
- iavuBlindnessUseDR
- iavuBlockDamageReductionUseDR
- iavuChameleonUseDR
- iavuDefendBonusUseDR
- iavuReflectDamageUseDR
- iavuResistNormalWeaponsUseDR
- iavuSpellAbsorbUseDR
- iavuSpellReflectUseDR

Example for Blindness
...
let value := Call migAVAdjust (actorRef.GetAV Blindness) "iavuBlindnessUseDR"

But you could use any numeric value as the first argument.

Use it remotely with formID 00087A
Use Fundament's (http://www.nexusmods.com/oblivion/mods/41005) fuctions instead if what you need is to calculate a diminished value without checking for AV Uncapper's settings for it.



=========================
Icon Retriever
=========================
Retrieves the icon of an inventory object. If called BY a female NPC ON an armor or clothing item, will return the female icon path if it exits. In any other case it returns the male/default one, cuz I'm sexist n' shit.

string_var sPath
ref rItem
...
let sPath := Call migGetIcon rItem
or
let sPath := femaleActorRef.Call migGetIcon rArmorItem

Use it remotely with formID 00087C


=========================
Block, Damage and Armor Calculators
=========================
Thse functions must be called BY actors, either creatures or NPCs. They calculate a few combat derived statistics based on their skills. For best results, have Fundament (http://www.nexusmods.com/oblivion/mods/41005) installed for correct Luck modifier calculations.


* migCalcActorBlock: returns the block effectiveness of the actor, i.e. how much damage % he's able to block from a hit.

float fResult
...
let fResult := .Call migCalcActorBlock

Use it remotely with formID 00087B


* migCalcActorDamage: This function requires a form as argument, but can work with whichever it is.
If the supplied form is a weapon (or arrow), will calculate that weapon's damage adjusted to the actor's corresponding skill.
If the actor also has that weapon equipped, the result will be further adjusted by his weapon's condition.
If the supplied form is anything else, it will return the attack damage of creatures, or the hand to hand damage of NPCs.

float fResult
...
let fResult := .Call migCalcActorDamage WeapIronLongsword ;calculates how much damage the actor does with an (or his, if equipped) Iron Longsword.
let fResult := .Call migCalcActorDamage Gold001 ;Gold001 is not a weapon, so it will calculate how much damage the actor does in hand to hand.

Use it remotely with formID 00087D


* migCalcArmor: This function requires an armor form as argument. Will return its armor rating adjusted to the actor's corresponding skill, and to its condition if the actor has it equipped. Alas, I believe the result doesn't really match what the UI says, so consider it on the fritz.

int iResult
...
let iResult := .Call migCalcArmor DaedricBoots

Use it remotely with formID 00087E