User Guide.tex

% Setup
\documentclass[12pt]{amsart}
\usepackage{array,amssymb,amsmath,amsthm,amsfonts,latexsym,euscript}
\usepackage[margin=0.7in]{geometry}
\usepackage{hyperref}
\raggedbottom
% Contents
\title{Skyrim Uncapper (SE/AE) User Guide}
\author{Andrew Spaulding (Kasplat)}
\begin{document}
\maketitle
\pagebreak

% Helper functions
\newcommand{\startblock}{
    \noindent\begin{minipage}{\textwidth}\setlength{\parindent}{0.5in}\bigskip
}
\newcommand{\stopblock}{\end{minipage}}

\startblock
\section{Introduction}

In this file, I hope to clear up some of the confusion surrounding how to
configure this plugin. My hope is that this file will obviate the need
to ask me questions on the Nexus forum, but I will, of course, be willing
to answer any questions regardless.
\stopblock

\startblock
\section{Change Log}

Note: In this section, versions considered stable (i.e. no major bugs) are in
bold, and versions considered unstable (i.e. major issues which render the mod
unusable for some players) are in italics.

\bigskip
\noindent
\emph{1.0.0}
\begin{itemize}
    \item Initial release.
\end{itemize}
\stopblock

\startblock
\noindent
\emph{1.0.1}
\begin{itemize}
    \item Fixed INI files not saving correctly.
    \item Fixed game setting loading not being address independent.
    \item Added compatibility with 1.6.317 to 1.6.353.
\end{itemize}
\stopblock

\startblock
\noindent
\emph{1.0.2}
\begin{itemize}
    \item Fixed an issue where the perk calculation was just completely wrong.
    \item Fixed an issue where unused perk points would be deleted at level up.
\end{itemize}
\stopblock

\startblock
\noindent
\textbf{1.0.3}
\begin{itemize}
    \item Fixed an issue where having multiple perk level brackets made the perk
          points additive across all levels.
    \item Rewrote the config loading system to be easier to extend with new
          fields later.
\end{itemize}
\stopblock

\startblock
\noindent
\textbf{1.1.0}
\begin{itemize}
    \item Added an option to disable each individual group of patches. Disabled
          patch groups will not be installed to the game engine, increasing mod
          compatibility.
    \item Added individual caps for enchanting charge and magnitude. These caps
          are still capped by the formula cap for enchanting.
    \item Added an option to increase off-attributes (e.g. health and magicka
          when stamina was selected) at level-up.
    \item Fixed the displayed colors of skills, whose formula cap was lower than
          their actual cap, in the skills menu.
\end{itemize}
\stopblock

\startblock
\noindent
\textbf{2.0.0}
\begin{itemize}
    \item Greatly improved the information provided by the log file.
    \item Added signature checking to code injection. The mod will now refuse to
          install a patch if the code at the patch location does not exactly
          match what the code was when the patch was written.
    \item Fixed the enchanting max\_charge formula using the wrong enchanting
          cap.
    \item Fixed an issue which prevented skills from being legendary'd in most
          cases.
    \item Fixed an issue where the legendary skill settings were not applied if
          the key for legendarying skills had been rebound (note: for some
          reason, rebound keys for this take a completely different code path).
\end{itemize}
\stopblock

\startblock
\noindent
\emph{2.0.1}
\begin{itemize}
    \item Fixed possible undefined behavior if/when a native game function threw
          an exception which then tried to unwind through this plugins code.
    \item Removed branch trampoline allocation. This mod no longer counts toward
          the practical limit on the number of SKSE plugins which can be
          installed.
    \item Fixed an engine bug which sometimes caused the legendary skill hint to
          be displayed incorrectly, and applied that bugs fix to this mods
          changes.
\end{itemize}
\stopblock

\startblock
\noindent
\emph{2.0.2}
\begin{itemize}
    \item Fixed a plugin panic when opening the vampire lord perk tree.
\end{itemize}
\stopblock

\startblock
\noindent
\emph{2.0.3}
\begin{itemize}
    \item Fixed an issue which prevented the address library from loading on
          the GOG version of Skyrim unless its database file was renamed.
\end{itemize}
\stopblock

\startblock
\noindent
\textbf{2.0.4}
\begin{itemize}
    \item Fixed an issue which made bLegendaryKeepSkillLevel reset the level
          to a garbage value.
\end{itemize}
\stopblock

\startblock
\noindent
\emph{2.1.0}
\begin{itemize}
    \item Added compatibility with game versions 1.5.97 and below.
    \item Cleaned up the legendary skill and enchantment charge hook
          implementations.
    \item Added the ability to apply skill XP multipliers to the XP offsets
          as well as the base values.
\end{itemize}
\stopblock

\startblock
\noindent
\emph{2.1.1}
\begin{itemize}
    \item Fixed an issue which prevented patches from being disabled.
\end{itemize}
\stopblock

