###################################################################
# EK_UnusualApplications #
# #
# a collection of convenience spells #
###################################################################

DISCLAIMER: This mod is still considered beta as it depends
on a beta version of SKSE supporting papyrus.


-------------------------------------------------------------------
| Description |
-------------------------------------------------------------------

There are some activities your character must perform regularly
that over time may become repetitive and boring.
This mod adds some magic means to help with these chores:


* Harvest Flora:
As long as the concentration spell is active, pick ingredients
(including insects&fishes) from within an ever widening circle.

The Player learns the spell after having finished the alchemy
tutorial quest.

* Find Any Ore:
Locate an undepleted ore vein nearby and start a quest, marking
the vein's location by the quest's map marker.
The vein is also marked with a glowing shader and a particle
cloud emitted from it.
The quest auto-finishes after a certain amount of time.

The Player learns the spell after having finished the smithing
tutorial quest.

* Find Ore of specified type
Additional spells for finding a given type of ore can be
- found in spell tomes scattered at appropriate places
- or learned by mining ore after having received the general
spell.

Any character that has completed a tutorial quest before
installation of this mod will receive the respective spell at
startup.

* Vulture's Eye:
The corpses of killed enemies may be difficult to find,
especially when you've killed them long range or they are hidden
in high grass.
This spell detects corpses (dead actors) within an ever widening
circle and marks them with a bright green-yellow particle cloud.

The Player learns the spell by being in the vicinity of an actor
he killed for a sufficient long time.

-------------------------------------------------------------------
| Configuration |
-------------------------------------------------------------------

I most certainly will add a proper configuration file in the
future. But this won't be before SKSE introduces a OnSaveGameLoaded
event!

Until then you'll have to change the spell parameters manually.

Calling the lesser power "EK_UnusualApplications Configuration" will
start a multi-level configuration menu.

Until SKSE has functions for reading/writing ini-files your changes
will be for the current character only, that is:
stored in the savegame.

The configuration defaults stored in the esp are shown in the
configuration statements shown below.

