OBLIVION
Clean up by kuertee
Oblivion » Utilities
Added: 23/05/2009 - 03:58PM
Updated: 23/12/2010 - 02:18PM

620 Endorsements

0.56 Latest version

9,618 Unique D/Ls

15,596 Total D/Ls

65,239 Total Views

Uploaded by kuertee

Description

Last updated at 14:18, 23 Dec 2010 Uploaded at 15:58, 23 May 2009

Name: Clean-up
Version: 0.56
Date: 15 December 2010
Category: Miscellaneous
Requirements:
Oblivion Patch 1.2.0.214,
Oblivion Script Extender (OBSE): http://obse.silverlock.org/
Author(s): kuertee
Source: http://www.tesnexus.com/downloads/file.php?id=24606

Changes since last update, 0.55:
================================
0.56, 15 December 2010:
Bug-fix: The count for the number of items cleaned was never used.
So it always reported 0.
This is now fixed.
The cleaning process, however, always worked.

===========
Description
===========
Prevents saved-game file-size bloating by cleaning the game of actor and item references that are no longer required.
(e.g. inactive references created from dropped items that were picked-up by the player.)

Cleans long-dead actors that may have been corrupted somehow.

=======
Details
=======
The cleaning process used is the game's inherent behaviour of removing items that no longer has any "links" to the game world.

Normally, dead actors and "dynamically created" items that were not picked up by the player will be removed from the world, when the cell they are in resets.
(Dynamic items are those created at game-time as opposed to those created in the Construction Set.
Examples of these items are: those created by PlaceAtMe, those dropped by the Player, those dropped by dying NPCs: e.g. shields, etc.)

However, there are cases when these actors and dynamically created items will (for some reason or another) stay in the game world forever.
And actors not cleaned up by the game properly will never respawn, causing a "broken" game experience.
Saved-game bloat is the result of these.
And saved-game bloating may be the cause of some game crashes.

======================================
Examples of causes of saved-game bloat
======================================
These are some causes of "corrupt" actors and "dynamically created" items:
1. Corrupted actor-spawns.
Sometimes dead actors retain a "link" to the game world preventing the game from removing their entities from the game world.
Their spawn entity is therefore not reused to create a new actor.
Ultimately, this will decrease the game world's population.
How these occur is still a mystery.
In my game, undead and some goblins were forever dead.
It reached a point where I no longer encountered skeletons nor zombies in the wild.

2. Items dropped by the player.
These items will forever stay in the game world.
These are not corrupt entities per se, but some if not most may be categorised as "clutter" and are no longer required by the player.
E.g.: dropped ingredients or food, dropped useless clothing, clutter no longer required.

====================
The cleaning process
====================
The mod runs in the background.
It scours the player's immediate area for dead actors and dynamically-created items.

Any dead actors evaluated as being "no longer required" will be disabled (i.e. actorRef.Disable).
The disabled actor will be removed from the game world the next time the cell is reset.

Any items evaluated as being "clutter" and ignored by the player (i.e. not picked up) will be picked-up by a "special" cleaner NPC (i.e. itemRef.Activate cleanerRef, 1).
Any item picked-up by the cleaner NPC will be removed from the game world immediately (i.e. cleanerRef.RemoveItem itemRef itemCount).

So that the mod doesn't remove actors and items that may actually be required by the game, each actor and item found will first be evaluated before being cleaned.

============================
Dead actor filtering process
============================
Actors that are any of the below will NOT be disabled:
1. IsEssential
2. GetTimeDead < IHoursToRespawnCell or for those that play with "DS Less Predictable Respawn.esp", GetTimeDead < DSLPR.TimerMax
3. has in their possession a quest item

Remember that normally, actors will be removed by the game when the cell they are in is reset.
Only actors that were corrupted will never be removed by game.
This mod readies these corrupt actors for cleaning by "disabling" them.

==============================
Dynamic item filtering summary
==============================
Items that were in the vicinity of the player but were ignored (not in the vicinity of the player anymore) will be cleaned up by the cleaner NPC.

Items dropped by the player will not be cleaned up by the cleaner NPC immediately.
However, if the player doesn't pick them up the next time the player is within a certain distance from them, they may be detemined as being ignored and therefore may be cleaned-up.

The process of filtering out these items is explained in the section "Dynamic item filtering process" below.

====================
Restoring lost items
====================
This requires Pluggy or ConScribe.
1. Install Pluggy or ConScribe.
2. Ensure that the the mod logs items that are cleaned-up:
If using Pluggy, ensure that pluggyDebug is set to 1 in the INI file.
If using ConScribe, ensure that debug is set to 1 in the INI file.
3. After a game session, check the logs for items that were cleaned-up:
Logs from pluggy are located in /Pluggy/User Files/kuerteeCleanUp.txt.
In Vista, is located in the folder: Documents/My Games/Oblivion/.
It may be located elsewhere in other versions of Windows.