\startblock
\noindent
\emph{2.1.2}
\begin{itemize}
    \item Moved a patch to enable compatibility with meh321's .NET framework.
    \item Added an option to disable only the formula cap UI fixes, without
          disabling the formula cap patch itself.
    \item Fixed up assembly code to avoid possible register clobbering, mostly
          out of paranoia.
\end{itemize}
\stopblock

\startblock
\noindent
\emph{2.1.3}
\begin{itemize}
    \item Fixed a regression which made this mod incompatible with the
          eXPerience mod.
\end{itemize}
\stopblock

\startblock
\noindent
\textbf{2.1.4}
\begin{itemize}
    \item Fixed a regression in the previous version which made skills cap based
          on a garbage value in the AE implementation.
\end{itemize}
\stopblock

\startblock
\noindent
\textbf{2.1.5}
\begin{itemize}
    \item Added a system for detecting plugin conflicts which corrupt this mods
          patches after they have already been installed to the games code. Note
          that if this situation is encountered the game will \emph{always} be
          closed since it cannot be safely run in such a state.
\end{itemize}
\stopblock

\startblock
\noindent
\textbf{2.2.0}
\begin{itemize}
    \item Added a system for automatically adding missing fields to the INI file
          without overwriting the users current settings/formatting/comments.
    \item Fixed a crash when getting/spending perks at a level below the lowest
          defined level in the INI file.
    \item Fixed a crash encountered when the path to a file used by this plugin
          contained non-unicode text (in practice, this meant pretty much any
          non-english text).
\end{itemize}
\stopblock

\startblock
\noindent
\textbf{2.2.1-beta}
\begin{itemize}
    \item Fixed an issue where the formula cap was applied to NPCs as well.
    \item Rosolved the incompatibilty between the Custom Skills Framework and
          the formula cap UI fix. Note that the legendary patch is still
          incompatible with CSF.
\end{itemize}
\stopblock

\startblock
\noindent
\textbf{2.2.1}
\begin{itemize}
    \item Stablized patches from 2.2.1 beta.
    \item Fixed a long-standing issue which prevented the formula cap from
          correctly applying for certain effects (e.g. one-handed damage,
          spell cost)
    \item Refactored code for simplicity. Moved to a "no\_std" environment.
\end{itemize}
\stopblock

\startblock
\section{Bug Reports}

If you encounter an issue with the plugin, which may include strange game
behavior, plugin incompatibility, or a CTD (which would hopefully include
a panic message box from the plugin), please report it to me on the BUGS
section of the nexus page. Please do not report it in the posts section, as
this section has less visiblity to me and other users (e.g., I do not get
notified on Nexus when someone makes a post in that section).

When reporting a bug, please include a copy of the log file found in
\textlangle Documents\textrangle/My Games/Skyrim Special Edition/SKSE/SkyrimUncapper.log,
as well as a brief description of the issue/what you were doing when you
encountered it. This information will allow me to resolve the problem promptly.
\stopblock

\startblock
\section{INI file generation and updating}

\bigskip
\subsection{INI file location}\hfill\\

The location of the INI file will depend on a few factors. Those being the
current version of the plugin you are running, and whether or not you have,
at any point, run the game with a previous version installed. It will also
depond on if you are using a mod manager, though I will assume that everyone
is because if you aren't you need to rethink the choices in your life that
brought you to this point.

The path to the INI file is always /data/SKSE/plugins/SkyrimUncapper.ini.
Where the file actually gets place will depend on your plugin version and
mod manager.
\stopblock

\startblock
\subsubsection{Kassent/Vadfromnu's uncapper, or versions 1.1.0 and below,
or for those updating from any of these}\hfill\\

Those who are using/used these versions of the plugin will have had their
INI file generated. MO2 will place this generated INI file in the overwrite
directory. Vortex should place the file in Skyrim's game directory. You will
need to run the game with the plugin at least once before configuring it.
Note that the default configuration uses all vanilla settings.
\stopblock

\startblock
\subsubsection{Versions 2.0.0+}\hfill\\

These versions package the INI file with the zip file. If using MO2, this file
will be ignored if there is also an INI file in the overwrite directory.
Assuming there is no INI file in the overwrite directory, the file will appear
in the same directory as the plugin itself.
\stopblock

\startblock
\subsection{Updating the INI file}\hfill\\

When new fields are added to the INI file by an update to the plugin, some
versions of the plugin will automatically add those fields. How each version
goes about this process varies, however.
\stopblock

