PREFACE
-------

This README assumes you have some knowledge of PowerShell scripts. At a minimum that you have changed the execution policy to allow running unsigned scripts. If you are on Windows 7 this is a pre-requisite. On Windows 8.x and Windows 10 they will assist you in doing so when trying to run in the One click mode.

DISABLING THE PREVENTION OF RUNNING UNSIGNED SCRIPTS IS DANGEROUS. DO SO AT YOUR OWN RISK.

To disable for all scripts globally, open PowerShell with administrative rights and use the command:
Set-ExecutionPolicy -ExecutionPolicy Bypass
You will get a warning that should not be ignored. PowerShell is very powerful and can be abused by malware if you're not careful.

An alternative is to use a batch file or change the Run with Powershell context menu entry for Windows 7. To change the context menu entry you will need to use REGEDIT and modify the key at HKEY_CLASSES_ROOT\Microsoft.PowerShellScript.1\Shell\0\Command and change the (Default) value to
"C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" "-Command" "if((Get-ExecutionPolicy ) -ne 'AllSigned') { Set-ExecutionPolicy -Scope Process Bypass }; & '%1'"


TABLE OF CONTENTS
-----------------

1.0 What this script is and what it isn't.
- 1.1. What does it do?
- 1.2. How does it work?
- 1.3. What it doesn't do.
2.0 How to use the script.
- 2.1. Defaults basic setup.
+-- 2.1a. Default variable explanation.
- 2.2. One click mode.
- 2.3. Advanced command line options.

1.0 What this script is and what it isn't.
-----------------------------------------

1.1. What does it do?

This script is designed to enhance the ability for a mod developer to easily batch pack their mod.

The original conception was to use a staging location and target the script to that path and have it make the appropriate archive that can then be distributed. It has been further developed to allow for multiple game modes (Skyrim, Skyrim SE, and Fallout 4 currently) as well as script definable and command line specified settings.

1.2. How does it work?

You can simply edit the script file and change the default parameters in the header and run it. It will then generate a packing list of files and then call the archiver tool for the game you have specified. Thus creating the destination BSA/BA2 as defined in the script defaults.

The other option is targeting more for the advanced developer who has a use and need for batch scripting. You can use the same script and call with command line arguments to specify: the game type, output path, output bsa file, exclusion filename list, exclusive mod mode, mod data folder (anywhere you want it to be), compression flag for main and/or texture file, option to split textures to separate file.

1.3. What it doesn't do.

This script is not smart. It assumes you properly set the default user definable variables to match your system setup, or you pass the proper arguments. There is a little sanity checking but you *can* screw things up.

It will not validate the texture files that are in the texture folder in any way. When packing to separate texture archives if any invalid files are there it will produce an error. You can use the file exclusion variable to help deal with that if they are of certain types, such as Thumbs.db, or alternate versions like *.tga.

It does not handle conversion to XBox compatible formats. You should use the CreationKit archive menu option to do that. It has a multitude of different things that are done to handle XBox specific changes.

2.0. How to use the script.
---------------------------

There are two modes the script is designed to be run in.

The first is what I call "One click mode" where you would normally edit the script to suit a single mod. You set the defaults for that one specific mod and save it. Then using the right-click context menu in Windows you choose run and it always packages that one mod. This is most useful if you have a separate staging area away from the game data folder where all your mod files are stored. Then you just make copies of the script and edit for each mod you might work on. Keeping that customized file for each mod in their own folder.

The second option is the more versatile and robust command line version. You can skip the initial default configuration entirely if you wish. You are expected to then specify every applicable parameter on the command line when you run the script file.

2.1. Defaults basic setup.

The script as distributed has very basic defaults that frankly should never be used as is. If you plan to use command line arguments exclusively you can skip to section 2.3 for details on how to use it in that mode and skip the defaults configuration. Though for an explanation of what values are valid for the command line arguments you should read the next section.

The user should first open the script for editing. You can use whatever file editor of your choice, be it Notepad, the PowerShell ISE, or something else.

Once the file is opened up for editing you'll need to find the user definable defaults section. It will be very near the top. This is done intentionally to make it as easy as possible for non experienced users. Within that section you will find the following variables available for modification. Not all are necessary to change. In fact some users may find they only change the first 2 being the default game mode and output base name.

2.1a. Default variable explanation.

$sDefaultGameMode
-----------------
Default game mode used if none is provided on the command line.
Valid options are currently: SK, SSE, FO4

$sOutputBSABaseFilename
-----------------------
This is the base of the filename used for output of the BSA file. It should match your plugin name. It is also used for smart matching if using eclusive mod mode.
Example: If you have MyMod.esp use "MyMod" for the base name.
The final filename outputs will follow this style:
MyMod.bsa (Skyrim/SkyrimSE)
MyMod - Textures.bsa (SkyrimSE if chosen to split textures)
MyMod - Main.ba2 (Fallout 4)
MyMod - Textures.ba2 (Fallout 4 if chosen to split textures)

$sModDataDirectory
------------------
The path to the mod data directory. It must be an absolute full drive and folder path. It Can be the game data folder, or another staging folder of your choosing. The final folder of the path must be named Data or the archive tool will pack the wrong path names. This is a bug in the Bethesda archive tool. This script will force usage of the Data folder or exit with an error.
To use the game data folder leave it blank.
Example: C:\WIP\MyMod\Data