Note that you can make a pseudo-configuration file:
- copy&paste these lines into a file (let's call it UA_cfg)
- adjust to your needs and then,
- on the game console type "bat UA_cfg".

>>>>>>>>>>>>>>>>>>>>>>>>> harvest flora <<<<<<<<<<<<<<<<<<<<<<<<<<
set EK_GlobHarvestDistanceMin to 100
set EK_GlobHarvestDistanceMax to 5000
set EK_GlobHarvestDistanceRPS to 200

These variables control the search for ingredients: the search
radius starts at DistanceMin and grows by DistanceRPS per second
up to a maximum of DistanceMax.

Note that these distances are game-units and don't translate
particularly well into SI units.

Note that (see section Technicals) a _random_ object withing the
current search radius is checked for validity.

Thus with a high value of DistanceMin you may never pick the flower
right in front of you because others, well out of view, are picked
instead.
The same goes for too high values of DistanceRPS: after only a few
iterations the current search radius may be so big high that you'll
miss the 'obvious' choice in front of you.
With too low values of DistanceRPS and DistanceMin you may run out
of magica before you hit the first valid target.

>>>>>>>>>>>>>>>>>>>>>>>>>>> find ore <<<<<<<<<<<<<<<<<<<<<<<<<<<<
set EK_GlobMiningDistanceMin to 1000
set EK_GlobMiningDistanceRPS to 5000

These variables control the search for ore veins: the search
radius starts at DistanceMin and grows by DistanceRPS per second
without a maximum distance.
The notes from the 'harvest flora' section hold here, as well.

set EK_DisableOreExperience to 0

If you set this variable to 1 you won't get specialized ore spells
by mining ore.

set EK_GlobMiningTimeOut to 30

Determines how long (in [s]) the marked ore vein will be displayed
on the map.
During this time the FindOre spell will terminate immediately.

>>>>>>>>>>>>>>>>>>>>>>>>> find corpses <<<<<<<<<<<<<<<<<<<<<<<<<<
set EK_GlobCorpseDistanceMin to 250
set EK_GlobCorpseDistanceRPS to 200

These variables control the search for corpses: the search
radius starts at DistanceMin and grows by DistanceRPS per second
without a maximum distance.
The notes from the 'harvest flora' section hold here, as well.

set EK_GlobCorpseBeaconLifetime to 15

Determines how long (in [s]) a detected corpse will stay marked.

-------------------------------------------------------------------
| Troubleshooting |
-------------------------------------------------------------------
On the entry level of the configuration menu you'll find an entry
'Troubleshooting', as well:

(1) Stop Spell-Giving Quest
In rare cases, for example after a mod-update, it may be
necessary to restart the quest-script that will eventually
give the spells to the player. Use this button to stop the quest
(2) Start Spell-Giving Quest
and this one to start it again.

-------------------------------------------------------------------
| Things you should take note of |
-------------------------------------------------------------------
All spells are concentration spells with MagicEffect-scripts
attached.

As of now the Papyrus language has no command to selectively work
on a list of references: you can only pick the _nearest_ or a
_random_ reference to an object contained in a given list and
within a certain search radius, using e.g.
FindRandomReferenceOfAnyTypeInListFromRef
or FindClosestNearest*.

This means that you _can_ e.g. pick the nearest ore vein but
(in case it is already depleted) you _cannot_ step to the next
nearest.

The workaround used here is to
- start with a small search radius R1
- process a random reference within R1
- increase the search radius to R2=R1+deltaR
- ...
until
- the concentration spell is stopped for Harvest Flora and
Vulture's Eye
- the first valid (undepleted) reference is found for Find Ore.
- or the magic bar runs dry.

This method is likely to change once SKSE provides the necessery
script extensions.

-------------------------------------------------------------------
| Requirements |
-------------------------------------------------------------------
This mod requires SKSE with papyrus support, that is at least
version 1.05.xx

-------------------------------------------------------------------
| Installation/Update |
-------------------------------------------------------------------
Unzip into ${SKYRIMBASE}/data/, activate.

Beginning with version 0.97 there are the files
EK_LimitedItems.esp
EK_LimitedItems.bsa
EK_LimitedItems.txt

De-activate and remove these files for de-installation.

Update simply by overwriting.
If you are updating from versions 0.95 or 0.96, you need to delete
the files

Scripts/EK_FindOre.pex
Scripts/EK_MarkOre.pex
Scripts/EK_HarvestFlora.pex
Scripts/EK_GiveUnusualApplications.pex
Scripts/EK_GiveIndividualOreSpells.pex
Scripts/Source/EK_FindOre.psc
Scripts/Source/EK_MarkOre.psc
Scripts/Source/EK_HarvestFlora.psc
Scripts/Source/EK_GiveUnusualApplications.psc
Scripts/Source/EK_GiveIndividualOreSpells.pex

-------------------------------------------------------------------
| Version History |
-------------------------------------------------------------------
v0.95: - initial release
v0.96: - spell delivery method changed
- added spells for individual ores
v0.97: - added Vulture's Eye

-------------------------------------------------------------------
| Credits |
-------------------------------------------------------------------
I'd like to thank

- as always the SKSE team: without you this would not be possible
- LaoArchAngel, from his Auto Harvest mod I learned how to avoid
picking owned ingredients.
(http://skyrim.nexusmods.com/downloads/file.php?id=10067)
- RedWood Elf and RandomNoob for their explanations about quest
scripting and ore vein evaluation.

-------------------------------------------------------------------
| Legal |
-------------------------------------------------------------------
There's no point in trying to protect published sourcecode from
being used and it wouldn't be my style, anyway, because I've
learned a lot by looking at other people's scripts.

So, you're welcome to use this or parts of it in your work.
You could then, however, do me the favour of
- notifying me if you find any bugs or have suggestions for
improvements
- pointing me to your work, so I can have a look at it and adopt
back what I like about it.