Logs from ConScribe are located in the folder: /ConScribe Logs/.
4. Items removed from the game are logged like this:
08/09/2009 00:25:43 removing Shadowhunt 00034899 at 0
to restore:
Set kCURestoreItemsQuest.itemRef[X] To GetFormFromMod "Oblivion.esm" "00034899"
Set kCURestoreItemsQuest.quantity[X] to 1

5. To restore an item to the player, copy its restore lines from the log:
Set kCURestoreItemsQuest.itemRef[X] To GetFormFromMod "Oblivion.esm" "00034899"
Set kCURestoreItemsQuest.quantity[X] to 1

6. Paste them into the /Data/Ini/kuerteeCleanUpRestoreItems.ini and replace "[X]" with a number from 1 to 10:
Set kCURestoreItemsQuest.itemRef1 To GetFormFromMod "Oblivion.esm" "00034899"
Set kCURestoreItemsQuest.quantity1 to 1

Set kCURestoreItemsQuest.itemRef2 To GetFormFromMod "ZumbsLockpickingMod - OBSE.esp" "470015AB"
Set kCURestoreItemsQuest.quantity2 to 1
7. Only 10 types of items (but any quantity of each item) can be restored at one time.
8. In the game, click on "Restore items listed in Data\ini\kuerteeCleanUpRestoreItems.ini" from the "Clean-up console".
By default, the key to open the "Clean-up console" is the minus (-) key.
9. Items are restored into the player's inventory.

==============================
Dynamic item filtering process
==============================
NOTE: that the game will regularly clean items when the cell they are located in is reset.
This clean-up process is only for those that have the potential to stay in the game world forever.
But because this clean-up process can easily be applied to items that will normally be cleaned-up, it is applied to them as well.

This filtering process is a little bit more involved.
This is because items have no such timers like actors have (i.e. GetTimeDead).
The items cleaned-up by the cleaner NPC are those that the player has ignored.
Ignored items are those that the player actively ignored (seen by the side of the road but not picked), not found (shot arrow embedded in a tree), or dropped as clutter.

However, there are some items that will NEVER be cleaned-up:
1. IsQuestItem
2. IsScripted
3. IsArmor if removeArmor is 0 in the INI file
4. IsClothing if removeClothing is 0 in the INI file
5. IsSoulGem if removeSoulGem is 0 in the INI file
6. IsWeapon if removeWeapon is 0 in the INI file
7. GetParentCellOwner == Player

Determining ignored items follows this procedure:
1. the references of up to 20 items within the players vicinity (ignoreDistance in the INI) are saved in the "possibly ignored" list
2. any item within the ignoreDistance from the player but were not saved (because there were already 20 items saved) will not be cleaned up in this time.
they may be cleaned-up the next time the player is in the same area.
3. any of the 20 items that the player moved ignoreDistance away from, will be picked-up by the cleaner NPC (i.e. itemRef.Activate cleanerRef, 1)
4. any items that the cleaner NPC picked-up will be removed from the game immediately (i.e. cleanerRef.removeItem itemRef itemCount)

That's it! To summarise (this is Summary point 1):
Items that were in the vicinity of the player but were ignored (not in the vicinity of the player anymore) will be cleaned up by the cleaner NPC.

