First pass on package script docs

doc/Package.md

@@ -1,3 +1,114 @@
-# Packaging Scripts
+# Packaging Script
+
+The `ue4-package.ps1` script builds, cooks and packages your game into a folder, 
+much like using "File > Package Project" in the UE editor. However, it offers a 
+number of other features.
+
+This script operates based on a `packageconfig.json` file which must be present
+in the root of your UE4 project. Please see the [Package Config File docs](PackageConfig.md)
+for a full description of this file.
+
+```
+  ue4-package.ps1 [-src:sourcefolder] [-major|-minor|-patch|-hotfix] [-keepversion] [-force] [-variant=VariantName] [-test] [-dryrun]
+
+  -src          : Source folder (current folder if omitted), must contain buildconfig.json
+  -major        : Increment major version i.e. [x++].0.0.0
+  -minor        : Increment minor version i.e. x.[x++].0.0
+  -patch        : Increment patch version i.e. x.x.[x++].0 (default)
+  -hotfix       : Increment hotfix version i.e. x.x.x.[x++]
+  -keepversion  : Keep current version number, doesn't tag unless -forcetag
+  -forcetag     : Move any existing version tag
+  -variants Name1,Name2,Name3
+                : Build only named variants instead of DefaultVariants from packageconfig.json
+  -test         : Testing mode, separate builds, allow dirty working copy
+  -dryrun       : Don't perform any actual actions, just report on what you would do
+  -help         : Print this help
+```
+
+## What the Script Does
+
+### 1. Check Working Copy
+
+If you're using Git, as a safety check the script doesn't allow you to package 
+builds from a working copy with uncommitted changes. This ensures that your builds
+are always from a known version. 
+
+### 2. Locate UE Install
+
+The script can locate your UE4 install automatically. You may need to customise
+this on non-Windows platforms or if you use a source build. 
+
+See [How Scripts Locate the UE4 Install](UEInstall.md) for more details.
+
+### 3. Close the UE Editor
+
+If you have this project open in UE, the script will close the editor. This is
+to ensure that it won't interfere with any build actions.
+
+### 4. Increment Project Version
+
+The version number of the project will be increased automatically, by default
+as a "patch" release (meaning the 3rd number in the version string). As you 
+can see, you can supply arguments `-major`, `-minor` or `-hotfix` instead to 
+increment a different part of the version number. 
+
+This will edit the `DefaultGame.ini` file and replace the `ProjectVersion` 
+setting. This change will be committed automatically before the build if you're using Git.  
+
+If you don't want to change the version number, you can provide `-keepversion` on
+the command line instead.
+
+### 5. Tags Git Repository
+
+If you're using Git and the version number was incremented, the repository will
+be tagged with the new version number.
+
+### 6. Cook Maps
+
+Based on your settings in [packageconfig.json](PackageConfig.md), the tools knows
+which maps to cook into your packages. You can tell it to cook all of them automatically,
+only a specific list, or all *excluding* a chosen few.
+
+### 7. Package Variants
+
+Rather than building / packaging just a single way, `ue4-package.ps1` supports
+packaging multiple variants of your project. The variations can be:
+
+* **Platform**: lets you build for Windows, Linux, Mac etc
+* **Build Configuration**: so you can build a private version as Development, public version as Shipping for example
+* **Build Arguments**: If you want to toggle on/off compiled-in features that are triggered by build arguments, you can add them for different variants
+* **Release Destinations**: If you have one build for Itch, and a different one for Steam etc
+* **Cultures**: For if you want to include specific cultures in a build
+
+Variants are defined in [packageconfig.json](PackageConfig.md) in the root of 
+your project. You can either specify which variants you want to build on the command line,
+or you can just use the defaults as defined in your config.
+
+### 8. Unique Package Folder
+
+The destination of the package operation is generated from a combination of:
+
+* The `OutputDir` setting in your [packageconfig.json](PackageConfig.md)
+* The version number
+* The variant name
+
+Therefore if you're building variant "PublicSteamWin64" at version 1.1.2.0, the
+package output will be in `$OutputDir/1.1.2.0/PublicSteamWin64/`
+
+### 9. Optionally Zip Packaged Build
+
+If you've enabled the `Zip` option for a given variant in [packageconfig.json](PackageConfig.md),
+the package output folder will also be zipped up, into the `ZipDir` directory 
+as given in that same config file.
+
+The files are named `ProjectName_Version_Variant[_PlatformType].zip`, e.g. 
+`MyGame_1.1.2.0_PublicSteamWin64.zip`. 
+
+> We zip the contents of the *subfolder* of the package output, e.g. `WindowsNoEditor`,
+so that the root of the zip is your game executable.
+
+> The `_PlatformType` suffix is usually omitted; it will only be there if there is
+more than one subfolder in the package folder, which is only the case when you
+build a dedicated client & server. In that case there will be separate zips for
+each, e.g. `MyGame_1.1.2.0_PublicSteamWin64_WindowsClient.zip` and `MyGame_1.1.2.0_PublicSteamWin64_WindowsServer.zip`
 
-TODO

doc/PackageConfig.md

@@ -0,0 +1,3 @@
+# The packageconfig.json File
+
+TODO

doc/UEInstall.md

@@ -0,0 +1,13 @@
+# How Scripts Locate the UE4 Install
+
+If you're using an installed version of UE4, the script reads your project file
+and automatically finds the location of the tools.
+
+If you're using a source version of UE, or have installed in a non-standard location,
+you can define the following environment variables instead:
+
+* **UE4ROOT** : Set the root directory of installed versions of UE4 (instead of the default e.g. C:\Program Files\Epic Games). The script will find the correct version in subfolders e.g. UE_4.25
+* **UE4INSTALL**: Explicitly set the location of the UE4 build you want to use.
+    The script will just use this directly and assume it contains e.g. Engine/Build/BatchFiles
+
+