$sOutputPath
------------
This is where the BSA will be created. If empty it will be the Mod Data folder. Otherwise it needs to be a full absolute path.
Example: C:\Program Files (x86)\Steam\SteamApps\common\Skyrim Special Edition\Data
Example: C:\WIP\MyMod\Data

$sLogFile
---------
The log file and path. It will be created relative to the mod data directory unless absolute. Because the archive tool overwrites it each time it runs, this script adds a time stamp to the name. The time stamp and file extension is appended to the string provided here. Using customizable variables is loosely supported. Just retain the single quote instead of using double quotes.
Leave blank for no log.
Example: Logs\Archives\ArchiveLog
Becomes: Logs\Archives\ArchiveLog.yyyy-dd-mm-hhmmss.txt
Advanced Example: $sOutputPath\$sOutputBSABaseFilename.ArchiveLog

$bCompressMainArchive
*--------------------
Flag for using compression on the main archive file. This may need to be disabled if you have wave sound files for sound effects and/or voices. There have been issues when using those compressed.
Valid Options: $true, $false

$bCompressTexturesArchive
-------------------------
Flag for using compression on the textures split archive. Only applies if separate texture archive is used. Will generate a warning if enabled without the separate textures flag.
Valid Options: $true, $false

$bSeparateTexturesArchive
-------------------------
Flag for separating the textures to their own archive file. Useful if you want to compress the textures but not the other files such as if you have voices or sound effects. Only valid for Skyrim Special Edition and Fallout 4. If legacy Skyrim is chosen it will generate a warning but split and archive anyway because you told it to.
Valid Options: $true, $false
Valid Game modes: SkyrimSE, Fallout 4

$sExclusiveModFolder
--------------------
This is a setting to facilitate packing just a specific mod folder within an unclean Data folder. It makes drastic changes to how the file selection is made. Because of this it may not get all your files unless they fit the following criteria. In an attempt to promote each mod developer to create their own folder within Meshes, Textures, etc. This will only grab files within a child folder with this name beneath the normal folders.
Example: MyMod
The search behavior is modified to look for this pattern with a conjunction of $sExclusiveModFolder and $sOutputBSABaseFilename being used. This will then only search for and pack:
Interface\<$sExclusiveModFolder>
Shadersfx\<$sExclusiveModFolder>
Meshes\<$sExclusiveModFolder>
Materials\<$sExclusiveModFolder>
Music\<$sExclusiveModFolder>
Vis\<$sOutputBSABaseFilename>.*
Vis\<$sExclusiveModFolder>.*
SEQ\<$sOutputBSABaseFilename>.seq
SEQ\<$sExclusiveModFolder>.seq
Scripts\<$sExclusiveModFolder>
Scripts\<$sOutputBSABaseFilename>
meshes\actors\<$sExclusiveModFolder>
meshes\actors\character\FaceGenData\FaceGeom\<$sOutputBSABaseFilename>.esp
meshes\actors\character\FaceGenData\FaceGeom\<$sExclusiveModFolder.esp>
textures\actors\character\FaceGenData\FaceTint\<$sOutputBSABaseFilename>.esp
textures\actors\character\FaceGenData\FaceTint\<$sExclusiveModFolder.esp>
Sound\<$sExclusiveModFolder>
Sound\fx\<$sExclusiveModFolder>
Sound\voice\<$sExclusiveModFolder>.*
Sound\voice\<$sOutputBSABaseFilename>
Strings\<$sExclusiveModFolder>.*
Strings\<$sOutputBSABaseFilename>.*

$ExcludedFiles
--------------
A PowerShell array list of file wildcards not to be included in the archive. Typically used to exclude script sources or text files from the archive. If you don't want any exclusions just make the variable empty.
Example none: @()
Example multi: @("*.psc", "*.txt")
Example one: "*.psc"

2.2. One click mode.
--------------------

So now that you've defined the default variables you are ready to use the script. Simply right-click in Windows explorer or your file manager of choice. Choose Run with PowerShell. If you set up the variables properly for your system you should be good to go.

2.3. Advanced command line options.
-----------------------------------

So the one click mode isn't enough for you? It wasn't for me either. There are command line arguments which will override most of the defaults. The one exception is the log file. The command line only supports disabling the log, not changing the output log file.

All arguments are optional. Any that are not provided will use the default set in the script file. Any extra argument parameters will be listed within <> with a simple definition of the expected value. For detailed explanations of the values and valid options see the previous section 2.1a where the default variables are explained.

FOLDER AND FILE OPTIONS
--------
[-Data|ModDataDirectory ]
Ex: -Data "C:\WIP\MyMod\Data"
[-BSA|File|OutputFile ]
Ex: -BSA "MyMod"
[-Dest|OutputPath ]
Ex: -Dest "C:\WIP\MyMod\Data"
[-ExclusiveMod ]
Ex: -ExclusiveMod "MyMod"
[-ExcludeList ]
Ex: -ExcludeList "*.psc","*.txt"

GAME MODE OPTIONS
--------
Each of these is mutually exclusive. Using more than one will result in an error.

[-SK|Skyrim|SkyrimLE]
[-SSE|SkyrimSE|SkyrimSpecialEdition]
[-FO4|Fallout4]

MISC OPTIONS
--------

[-cm|CompressMain]
[-st|SplitTextures]
[-ct|CompressTextures]
[-NoLog]