However, there are times when the player needs to drop an item they may need/want to return to.
This is the procedure used to keep those items from being cleaned up.
1. when the player's encumbrance is lessened, it is assumed that items were dropped from their inventory
2. any items up to 20 that are found within the set dropped distance from the player (keepDistance in the INI) are saved in a "possibly to be returned to" list
3. any items in this "possibly to be returned to" list will never be saved in the "possibly ignored" list and so will never be cleaned up by the cleaner NPC
4. but when the player next approaches within keepDistance of any items in the "possibly to be returned to" list, they are removed from that list
5. items removed from the "possibly to be returned to" list will be put in the "possibly ignored" list and will be cleaned up by the cleaner NPC if the player ignores them (i.e doesn't pick them up)

To summarise (this is Summary point 2):
Items dropped by the player will not be cleaned up by the cleaner NPC immediately.
However, if the player doesn't pick them up the next time they are within keepDistance from them, they may be detemined as being ignored and may be cleaned-up.

BUT because there is a limit (20) to the number of items that can be kept in the "possibly to be returned to" list, there is a need to clear the list for new items.
Items that are in the list that are more than ignoreDistance away from the player will be removed from the list.
But note that items removed from this list will not be cleaned-up immediately.
They will be put to the same process as any other item that gets within the ignoreDistance from the player.
They will be cleaned up the next time they are determined to have been ignored by the player: Summary point 1.
So, the player may return to items that were dropped a very long time previously.
Only when the player ignores them on their return will they be cleaned up.

To summarise (this is the same as Summary point 2):
Items dropped by the player will not be cleaned up by the cleaner NPC immediately.
However, if the player doesn't pick them up the next time they are within keepDistance from them, they will be detemined as being ignored and may be cleaned-up.

==========
Conclusion
==========
The mod has two functions:
1. removing corrupt actor-spawns from the game world so that the game can respawn them
2. actively removing clutter and ignored items that can stay in the game world forever

======
Result
======
Fixed corrupt actor-spawns.

A relatively more efficient saved-game file-size.
There will be a time when file-sizes will fluctuate between a very small range.
And file-size reduction will occure more frequently - rather than over 10 or more game files when the cells have been reset.

============
OBMM Install
============
1. Add the archive into a newly created OMOD.
2. Activate the OMOD.

=======
Install
=======
1. Extract the files to a temporary location.
2. Examine the folder structure and make corrections where necessary.
3. Copy files to (install folder)\Oblivion\Data\
4. Start Oblivion Launcher, click 'Data Files', place a checkmark beside the kuerteeGameCleaner.esp file.

==============
OBMM Uninstall
==============
1. Deactivate the OMOD.
2. Delete the OMOD.

=========
Uninstall
=========
1. Start Oblivion Launcher, click Data Files, uncheck the kuerteeGameCleaner.esp file(s).
2. Delete the .esp, .ini and .txt file(s) associated with the mod.

===============
Incompatibility
===============
None.

====================
Known Issues or Bugs
====================
Sometimes, manually dropped items in the "possibly to be returned to" list may get cleaned-up before the player gets a chance to return to them.
Best to drop items you want to keep in "safe areas".

=======
History
=======
0.55, 3 November 2009:
Bug-fix: Superfluous non-item (and unplayable) references that cannot be picked-up were getting detected by the mod as items that need to be cleaned.
Thanks, scruggsy! http://www.bethsoft.com/bgsforums/index.php?showtopic=1028563&view=findpost&p=15198736

0.54, 3 October 2009:
Bug-fix: Previously, long-dead actors would not be cleaned up because the unplayable tokens added by mods were detected as quest items.
Note that Long-dead actors that have usable quest items in their inventory are never cleaned-up.
This version checks whether those tokens are usable by the player.
Long-dead actors found without playable Quest tokens are now cleaned-up.
0.53, 8 September 2009:
New feature: See the section "Restoring lost items".
This requires Pluggy or ConScribe.
Search for these OBSE plug-ins in TESNexus.
Bug-fixes: All the major features in previous versions were either broken or only worked partly.
Here are the fixes:
Bug-fix: Player-owned cells are now correctly detected.
Bug-fix: "Safe markers" are now not lost when the cell they are in is reset.
Bug-fix: Items dropped by the player are now correctly remembered and are now only removed if the player returns to their vicinity but ignores them.
0.52, 27 June 2009:
New feature: "Safe marker". Items within the "ignore distance (by default 5000)" from these "safe markers" will not be cleaned-up by this mod.
Note that some of the ignored items may still be cleaned-up by the game when the cell containing them is reset.
New feature: Clean-up console. This is used to drop "safe markers" to mark areas safe from cleaning.
Open this console by tapping the minus (-) key.
Note that because the mod only runs 1 per second, you may need to hold down then release the key.
New feature: Statistics. Counters of the number of actors disabled and the number of items removed.
This is displayed in the Clean-up console.
New feature: "Safe area" notifications. Notifications when you move in and out of these "safe areas".
These messages are toggled on and off in the Clean-up console.
Bug report: Sometimes, manually dropped items in the "possibly to be returned to" list may get cleaned-up before the player gets a chance to return to them.
Best to drop items you want to keep in "safe areas".
0.51, 30 May 2009:
Bug-fix: 20-item cleaning limit removed.
This limit was caused by items detected to be clutter but are not pickable by the cleaner NPC.
this was fixed by clearing the variables after 10 loops of the script.
0.50, 22 May 2009: Initial release.

=======
Contact
=======
kuertee in http://www.bethsoft.com/bgsforums/

=======
Credits
=======
kuertee in http://www.bethsoft.com/bgsforums/
thanks to thes guys: Vagrant0, DragoonWraith, Jibak, shadeMe, Wrye, QQuix, JDFan who have contributed their experiences and ideas to this mod as detailed in this discussion: http://www.bethsoft.com/bgsforums/index.php?showtopic=966829

==========
Tools Used
==========
Oblivion Script Extender (OBSE) - http://obse.silverlock.org/
TES4Edit - http://www.tesnexus.com/downloads/file.php?id=11536
TES Construction Set - http://www.tesnexus.com/downloads/file.php?id=11367
Readme Generator - http://lhammonds.game-host.org/obmm/tools_readme_generator1.asp

Licensing/Legal
===============
You can do whatever you want with this mod but all I ask in return is that
you give me credit if you distribute any part of this mod. I would also like
to know what mods are including my work.