File: Readme-Collection_Tools--V0-3-2.txt
Version: 0.3.2
Author: Raider480
Date: 2016-09-08

**********
Nexus Short Description
**********
Adds reusable tools for harvesting the items from flora/misc items/corpses on demand, and for collecting loose junk automatically, each within a configurable radius.

**********
Summary
**********
Adds a "[Utility] Mass Harvester" item to the game, with a corresponding recipe under "[UTILITY]" at the Chemistry Station, along with its configuration holotape.
This will harvest and collect items within a configurable radius, and then open a container interface showing the acquired items; once this is closed, the player will receive those items.

Additionally, adds a [Utility] Junk Vacuum item to the game, craftable in the same category and using the same configuration holotape.
When activated, this will automatically add any loose junk items to the user's inventory.

Also contains optional files to add support for DLC content.

**********
Description
**********
The recipes for the items are configured to disallow crafting more if one of any given item is already in the player's inventory, like that for the configuration holotape.
This is to discourage having more than one at once. There should be no reason to run more than one of any given item simultaneously, and the corresponding logic is coded to catch this, in order to help prevent potential issues.

Activating a tool will "consume" it but then return another almost immediately afterward.
Then, the corresponding script will then search the area in a radius roughly equal to what can be chosen from the holotape.
These values are very loose approximations, and were formed from documentation for the Skyrim version of the Creation Kit; they should still be suitable, but don't rely on them for any sort of precision.

A notification will appear in the corner of the screen indicating the progress of various collection routines within the given radius.
Then, each appropriate item will be processed, and anything yielded will eventually make its way to the user.
The transfer interface for a container may open to show some collected items, depending on the tool used, but no items can be put into it or taken out from it - just close this and the items will be added.

The configuration holotape supports various options for each tool added, including configuring the harvester to harvest flora, or to harvest corpses as well.
The items on any corpse within the harvesting radius will be pooled and presented to the player in the same manner as other yielded items.
Additionally, the holotape supports running both flora and corpse harvesting "at the same time".
This will in reality run first the flora harvesting and then the corpse harvesting back-to-back, saving the user from having to change the configuration every time if they want to use all features from this mod.
Flora harvesting can be set to ignore or enforce a requirement that flora not be harvested if that would be stealing for the user; the default behavior is to ignore this requirement.
Corpse harvesting can be set to ignore or enforce a requirement that the actor in question have been killed by the user; the default behavior is to ignore this requirement.

The Junk Vacuum will always collect loose items lying in the world around the player, and uses its own, separate radius.
The Junk Vacuum can be configured to either process or ignore items considered stealing for the user, or even to strip ownership information.

**********
Compatibility
**********
This doesn't alter anything from the base game, so it should be fairly compatible with most mods.
As such, the load order shouldn't matter too much, but any optional patches will of course need to be below both the base plugin for this mod and the DLC/mod agains which the compatibility patch should run. For example, something like this:
Fallout4.esm
[...other DLC...]
DLCCoast.esm
[...other DLC...]
[...other ESMs...]
Homemaker.esm
[...other ESMs...]
[...other ESPs...]
Rdr-Harvesting.esp
Rdr-Harvesting-DLCCoast.esp
Rdr-Harvesting-Homemaker.esp
[...other ESPs...]

Any mod that adds custom flora or junk items won't work without a patch.
If you have a mod that you really want added you can add a comment or PM me and I can have a look, or you can just make your own patch that adds the new flora to the form list of flora from the base plugin file.
Any mod that changes the ingestible yielded by pre-existing flora records should work, however, provided that it is against the same flora base object and loads before this mod.

This should be compatible with most mods that add new NPCs, provided that they use the keywords shared by other NPCs in the game.
Custom races may possibly introduce problems with being harvested, however, though the scripting tries fairly hard to find all valid corpses.

**********
Disclaimers
**********
Try to be gentle with the scripts; I tried to account for most situations, but some activities might cause some trouble, like the following:
- Fast-travelling away from the activation area immediately after using the item
- Spam-activating multiple tools within a very short period of time, or quickly changing the harvesting radius between these
- Trying to coerce actors other than the player into using the tools; while the scripts were written the be agnostic to whoever used it, this has not been tested
- Installing/uninstalling the mod or DLC plugins, or saving and exiting, while the tools are running; saving and exiting should work, but is not recommended (especially between updating the mod)

The harvester should never take very long to finish, and if it does then something has probably gone wrong; corpses may take longer though.
You may want to consider saving before each activation, because I had some early issues in testing with the game freezing after collecting from larger numbers of harvestables.

This mod has had some light testing to ensure that it functions as expected, but keep in mind that this is just an early release and bugs are very possible.
Please send any suggestions/bug reports my way, and I will do my best to address them.

Try not to travel too far too quickly while the harvester is running; it uses an invisible container to give items to the player, and if this is inaccessible at just the right moment the mod may have unpredictable behavior.

The usual warnings for mods apply - I am not responsible for anything bad that may happen to your saves/game/computer/etc., use at your own risk, ...

Please do not upload this elsewhere.

**********
Changelog
**********