\startblock
\subsubsection{Kassent/Vadfromnu's uncapper, or versions 1.1.0 and below}\hfill\\

These versions of the uncapper track the file version using the \textit{Version}
field in the \textit{[General]} section of the INI. If this field is outdated
(according to the value that said version of the plugin expects) the INI file
is regenerated with the currently stored configuration values as loaded from
the INI.

Note that this regeneration has a few issues. Any field which was not loaded
correctly will be lost, and all user-added comments/formatting are stripped
from the INI file in this process. It is as if the INI file was generated again
from scratch, except the previously known values are used instead of the
default values.
\stopblock

\startblock
\subsubsection{Versions 2.0.0 to 2.1.5}\hfill\\

These versions of the uncapper make no attempts to automatically update the INI
file. These versions will issue warnings in the log file when they detect
that a field/section is missing from the INI file, however any actual updates
to the file must be manually applied by the user.
\stopblock

\startblock
\subsubsection{Versions 2.2.0 and above}\hfill\\

These versions will automatically append missing fields to the end of the
section they should appear in, and missing sections to the end of the file.
The formatting and comments within the INI files should not be altered by this
process (or should only be minimally altered). A message will be displayed to
the user when the game is launched if their INI file was updated.

Note that this process happens independent of the values of any field. This
means that the \textit{Version} field used in previous versions of the uncapper
is ignored by these versions.
\stopblock

\startblock
\section{INI Configuration}\hfill\\

The INI configuration is split into sections, with most sections having some
way to disable them entirely from the general section. This ability was
introduced in version 1.1.0 of the plugin.
\stopblock

\startblock
\subsection{[General]}\hfill\\

This section includes options to disable individual patches, as well as some
now depreciated options related to updating the INI file.

Note that when a patch group is disabled the patches it governs will not be
installed to the game, and thus will not conflict with any mods. If, for
example, thu uncapper notes that DisplayTrueSkillLevel could not be installed
or was clobbered, disabling bUseSkillFormulaCapsUIFix would allow the plugin
to load at the cost minor graphical issues being present on the skills menu.
\stopblock

\startblock
\subsubsection{Author = \textlangle String\textrangle}\hfill\\

This field is ignored by all versions of the plugin.
\stopblock

\startblock
\subsubsection{Version = \textlangle unsigned int\textrangle}\hfill\\

This field is used by versions 1.1.0 and below to determine if the INI file
should be updated. Versions 2.0.0 and above ignore this field.
\stopblock

\startblock
\subsubsection{bUseSkillCaps = \textlangle true/false\textrangle}\hfill\\

Enables the patch group which allows the absolute level cap of skills to be
changed. Without this group, all skills will have a level cap of 100.

Enables patches:
\begin{itemize}
    \item GetSkillCap
\end{itemize}
\stopblock

\startblock
\subsubsection{bUseSkillFormulaCaps = \textlangle true/false\textrangle}\hfill\\

Enables the patch group which allows the formula cap for skills to be altered.
Without this group, the game will cap the formula in the default manner
(e.g. it either wont or will cap at 100, depending on what it is).

Enables patches:
\begin{itemize}
    \item PlayerAVOGetCurrent
    \item (2.2.1 and above) CapMagickaCDR
    \item (2.2.1-beta and above) UpdateSkillList
    \item (2.2.0 and below) DisplayTrueSkillLevel
    \item (2.2.0 and below) DisplayTrueSkillColor
\end{itemize}
\stopblock

\startblock
\subsubsection{bUseSkillFormulaCapsUIFix = \textlangle true/false\textrangle}\hfill\\

Deprecated. Does nothing in versions 2.2.1 and above.

In versions 2.2.0 and below, disabling these patches is necessary for the mod to
load with the Custom Skills Framework, however it will also cause skill levels
to display incorrectly in some menus.

Note that this option does nothing if bUseSkillFormulaCaps is disabled.

In 2.2.1-beta and below, this option controls the following patches:
\begin{itemize}
    \item (2.2.1-beta) UpdateSkillList
    \item (2.2.0 and below) DisplayTrueSkillLevel
    \item (2.2.0 and below) DisplayTrueSkillColor
\end{itemize}
\stopblock

\startblock
\subsubsection{bUseEnchanterCaps = \textlangle true/false\textrangle}\hfill\\

\subsubsection{bUseSkillExpGainMults = \textlangle true/false\textrangle}\hfill\\

\subsubsection{bUsePCLevelSkillExpMults = \textlangle true/false\textrangle}\hfill\\

\subsubsection{bUsePerksAtLevelUp = \textlangle true/false\textrangle}\hfill\\

\subsubsection{bUseAttributesAtLevelUp = \textlangle true/false\textrangle}\hfill\\

\subsubsection{bUseLegendarySettings = \textlangle true/false\textrangle}\hfill\\

\subsection{[SkillCaps]}\hfill\\

\subsection{[SkillFormulaCaps]}\hfill\\

\subsection{[Enchanting]}\hfill\\

\subsection{[SkillExpGainMults]}

\subsubsection
\stopblock

\startblock
\section{External Links}

\href{https://github.com/TheDreadedAndy/SkyrimAEUncapper-Rust}{GitHub}

\href{https://www.nexusmods.com/skyrimspecialedition/mods/82558}{Nexus}
\stopblock

\end{document}