===================================================================================================
Save and Load Cells: Jaxonz Extension
AUTHOR: Lord Zapharos (www.lordzapharos.com)
DATE: 19 September 2021
VERSION: 1.1
===================================================================================================


LICENSE AND CREDITS:
===================================================================================================
Creative Commons Attribution 4.0 International (https://creativecommons.org/licenses/by/4.0/)

You are free to share and transform this work (commercially or otherwise) provided you give proper
credit to Lord Zapharos, provide a link to this license, and indicate if changes were made.

I claim no copyright or credit whatsoever for the following mod(s):

    Jaxonz Positioner by Ian Patterson, Stephen Abel, Paul Connelly, and Brendan Borthwick
            (http://skse.silverlock.org/)


DESCRIPTION:
===================================================================================================

The setting: you have just finished a beautiful, meticulously decorated player home using Jaxonz
Positioner. Every object is in place, your weapon wall is complete, and you have created a banquet
table fit for jarls. Thanks to Jaxonz, none of these decorations can be disturbed by an accidental
bump or misplaced shout -- because you locked them down first. You give yourself a pat on the back,
congratulating yourself on a job well done...

...and then you realize that this elegant masterpiece is stuck forever in one save file. To bring
these wonders to a new character, you must rebuild them entirely from scratch.

Jaxonz Positioner is unquestionably my favorite and most indispensable Skyrim mod (so much so, in
fact, that I created an equivalent mod in Fallout: New Vegas -- check it out!). But this mod does
have limitations, the most notable of which is that you cannot move your changes between different
save characters, or share your decorations with other people. Jaxonz also tends to get sluggish for
determined decorators (i.e. when you place more than 1000 decorations in a single location).

All of that changes with Save and Load Cells: Jaxonz Extension. This mod allows you to save your
countless hours of work to an external file. You can then load this file into a new game or even
share the file with others, so they bring your decorations into their own game. Home interiors,
exterior gardens, custom dungeons, mod-added weapons -- all can be saved, and all can be loaded!

A summary of the features offered by this mod:

 - Compatible with virtually everything.

 - You can save ANY "cell" i.e. location in your game to a file, then load that file for any other
   character. Every object you placed will be faithfully reproduced, down to the last sweetroll.

 - This tool will save and load objects from ANY mod. If you delete or move vanilla objects with
   Jaxonz Positioner (such as the Breezehome dining table), those changes will be recorded too.

 - The files you save can always be loaded even if you uninstall other mods. This tool will simply
   skip over any objects it does not recognize.

 - Saved files do not care about your load order (shuffling mods around won't break anything).

 - You can easily share the files you create with other people. Files are stored in plain text and
   can be manually edited if needed (all you need is a text editor and TES5Edit; see guide below).

 - This mod fixes several issues with Jaxonz Positioner: there is no longer any slowdown when you
   place "too many" objects and a major cause of save bloat has been eliminated.

Unlike Jaxonz's GameToMod, this mod doesn't require TES5Edit to use and there is no need to worry
about load order or which mods you have previously installed. A complete usage guide is provided in
the below sections; however, in most cases it really is as simple as clicking "Save" and "Load"!


REQUIREMENTS:
===================================================================================================

Skyrim Legendary Edition
SKSE 1.7.3
SkyUI 5.1
PapyrusUtil 3.3 (i.e. StorageUtil)
Lord Zapharos IO Utilities
Lord Zapharos String Utilities
Jaxonz Positioner 2.92


CHANGE LOG:
===================================================================================================

1.1     Added legacy object selection toggle

1.0     Initial release


UPDATE INSTRUCTIONS (v1.1 from v1.0):
===================================================================================================

Follow the regular installation instructions below, overwriting all files.


INSTALLATION:
===================================================================================================

1. Copy both the "Data" and "saveAndLoadCellsJaxonzExtension" folders from this directory to your
   main Skyrim directory (usually found in "C:\Program Files (x86)\Steam\steamapps\Skyrim"). You
   should overwrite any existing files if prompted.
2. Activate "SaveAndLoadCellsJaxonzExtension.esp" with your mod manager of choice.
3. If you are starting an entirely new game, make sure to disable legacy object selection (see the
   end of this readme for details).

To uninstall, just remove all added files.

The "saveAndLoadCellsJaxonzExtension" folder contains all saved cell files, so do NOT delete it if
you want to keep your cells around for a future playthrough!


SKYRIM SPECIAL EDITION USERS:
===================================================================================================

This mod was designed in Skyrim Legendary Edition and WILL NOT WORK with Skyrim Special Edition. If
you decide to convert this mod to work in Skyrim Special Edition, I would be happy to bundle your
converted version with this mod and give you due credit -- just send me your conversion.


WARNINGS AND DISCLAIMERS:
===================================================================================================

You must NEVER save or load a cell whilst selecting or manipulating objects in Jaxonz Positioner.
Doing so may break the Jaxonz Positioner mod entirely (or the object that you are moving).

If you load a file containing any quest objects (Auriel's Bow, Black Books, the Golden Claw, etc.)
before you have completed the associated quests, you may BREAK THOSE QUESTS PERMANENTLY. This has
exactly the same consequences as using "player.additem" in the console, so be careful!

This tool will not save or load NPCs (people, creatures, and so on). This is for your protection,
as most NPCs are linked to quests or scripts, which would break if you attempted to spawn them.

Hearthfire homes in particular are divided across multiple cells; you will need to save each cell
separately to get the entire thing. See the usage guide below for more details.

It is normal for objects to appear "out of position" after you load them into a cell, or after you
enter a new cell entirely. These askew objects will fix themselves automatically in a few seconds.

You may need to manually delete a few mannequins and vanilla objects after loading a cell. Objects
you delete with Jaxonz Positioner are eventually, but NOT immediately, removed from your save game,
which is why some previously deleted objects may appear to "linger" behind after loading.

Saving and loading cells can take a VERY LONG TIME, during which you will be unable to do anything.
Heavily-customized Hearthfire homes may take up to 25 minutes to save. You can tab out of the game,
but NEVER CLOSE THE MCM MENU while objects are being loaded and saved!

Why is this process so slow? Skyrim's scripting language (Papyrus) is both poorly optimized and
poorly designed, and is actually SLOWER than its GameBryo predecessors (e.g. Fallout 3, New Vegas).
This mod does everything possible to speed things up (including making use of custom SKSE plugins),
but there is no way to fix Papyrus's fundamental design flaws. Please be patient!


JAXONZ POSITIONER FIXES:
===================================================================================================

After placing a lot of decorations with Jaxonz Positioner, you will observe an increasing delay
between when you select an object and when you are actually able to move it. This delay can reach
upwards of 20 seconds and makes object positioning very tedious.

This mod resolves the issue by replacing a costly script loop with a speedy hash lookup. Object
selection will always be fast for new games. The fix is applied incrementally to existing saves:
when you first select an object it will be slow, but future selections on it will be very fast.

In Hearthfire homes, object-undo markers often became persistent. These invisible markers caused
slow loading times and also bloated your save. This mod removes "Undo Placement" and allows you to
clean affected cells either automatically when saving them, or manually through the MCM.


MY OTHER MODS:
===================================================================================================

Arrows to Ingots
Better Low-Level Illusion
Dragon Souls Experience System
Finders Keepers (Better Stones of Barenziah)
Guild Ranks and Progression
Inigo Avoid All Combat
Lord Zapharos Default Outfit Changer
Lord Zapharos IO Utilities
Lord Zapharos String Utilities
Necromancy is Hated
Spriggans Fear Nettlebane
TDF Equipment Restrictions for Duelists and Assassins
The Legendary Red Eagle
Useful Requiem Beverages
Vilja Avoid All Combat
Wait I Know You Bug Fix
Weapon and Armor Etching
Whispering Fang Unarmed Combat





===================================================================================================
===================================================================================================
========================================== USAGE GUIDE ============================================
===================================================================================================
===================================================================================================


THE BIG PICTURE:
===================================================================================================

To save a cell, you will need to do the following:

    1. Move your player to the correct location.
    2. Open up the Mod Configuration Menu --> Save and Load Cells --> Save Cell.
    3. Click on "Save to File".
    4. Wait!

The procedure to load a cell is very similar:

    1. Move your player to the correct location.
    2. Open up the Mod Configuration Menu --> Save and Load Cells --> Load Cell.
    3. Click on "Load File".
    4. Wait!

The first time you save or load a cell can be a little confusing -- that is what this guide is for!
After you save/load your first few cells, the process will quickly become intuitive and easy, and
you will probably won't need this guide anymore.


WHAT IS A CELL, ANYWAYS?
===================================================================================================

The open world of Skyrim is internally divided into a lot of small squares or cubes called "cells".
Only a small number of these cells are fully loaded in the game at any time. Cells are loaded into
the game as you move closer to them, and older cells are unloaded as you move away from them. This
behavior drives the seamless open world experience -- and also causes the infamous "pop in" effect
when you travel too quickly across the world while on a horse or using "setspeedmult" commands.

In many cases, one "location" (e.g. Breezehome) corresponds exactly to one "cell". However, larger
areas such as dungeons, fortresses, and Hearthfire homes are subdivided into multiple cells.

This mod saves and loads *cells*, not locations. If you want to save a Hearthfire home, you will
actually need to save multiple times: once for the inside, once for the basement, and between 1-3
times for the exterior (depending on the span of your garden or other exterior decorations).

To make saving and loading easier, this mod displays your current cell in the MCM -- see below.


POSITIONING YOURSELF FOR A SAVE OR LOAD:
===================================================================================================

Always start by moving your player to the location you want to save or load:

 - WHEN SAVING A LARGER EXTERIOR AREA, walk around the perimeter of the objects you want to save,
   opening the MCM periodically. To save the entire area, you will need to stand in each cell that
   contains objects you want to save and click "Save to File" for each of these cells.

 - WHEN LOADING A LARGER EXTERIOR AREA, walk around the perimeter of the area you want to load and
   compare the cell names with the files you want to load. To load the entire area, you will need
   to stand in each of the respective cells and click "Load File" exactly once for each one.

 - WHEN SAVING OR LOADING AN INTERIOR AREA, you will need to stand in each "load area" (main hall,
   cellar, etc.) and save or load each of those areas one-at-a-time.

To check your current cell, pause the game and open the Mod Configuration Menu (MCM). Navigate to
"Save and Load Cells" and then select either "Save Cell" or "Load Cell". On the right side of the
menu, you will see text looking something like the following:

        Your current location is:
        016A56_HearthFires.esm

        ^^^^^^ these six characters are the cell's ID number;

               ^^^^^^^^^^^^^^^ and this is the mod where the cell comes from!

This is the current cell where your player is standing, and is also the NAME OF THE FILE that will
be either saved or loaded.

When you move through the game world, you will notice that either the ID number, the mod name, or
both will periodically change -- this means that your player is moving between different cells.

To save or load a larger area or multi-part house, you will need to identify the correct places to
stand, move to each of them, and click "Save to File" or "Load File" once for each of these cells.
The exact location where you stand is not important -- as long as you are standing *somewhere* in
each cell that needs to be saved/loaded, this mod will save or load that entire cell for you.


SAVING CELLS:
===================================================================================================

***NEVER save a cell if you are currently selecting or moving an object with Jaxonz Positioner!***

Now that you are standing in the correct location, open the Mod Configuration Menu, then select
"Save and Load Cells", and finally "Save Cell". Click on "Save to File" and wait until you see a
confirmation message indicating that saving is complete. It is only safe to close the MCM menu
AFTER you see this confirmation message.

If you have already saved this cell beforehand, you will be asked whether you want to overwrite the
current file. If you choose yes, the existing file will be deleted (consider backing it up first!).

While objects are being saved, you must NEVER CLOSE THE CURRENT MENU or navigate to any other MCM
entry. In short: don't touch anything! Just sit back and let this mod do its work.

After completion, you can move on to the next cell you want to save or resume playing the game. All
of your saved cells are located in the "saveAndLoadCellsJaxonzExtension" folder, which is found in
your main Skyrim directory e.g. "C:\Program Files (x86)\Steam\steamapps\Skyrim".


LOADING CELLS:
===================================================================================================

***NEVER load a cell if you are currently selecting or moving an object with Jaxonz Positioner!***

To load a cell, you will follow the same basic procedure as with saving cells: stand in each cell,
open the MCM, go to "Save and Load Cells", click on "Load Cell", and then on "Load File". Wait
until you see a confirmation message indicating that loading is complete.

All files are loaded from "saveAndLoadCellsJaxonzExtension", which is located in your main Skyrim
directory (usually "C:\Program Files (x86)\Steam\steamapps\Skyrim"). Make sure you place your files
here before trying to load them!

After loading is complete, MAKE A FULL SAVE and EXIT/RESTART SKYRIM. You need to do this for each
cell to ensure that placed objects "stay" in the correct place.

The most important rule when loading cells: NEVER LOAD THE SAME CELL TWICE in the same playthrough!

This mod does not "know" if you have previously loaded a cell. When you try to load the same cell
twice, a second copy of EVERY placeable object in the file will be created. The result is an utter
mess, with overlapping duplicate objects that ruin your framerate and are a major pain to remove.

So don't forget: ONLY LOAD A CELL **ONCE** PER PLAYTHROUGH!


REGARDING HEARTHFIRE HOMES AND QUEST OBJECTS:
===================================================================================================

When loading Hearthfire homes, make sure you have built the entire house FIRST (you must also build
the same extensions -- kitchen, library, and so on -- before loading any files). If you load a file
before building all requisite parts yourself, YOU WILL BREAK THE HEARTHFIRE QUEST for that home.
This means that workbenches may no longer function and your steward options may not work correctly.

If you do not build the same extensions -- kitchen, library, etc. -- as are defined in the saved
file, your house will NOT work properly and your game may crash when entering or leaving the area.
It is IMPOSSIBLE to fix these issues after they have occurred, so be careful!

Quest objects in your saved cell can also prove troublesome. Many items such as Auriel's Bow and
the Golden Claw have quest scripts attached to them. When you load a cell, you create new copies of
those items (and new copies of their scripts), which WILL BREAK THE ASSOCIATED QUESTS if you have
not already completed them. It is a good idea to remove these sensitive items from your saved cell
file manually (see instructions below), or to make sure you have completed all the related quests
before loading anything.

In all cases, it is a very good idea to keep MULTIPLE SAVE FILES when loading cells. You can then
revert back to those older saves if anything does go wrong.


RESTRICTING THE TYPES OF OBJECTS THAT ARE SAVED OR LOADED:
===================================================================================================

Sometimes you don't want to actually save or load ALL the objects in a cell. For example, you may
have a trophy room with rare weapons, and you want new characters to earn such trophies themselves.

To deal with this eventuality, this mod allows you to restrict which objects are saved and loaded.
Open up the MCM, go to "Save and Load Cells", and then click on "Advanced Options". The right side
of this menu contains toggle switches for weapons, armor, soul gems, and so on.

If you disable one of these switches, that object type will be ignored when saving cells and will
be skipped when loading cells. The settings you choose here will persist across multiple saves, but
are unique to each character/playthrough.

Some of the provided object types are not actually used in Skyrim, or are only minimally used. The
reason these options are present is for compatibility (i.e. some mods might make use of them).


SHARING DECORATIONS WITH OTHERS:
===================================================================================================

Sharing your decorations and saved objects is easy: grab all of the desired *.txt files from
"saveAndLoadCellsJaxonzExtension" (located in your main Skyrim directory), then send those files to
a friend, put them on your website, or submit them on NexusMods.

To make full use of these files, people will need to have the same mods as you. Their load order
doesn't matter -- but they will need the same mods.

But even if someone doesn't have the same mods, these shared files can still be loaded. This tool
will quietly skip over any mod objects it does not recognize, and the rest of the decorations or
objects will be loaded normally.

Shared files must always be placed in "saveAndLoadCellsJaxonzExtension". DO NOT RENAME CELL FILES
OR THEY WILL NOT LOAD CORRECTLY -- for you or anyone else. When distributing your modifications, it
is a good idea to include a readme explaining which locations are affected and any required mods.


(ADVANCED) EDITING CELL FILES MANUALLY:
===================================================================================================

The files generated by this tool can be modified manually if needed. All you need is a text editor
and a copy of TES5Edit (for looking things up).

To get started, open the "saveAndLoadCellsJaxonzExtension" folder, contained within the main Skyrim
directory e.g. "C:\Program Files (x86)\Steam\steamapps\Skyrim". After you have saved a few cells,
there will be several text files here.

BACK UP the file you want to edit first. Then open it with your text editor.

You will see numerous lines of text. Each of these lines represents a single object in the cell.
For example, the following (truncated for space) line indicates a very fine, custom-placed bottle
of Argonian Bloodwine (in Heljarchen Hall):

        ALCH`46`003535_HearthFires.esm`1`0`0`342.691895`-214.434906`17.588024`0.000000` (...)

Line are broken apart using the "`" symbol. Each time you see a "`", it indicates a new section for
that object. The sections, in order, are:

        1.  A four-letter tag making the object easy to identify ("Book", "ALCH", "Misc", etc).
            This tag should always be the same as what is displayed in TES5Edit.

        2.  A number representation of the aforementioned tag. The possible values are defined in
            SALCJEMainScriptMCM.psc and are reproduced below for your convenience:

                    TYPE_ARMA = 102                 TYPE_ACTIVATOR = 24
                    TYPE_AMMO = 42                  TYPE_ARMOR = 26
                    TYPE_BOOK = 27                  TYPE_CONTAINER = 28
                    TYPE_DEBRIS = 88                TYPE_DOOR = 29
                    TYPE_FLORA = 39                 TYPE_FURNITURE = 40
                    TYPE_GRASS = 37                 TYPE_INGREDIENT = 30
                    TYPE_KEY = 45                   TYPE_LAND = 72
                    TYPE_LIGHT = 31                 TYPE_MISC = 32
                    TYPE_MOVABLESTATIC = 36         TYPE_NOTE = 48
                    TYPE_POTION = 46                TYPE_SCROLLITEM = 23
                    TYPE_SOULGEM = 52               TYPE_STATIC = 34
                    TYPE_STATICCOLLECTION = 35      TYPE_TALKINGACTIVATOR = 25
                    TYPE_TREE = 38                  TYPE_WATER = 84
                    TYPE_WEAPON = 41

        3.  The reference ID or base ID of the object. To see what this object actually is, take
            the first six characters (a hexadecimal code e.g. "003535") and then find the load
            order of the mod immediately after those characters ("HearthFires.esm"; for me, this is
            at position "03" in my load order). Combine them together to get form ID "03003535".
            Type this value into the FormID box in TES5Edit and you will be taken to the object's
            entry: in my case, the base object "BYOHFoodWineBottle04".

                Note: in many cases, you will see a "Placed Object" entry in TES5Edit. This is for
                *reference objects* and it means that the object was placed in a cell by the mod
                itself (e.g. by HearthFires.esm). This affects what you can do with the object.

        4.  A number (0 or 1) indicating whether this is a custom object. Custom objects are always
            given *base IDs*, not reference IDs. If an object is custom, the player manually placed
            that object in this cell or copied an existing object via Jaxonz Positioner. Reference
            objects will always have a zero (0) here.

        5.  Another number (0 or 1) indicating whether this *reference* was deleted. Custom objects
            will always have a zero (0) here. Setting this to 1 will cause the reference to not
            appear in the player's game (i.e. make it invisible). This is akin to what happens when
            you delete e.g. the Breezehome dining table using Jaxonz Positioner.

        6.  A number (0 or 1) indicating whether this *reference* is disabled. Custom objects will
            always have a zero (0) here. Setting this to 1 will cause the reference to be invisible
            in the player's game, but the object can still be re-enabled / made visible later. This
            is akin to how Hearthfire "builds" or "removes" decorations and house extensions.

        7.  A decimal indicating the object's x-coordinate in the cell. Can be negative.

        8.  A decimal indicating the object's y-coordinate in the cell. Can be negative.

        9.  A decimal indicating the object's z-coordinate in the cell. Can be negative.

        10. A decimal indicating the object's x-angle in the cell. Can be negative.

        11. A decimal indicating the object's y-angle in the cell. Can be negative.

        12. A decimal indicating the object's z-angle in the cell. Can be negative.

        13. A decimal indicating the object's scale (1.0 is "normal"; must be greater than 0).

Armed with this knowledge, you can now edit individual lines of the cell file. For example, if you
saved a cell with the Golden Claw and want to remove it, all you need to do is find the base ID or
reference ID of the Claw, search for it in the cell file, and remove that line.

To change the position of an item, simply locate the item's line in the cell file and change its
coordinates.

You can hide "vanilla" game objects by setting their *references* in the cell file to be disabled
or deleted (this is essentially what happens when you delete objects with Jaxonz Positioner).

New lines can also be added. This is usually too tedious to be practical, but can be useful if you
are otherwise unable to select an object with Jaxonz Positioner.

DO NOT LEAVE ANY BLANK SPACES IN THE MODIFIED FILE! Blank lines will prevent the file from loading.
A single blank line at the END of the file is okay, but should occur nowhere else.


(ADVANCED) LEGACY OBJECT SELECTION:
===================================================================================================

Legacy object selection is a feature allowing this mod to be installed and used on existing saves
(i.e. saves in which you have already placed objects using Jaxonz Positioner). When this setting is
enabled, the first selection of any previously placed objects will be "slow". But future selections
on those same objects will be VERY fast.

This feature isn't needed if you intend to start an entirely new game after installing this mod, or
if you haven't placed any objects yet with Jaxonz Positioner in your current save. In fact, leaving
this option enabled in those scenarios will actually *slow down* object selection overall!

To disable this setting, open the Mod Configuration menu and navigate to "Save and Load Cells".
Click on "Advanced Options", and then DISABLE the "Use fallback selection" option. This change will
take effect immediately, but only within your current save.

If you installed this mod mid-playthrough, you should usually leave fallback selection ENABLED.
However, you can temporarily disable this feature when placing entirely new objects (weapons, etc.)
from your inventory. Disabling the feature will speed up selection on these new items. Make sure to
re-enable the setting afterward, though!
