Name: DALCO Junk-O-Matic
Version: 1.2
Date: 27 April 2014
Category: Cheats and God Items
Requirements: Fallout 3 with ALL DLCs, FOSE ( http://fose.silverlock.org/ ), and some means to unzip the files (7-Zip)
Author: DaveLessnau
Location: http://www.nexusmods.com/fallout3/mods/17176/?

Description
===========
Tired of wading through all the junk strewn throughout the Wasteland while trying to find or do more important things? This mod fixes that. It grabs all the pure junk in each area you're in and stores it in a box in either the player's Megaton House or Tenpenny Suite. Requires FO3 with all DLCs, and FOSE.

Location
========
When you make your choice of what to do with the Megaton bomb and get the resulting house, you'll see a quest complete message for "Clean up the World" and you'll get the DALCO Junk-O-Matic Device under the Apparel tab of your Pip-Boy. Merely equip the Device to start removing junk from the world or unequip it to stop. If you have the Megaton House, the Device will transfer all junk to the DALCO Junk-O-Matic Box in the front-left corner of the room (between the locker and where the Workbench will be). If you have the Tenpenny Suite, the Box will be in the front-right corner of the room (I've never entered that room via the doors so I'm not sure if it's front-right or rear-left -- but it will be next to where the Workbench will be).

Details
=======
When the Device is equipped, it scans through the entire area that the player is in and looks for junk (items that, to the best of my knowledge, aren't used anywhere in the base game or the DLCs). For each piece (or stack) of true junk that it finds, the Device removes it from the area and adds the proper number to the Box in the player's house. This should happen fast enough that it should never interfere with game play. What you do with the collected junk is up to you. You can ignore it. You can pull it out of the Box and sell it. You can run it through Wadsworth or Godfrey for recycling if you have my "Wadsworth the Recycler" mod loaded ( http://www.nexusmods.com/fallout3/mods/17146/? )

Notes:
- The Device uses the Choker slot as an attachment point. AFAIK, that slot is rarely used. So, the Device should be usable in almost all cases.
- If you ever drop or otherwise notice the DALCO Junk-O-Matic Device to be missing from your inventory, you can get it back via the console (~) with one of the following commands:
-- If you're using the Megaton House: "Player.AddItem xx003603 1" (no quotes, and xx is the load order of this mod in your setup)
-- If you're using the Tenpenny Suite: "Player.AddItem xx007CD5 1" (no quotes, and xx is the load order of this mod in your setup)
- The Device only transfers junk from the environment. The junk in your inventory, or any junk you manually add to your inventory, will remain untouched.
- Because the Device grabs all the junk in the cell, you won't see the cute little dioramas (built mostly of MISC items) that are strewn throughout the game. Because of this, you should probably use this mod only after your first run-through.
- The point of this mod is to clean the utter junk out of the area so that you know that whatever you see is of some use somewhere. Thus, be design, it does not pick up normal Tin Cans. Unlike Bent Tin Cans (not used anywhere), regular Tin Cans are use as Components and as ammunition for the Rock-It-Launcher. However, if you want to change the mod's behavior to pick up regular Tin Cans (or anything else), it can be done:
-- Open up FO3Edit ( http://www.nexusmods.com/fallout3/mods/637/? ), right-click on the panel of mods it shows you and Select None. Then select just this mod: DALCO Junk-O-Matic.esp
-- When it finishes loading, expand this mod's entry and its FormID List category
-- Select the DALJunkItemsList and look in the right panel for the label "FormIDs" with a blank line next to it. Right-click on that blank line and select Add
-- You should now see a NULL entry in the Form List. Right-click on that NULL entry and select EDIT
-- Enter whatever you want to be automatically picked up in the format provided. For the regular tin can, that should be "tincan02 "Tin can" [MISC:00022104]"
-- When you're done, press CTRL-S or exit FO3Edit. It will ask you where you want to save. Make sure you've checked the box for DALCO Junk-O-Matic.esp and the Backup mods box at the bottom.

Install
=======
Either manually download the mod or tell Nexus Mod Manager to download it. If you manually download it and want to manually install it, just unzip it and put the "DALCO Junk-O-Matic.esp" file in your game's DATA folder. If you want NMM to install it, go to NMM's Mod tab and select the top, Add Mod from File icon, and point it to where you downloaded the mod's .7z file. If you had NMM download the mod, it should shortly show up under NMM's Mod tab. In either NMM case, click the 2nd NMM icon to Activate the mod. Then, go back to the Plugins tab and make sure the .esp file is checked. It can go anywhere in your load order without fear of conflict.

Uninstall
=========
To uninstall using NMM, go to it's Mod tab, highlight the mod, and select the 2nd icon to Deactivate it. You can delete it if you want.

To uninstall manually, just delete it from your games DATA folder.

Upgrade
=======
1. Uninstall the old mod.
2. Install the new mod.
3. Start Fallout 3 and play. There is no effect on saved games and cannot corrupt any saves.

Incompatibility
===============
- I've marked both the player's Megaton House and Tenpenny Suite as owned by the player in an effort to minimize loops with the Box. Mods that change the player's house might leave the areas marked with the default lack of ownership. If this happens, and the mod that changes the ownership of the player's house is loaded after this mod, you will see a set of junk items (they differ, depending on what themes/upgrades you've bought for the house) appear in the box every 5 seconds. If you see this, open FO3Edit with all your mods selected, expand this mod, look at Cell, Block 9, and then both Sub-Block 3 and Sub-Block 9 for the two houses. See what other mod has changed the ownership of the houses and move this mod after it in the load order.

- Also, anything that adds something to the corners of the rooms where I've added the Boxes might cause them to disappear from view (though they will probably still work).

- Note: if you have mods loaded that use some of the items I classify as junk (maybe for crafting or repairing, for example), be aware that you won't be able to grab those items from the environment for your own use unless you un-equip the Device before entering the area (or travel to the Box and recover the items from it). If you want, you could use FO3Edit to remove those items from the DALJunkItemsList Form List.

Known Issues or Bugs
====================
None.

History
=======
- 1.2, 27 April 2014: Made the slave collar used as the DALCO Junk-O-Matic Device invisible by deleting its Model Names. Removed the items used to let various Protectron's know you're friendly (OfficeID, PassCardBlue, and PassCardRed) from the list of junk items.
- 1.1, 21 December 2013: The mod did not display its warning message if FOSE was not found. Corrected.
- 1.0.1, 31 Dec 2011: Removed the MarkForDelete lines in the mod for the sake of compatibility with other mods that might need those pieces of junk.
- 1.0, 31 Dec 2011: Fixed the "occasional crash" problem on entering heavily junkified areas after a lot of play.
- 0.5, 30 Dec 2011:
-- Fixed the crashing problem when processing stacks of items near the player's house.
-- Now processes stacks of junk items.
-- Now leaves junk items that players manually add to their inventory alone.
- 0.4, 28 Dec 2011: Initial public release.

Programming Notes
=================
- Regarding the mod's "hardware:"

-- For storing the items picked up by this mod, I edited the stock MetalBox01Library to give it a new EditorID of DALCOJunkOMaticBox and saved it. I re-opened it, gave it the name "DALCO Junk-O-Matic Box," emptied it of all items, made sure it didn't respawn, and set the ownership to Player (which didn't stick). After saving that, I dragged it into both of the player's homes (MegatonPlayerHouse and TenPenny03Player). There, I named them DALCOMiscItemsBox and DALCOMiscItemsBox2, respectively, and again set the ownership to Player. DALCOMiscItemsBox in the player's Megaton House is where the DALCOJunkOMaticDeviceScript puts things and DALCOMiscItemsBox2 is where the DALCOJunkOMaticDeviceScript2 puts things.

-- For the Device the player wears to cause the processing, I used the Slave Collar in Armor | Headgear (because it attaches to the player via the Choker slot and I assumed this would work with the most armor and stuff (NoseRing is used by the Invisible Ghoul Mask mod (http://www.fallout3nexus.com/downloads/file.php?id=8724) and I use that all the time)). I gave it a new EditorID of DALCOJunkOMaticDevice and saved it. I re-opened it, gave it the name "UTIL: DALCO Junk-O-Matic Device" and set it to Playable. I then attached my DALCOJunkOMaticDeviceScript to it. After saving it, I did the same thing to it to produce the Tenpenny Suite version (with DALCOJunkOMaticDevice2 and DALCOJunkOMaticDeviceScript2 for EditorID and script).

-- In an effort to keep infinite loops from happening in the player's home, I modified those cells (MegatonPlayerHouse and TenPenny03Player) so their ownership is Player on their Interior Data tabs.

- Since the mod requires FOSE, I set up a message (DALCOJOMFoseWarningMessage) that the scripts will display if they try to run without it.

- I used a Form List (DALJunkItemsList) to store the list of junk items that this mod removes from the cells and stores in the Box. These are the items on that list: Ashtray, Baseball01, BaseballGlove, Basketball, BigPot, BoardCutting, BodyPart01, BodyPart02, BodyPart03, BodyPart04, BodyPart05, BowlDog, BoxDetergent, BurnedBook01, BurnedBook02, BurnedBook03, BurnedBook04, BurnedBook05, BurnedBook06, BurnedBook07, BurnedBook08, Chessboard, Cigarette01, CigaretteCarton, CigarettePack, Clipboard01, Clipboard02, Clipboard03, Clipboard04, CoffeeKettle, CoffeeMug01, DinnerPlate01, DLC04FishingPole, DLC05AlienAppliance, DLC05AlienContraption, DLC05AlienCrystal, DLC05AlienCrystalLarge, DLC05AlienCrystalSmall, DLC05AlienDevice, DLC05AlienDoodad, DLC05AlienGemstone, DLC05AlienGemstoneLarge, DLC05AlienGemstoneSmall, DLC05AlienGizmo, DLC05AlienImager, DLC05AlienMaterial, DLC05AlienMechanism, DLC05AlienThingamabon, DLC05AlienTool, DLC05ButtercupToy, DLC05Widget, DrinkingGlass01, DrinkingGlass02, Fork01, GardenGnome01, GardenGnomeDestroyed01, GlassPitcher01, GnomeGarden, Hammer01, Harmonica01, HotPlate, Iron, JournalGeneric, Knife01, Knife02, MedicalBraceNew, Milkbottle01, MS02AntResin, NukaColaBottle, NukaTruck, Opthalmoscope, PanCookingMetal, Paperweight, Pencil01, Plate01, Plate02, Plate03, Plate04, PlateDinnerCeramic, Plunger, Pool10ball, Pool13ball, Pool2ball, Pool5ball, Pool8ball, PoolBall, Poolcueball, PoolTriangle, PotCookingMetal, PreWarBook, PrewarMoney, Rake, ShotGlass01, SkullBrahmin, SodaBottleEmpty01, Spatula01, Spoon01, SpoonBig01, Spork01, SurgicalBonesaw01, SurgicalForceps01, SurgicalScalpel01, SurgicalScissors01, SurgicalSyringe01, SurgicalTweasers01, TinCan02, ToasterPostwar, ToasterPrewar, WhetStone01, WhiskeyBottle01EmptyOl, WhiskeyBottle02, WoodChipper, Wrench01.

- Each Device has an Object script attached to it to do the processing (DALCOJunkOMaticDeviceScript and DALCOJunkOMaticDeviceScript2). The only difference between these scripts is the one line that tells the Device which box to store the junk items in. Using GetFOSEVersion, these scripts check for FOSE. If present, they use GetSecondsPassed to run every 5 seconds. They then "ref walk" through all the MISC items in the cell by using GetFirstRef and GetNextRef. For each such item, they use GetDisabled to only process items not disabled, IsInMyOwnedCell to avoid conflicts with house themes/upgrades, and GetOwner to process only those items the player does NOT own (in an attempt to avoid infinte looping between the Device and the Box). Using IsInList against DALJunkItemsList, they make sure the items are truly junk. If so, they use GetRefCount to store the number of items in the stack, SetOwnership to make the player the owner, GetBaseObject to store a copy of the base object for later use, and then Disable to remove the item from the cell. They then use AddItem to add the proper amount of the item to the appropriate Box.

- And, finally, to initiate the mod, I set up a script. In the GECK, I went to Actor Data | Quest and right-clicked to get a new quest. I gave it the name "Clean up the World" and ID "DALCOJunkOMaticQuest" and then saved it. I re-opened it, and checked the Start Game Enabled box and the Script Processing Delay (default) box. Under the Quest Stages tab, I set up two EMPTY stages (10 and 20). On stage 20, I checked the Complete Quest box. I then went back to the Quest Data tab and attached the DALCOJunkOMaticGiveScript (Quest Script) to it. This script merely uses GetStageDone for quest MS11 stages 210 and 60 (getting the Megaton House or Tenpenny Suite, respectively) to give the player the correct Device and then advance to the Complete Quest stage (20).

For version 1.1, I had to add the following (see DALCO FOSE Check ( http://www.nexusmods.com/fallout3/mods/19970/? ) for information on how):

- DALCOJOMGameRestartedGlobal: a new global variable of type Short, with a default value of 0, and checked the Constant box. No matter how the variable is changed during a game session, when the game next restarts, the variable will be reset to it's default value.

- DALCOJOMFoseCheckScript: a Quest Script attached to DALCOJOMFoseCheckQuest. It declares a variable to hold the status of whether FOSE is on or off. If FOSE is absent, it displays a warning via DALCOJOMFoseWarningMessage. It only does the work once per game session because it checks (and sets) the global constant variable.

- DALCOJOMFoseCheckQuest: a quest used merely to hold run it's quest script (DALCOJOMFoseCheckScript) at game start and the one quest stage whose result script isolates the GetFOSEVersion from the rest of the processing (it will fail if FOSE is not present).

Credits
=======
- A big thanks goes to Cipscis. His explanations from all over the web have pulled my bacon out of the fire repeatedly. Without his work, I'd never have been able to decipher the GECK documentation.
- Thanks to RickerHK for his suggestions in http://forums.bethsoft.com/topic/1325938-refwalk-on-misc-items-crashing-game/ .
- Thanks to Bethesda for creating Fallout 3.
- Thanks to Fallout3Nexus for the one-stop-shop resource for authors and players.

Tools Used
==========
- Notepad++: http://notepad-plus-plus.org/ (I did all my script editing in this)
- Cipscis' Script Validator: http://cipscis.com/fallout/utilities/validator.aspx (this is where I checked that my script didn't have obvious syntactic issues)
- Cipscis' Fallout 3 Script Syntax Highlighter for Notepad++: http://www.fallout3nexus.com/downloads/file.php?id=10322 (I added this to Notepad++ and it makes scripting quite a bit easier)
- Garden of Eden Creation Kit (The GECK): http://geck.bethsoft.com/index.php/Main_Page)
- Fallout 3 Edit (FO3Edit): http://www.nexusmods.com/fallout3/mods/637/?
- Nexus Mod Manager (NMM): http://www.nexusmods.com/fallout3/mods/modmanager/

Licensing/Legal
===============
Feel free to use this mod and modify it as you need. But, cite me as the originator.