*****Version 0.3.2 (2016-09-08)*****
General:
Formalized placement of the tools' utility actors, and tweaked those actors themselves again.
Introduced a shared framework for updates by compatibility patches; this is less error-prone, is much easier to maintain, and slightly reduces the size of this mod.
Transitioned existing patch logic in all DLC compatibility patches to the new, shared framework.
Edited out lingering debug code both from all DLC compatibility patches and from all terminal fragments.

Tool - Mass Harvester:
Corrected edge case where the game might lock up if the tool is active or finishes operating while the user is in VATS.
Added first pass at a workaround for a base-game bug whereby corpses might be incompletely emptied of all items.

Tool - Junk Vacuum:
Corrected script logic that was leading to missed allocation of an array; this was causing script errors, but the issues should be resolved now.
Added new activation sound effect; this alternates between two files on successive activations of the tool, and should help to distinguish when this tool is toggled.
Added support for some missing base-game items, in particular the Fusion Core; note that fusion generators in the world, which contain Fusion Cores too, are ignored by the tool.
Added support for new items from the base-game, larger-shipments update.

DLC 03 patch - Far Harbor:
Fixed script problem leading to the wrong timer ID being used for the spinlock's busy-wait timeout: the need to fix this separately was obviated by using the new shared framework, instead of an independent script.
Removed some non-junk items from the list of new items to add and patched them out from existing partial lists; the Junk Vacuum should not have been trying to collect these items in the first place anyway.

DLC 06 patch - Nuka-World:
Introduced; adds support for Nuka-World flora harvesting, etc. activators harvesting, junk vacuuming, and misc. items vacuuming.

*****Version 0.3.1 (2016-08-11)*****
General:
Changed DLC patches to use less-intrusive notifications upon successful installation, rather than message boxes.
Further reduced value of tools, to 15 caps each.
Changed tools' preview transforms to something more reasonable; they should by default be fully visible in the inventory now.
Changed tools' script logic to use message properties for most info conveyed to the user, rather than raw strings (this shouldn't be noticeable).
Tweaked the utility actors used to effect the tools' operations (this shouldn't be noticeable).

Tool - Mass Harvester:
Improved performance regression from excessive safety checks; operation is now slightly more dangerous if the user leaves the area very quickly after activating the tool, but should still be resistant to most major issues.

Tool - Junk Vacuum:
Added some missing junk items from the base game. The appropriate forms should automatically update themselves the next time the Junk Vacuum is run, but this can also be triggered manually through the config holo.
Slightly improved performance, though the script logic still somewhat suffers from the same performance regression that affected the Mass Harvester.

*****Version 0.3.0 (2016-07-19)*****
General:
Changed mod name to "Collection Tools" to reflect both the more generalized behavior and the added tools.
Removed meshes and textures archives for this mod's utility actors - a CK update indicates that these are no longer necessary to include.
Generalized the configuration holotape to allow modifying the behavior of more tools; currently configures the Mass Harvester and the Junk Vacuum.
Increased the granularity of control and information offered by the configuration holotape.
Adjusted the weight and value of tools to 0.1 and 25, respectively.
Added safety checks to prevent possible race conditions with multiple compatibility patches running simultaneously.
Added config holo menu item to check what tools are currently running.

Tool - Mass Harvester:
Added more safety checks to the Mass Harvester's scripting.
Added more items for misc harvesting by the Mass Harvester - caps: from bottlecap mines, Money Shot procs, and caps stashes.
Modified the forms for havesting from corpses in trying to improve the speed at which corpses are processed - please let me know if any corpses are being ignored now!
KNOWN ISSUE: Corpse harvesting does not work against disintegrated/gooified corpses.

Tool - Junk Vacuum:
Introduced; automatically collects loose junk, and runs continuously rather than via an on-demand trigger like the Mass Harvester. This tool should be considered experimental, and needs more testing to ensure that it works properly.

DLC 02 patch - Wasteland Workshop:
Introduced; added concrete shipments to the Junk Vacuum.

DLC 03 patch - Far Harbor:
Updated Mass Harvester compatibility patch slightly, now complies with new naming and global variable schemes.
Introduced compatibility for junk with the new Junk Vacuum.

DLC 04 patch - Contraptions Workshop:
Introduced; added "Steel Ball" to the Junk Vacuum.

*****Version 0.2.2 (2016-06-30)*****
Generalized "flora" harvesting to "harvestables" instead, consisting of flora and misc items, the latter now including (currently only) mirelurk eggs.
Default behavior is to harvest misc items at the same times as flora, but flora and misc processing can be independently enabled/disabled from the holotape.

*****Version 0.2.1 (2016-06-30)*****
Fixed script bug that was preventing the new flora from being properly added to the base mod's FormList.

*****Version 0.2.0 (2016-06-30)*****
Introduced experimental support for corpse harvesting as well, and added more configuration options to the harvester's configuration holotape.

*****Version 0.1.1 (2016-06-28)*****
Corrected script bug that prevented the user from receiving any of the harvested items.

*****Version 0.1.0 (2016-06-27)*****
Initial release.