===================================================================================================
HKXCMD
AUTHOR: Lord Zapharos (www.lordzapharos.com)
DATE: 8 October 2025
VERSION: 1.6
===================================================================================================


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 application(s):

    hkxcmd 1.5 by cedec0
            (https://www.loverslab.com/topic/89327-hkxcmd-15/)
    hkxcmd 1.4 by figment
            (https://www.nexusmods.com/skyrim/mods/1797)


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

hkxcmd is an essential tool for creating animations and editing behaviors in Skyrim, allowing you
to decompress the game's HKX file format into editable XML or KF files and back again. Almost every
animation tool you can find for Skyrim - 32-bit or 64-bit - starts with some variation of hkxcmd.

Unfortunately, the original inception of this tool contains a bug in which at least 1-2 frames are
dropped (lost) from every file converted from KF back to HKX, causing glitchy or ugly animations. A
newer version of this tool (1.5) addresses this bug, but also has several bugs of its own; notably,
it strips out Camera animation bones, making it impossible to put certain animations into the game.
Regardless of which version you use, the tool is not friendly for beginners and has cryptic errors.

I reverse-engineered and repackaged hkxcmd 1.5 to accomplish the following:

 - Camera bones can now be exported to HKX.

 - Several bugs with folder processing were fixed.

 - A custom skeleton rig was created for processing horse_rider animations (which no prior version
   of hkxcmd could correctly export without mangling).

 - Several droplets and batch scripts were included to make the process easier for beginners. An
   animation primer for beginners is also included below.

 - Older, easily-swappable versions of hkxcmd have been bundled for those few stubborn animations
   that require a specific hkxcmd version.

 - API-stable: can be plugged into other applications that bundle their own version of hkxcmd.

Please note that the author of 1.5 never released his source code for the camera bone patch. There
are certain bugs I cannot resolve short of decompiling the entire program (a huge undertaking). As
a result, my ability to support this application's continued development is quite limited.

Please also note that ALL VERSIONS of hkxcmd are buggy, and the project has been mostly abandoned.
It is common for certain animations to only work when processed with a specific version of hkxcmd,
which is why I have bundled other swappable versions into this release. A few animations cannot be
saved with ANY version of hkxcmd; you cannot work with these at all until someone develops a new
tool from scratch or decompiles hkxcmd 1.5 to resolve those bugs. Converting HKX to XML or KF is
more reliable than converting KF to HKX, especially for vanilla animations.

The only "always-works" approach to editing all animations is to possess a copy of 3ds Max 2010/12
with the associated version of Havok Tools. Unfortunately, there is no way to get either of these
applications officially, and Autodesk ever so graciously stopped offering activation for those of
us with legal copies of these "outdated" versions despite our protestations (gee, thanks a ton!).


CONTENTS:
===================================================================================================

The following hkxcmd versions are bundled in this release:

+-----------------------------------------------+------+------------------------------------------+
| LOCATION                                      | VER. | NOTES                                    |
+-----------------------------------------------+------+------------------------------------------+
| bin/hkxcmd.exe                                | 1.6  | My version of hkxcmd. Keeps camera bones |
|                                               |      | upon exporting to HKX.                   |
+-----------------------------------------------+------+------------------------------------------+
| bin/stripCamera/hkxcmd.exe                    | 1.6  | My version, but strips camera bones upon |
|                                               |      | export. Identical to 1.5 except for some |
|                                               |      | bug fixes.                               |
+-----------------------------------------------+------+------------------------------------------+
| bin/15_original/hkxcmd.exe                    | 1.5  | The original 1.5 version of hkxcmd. Only |
|                                               |      | included for archival purposes.          |
+-----------------------------------------------+------+------------------------------------------+
| bin/14_useForCorruptSplineExport/hkxcmd.exe   | 1.4  | An earlier version of hkxcmd to be used  |
|                                               |      | when 1.5+ fails converting HKX->KF due   |
|                                               |      | to a "corrupt spline" error. Do not use  |
|                                               |      | for KF->HKX conversion, as frames WILL   |
|                                               |      | be lost.                                 |
+-----------------------------------------------+------+------------------------------------------+

Please note that all included droplets and batch scripts use bin/hkxcmd.exe. If you want to use a
different version, rename bin/hkxcmd.exe to anything else and then copy the hkxcmd you want into
the bin/ folder.

The following animation rigs (skeletons) are bundled in this release:

                                                  +-----------------------------------------------+
                                                  | NOTES                                         |
--------------------------------------------------+-----------------------------------------------+
| skeletons/LZ_skeleton_horse_rider_toKFOnly.hkx  | Used for exporting HKX->KF for animations in  |
|                                                 | the horse_rider folder (trying to export them |
|                                                 | using any other skeleton will cause messed-up |
|                                                 | bone transforms). When exporting KF->HKX, you |
|                                                 | must use the male skeleton.hkx rig instead.   |
+-------------------------------------------------+-----------------------------------------------+
                                                  +-----------------------------------------------+
In skeletons/meshes/actors/:                      | NOTES                                         |
+-------------------------------------------------+-----------------------------------------------+
| vampirelord/character assets/skeleton.hkx       | Vanilla skeleton rig for vampire lords.       |
+-------------------------------------------------+-----------------------------------------------+
| werewolfbeast/character assets/skeleton.hkx     | Vanilla skeleton rig for player werewolves.   |
+-------------------------------------------------+-----------------------------------------------+
                                                  +-----------------------------------------------+
In skeletons/meshes/actors/character/:            | NOTES                                         |
+-------------------------------------------------+-----------------------------------------------+
| _1stperson/characterassets/skeletonfirst.hkx    | Vanilla skeleton rig for first-person.        |
+-------------------------------------------------+-----------------------------------------------+
| character assets/skeleton.hkx                   | Vanilla skeleton rig for male third-person.   |
+-------------------------------------------------+-----------------------------------------------+
| character assets female/skeleton.hkx            | Vanilla skeleton rig for female third-person. |
|                                                 | Any animations outside the female/ folder use |
|                                                 | the male rig in vanilla i.e. they are unisex. |
+-------------------------------------------------+-----------------------------------------------+


USAGE (WITH OTHER APPLICATIONS):
===================================================================================================

If you are using another tool that bundles its own hkxcmd, you can use my version with that tool.
Just close the other tool, back up the tool's existing hkxcmd.exe, and then copy my version from
the bin/ folder to the tool's hkxcmd location. After you have replaced the tool's hkxcmd, start it
up and resume your workflow as normal.

Some applications embed hkxcmd directly into their EXE code; you cannot use my hkxcmd with these
without a hex editor (and even then, there are no guarantees).


USAGE (STANDALONE):
===================================================================================================

To make animation conversion easier, I have created several batch scripts for hkxcmd. You can use
these without ever opening a Command Prompt! The following items are included:

+------------------------+------------------------------------------------------------------------+
| drop_1stP_toHKX        | When you drop a KF file onto this batch script, the file is converted  |
|                        | to HKX using the first-person skeleton in the skeletons/ folder. The   |
|                        | output file is placed next to the input file. If you drag a folder     |
|                        | with KF files onto this script, a new folder outHKX/ will be created   |
|                        | next to the input folder. A Command Prompt will open to show progress; |
|                        | press any key to close it after the operation is complete.             |
+------------------------+------------------------------------------------------------------------+
| drop_1stP_toKF         | Converts HKX files to KF using the first-person skeleton.              |
+------------------------+------------------------------------------------------------------------+
| drop_female_toHKX      | Converts KF files to HKX using the female third-person skeleton.       |
+------------------------+------------------------------------------------------------------------+
| drop_female_toKF       | Converts HKX files to KF using the female third-person skeleton.       |
+------------------------+------------------------------------------------------------------------+
| drop_hkx_fromXML       | Converts XML files to HKX. Does not require a skeleton rig. This is a  |
|                        | lossless conversion (i.e. converting from HKX to XML back to HKX will  |
|                        | produce an identical file).                                            |
+------------------------+------------------------------------------------------------------------+
| drop_hkx_toXML         | Converts HKX files to XML. Useful for editing annotations or "opening" |
|                        | behavior files for inspection.                                         |
+------------------------+------------------------------------------------------------------------+
| drop_horseRider_toHKX  | Converts KF files to HKX using the male third-person skeleton.         |
+------------------------+------------------------------------------------------------------------+
| drop_horseRider_toKF   | Converts HKX files to KF using my custom horse skeleton.               |
+------------------------+------------------------------------------------------------------------+
| drop_male_toHKX        | Converts KF files to HKX using the male third-person skeleton.         |
+------------------------+------------------------------------------------------------------------+
| drop_male_toKF         | Converts HKX files to KF using the male third-person skeleton.         |
+------------------------+------------------------------------------------------------------------+
| drop_vampireLord_toHKX | Converts KF files to HKX using the vampire lord skeleton.              |
+------------------------+------------------------------------------------------------------------+
| drop_vampireLord_toKF  | Converts HKX files to KF using the vampire lord skeleton.              |
+------------------------+------------------------------------------------------------------------+
| drop_werewolf_toHKX    | Converts KF files to HKX using the werewolf skeleton.                  |
+------------------------+------------------------------------------------------------------------+
| drop_werewolf_toKF     | Converts HKX files to KF using the werewolf skeleton.                  |
+------------------------+------------------------------------------------------------------------+

In addition to these, there is a separate set of batch files prefixed with "run_". These latter
files do the same thing as the droplets above, but utilize the respective inHKX/, inKF/, inXML/,
outHKX/, outKF/, and outXML/ folders for their input and output.

If you prefer, you may operate hkxcmd from the Command Prompt directly. To do this, just open the
Command Prompt and navigate to the bin/folder, then run hkxcmd (with no arguments) to see the list
of supported options.

To use a specific version of hkxcmd from the batch scripts, rename bin/hkxcmd.exe to anything else
and then copy the hkxcmd you want into the bin/ folder. All batch scripts use the hkxcmd in bin/.


ANIMATION PRIMER:
===================================================================================================

Unlike most other aspects of Skyrim modding, documentation regarding animations is very scarce. The
text below is intended to provide beginners with a basic idea of how the process works. It does not
aim to be exhaustive.

-- Overview --

All versions of Skyrim use Havok, a popular animation and physics engine. Havok is a general tool
supporting many different games - Skyrim does not use all of its features. Editing Havok animations
is therefore a different experience across different games. Many files you edit may contain empty
data structures or unused fields, or they may be structured in a way specific to Skyrim.

All of Skyrim's Havok files have the extension "HKX". Most can be extracted from the archive file
Skyrim - Animations.bsa, located in your Skyrim Data folder. DLC-specific animations are found in
their respective BSA file (alongside other unrelated files).

Animation mods may include their own BSA files, or may place animations as loose files in your Data
folder. Every animation is located in Data/meshes, and animations specific to the player are found
in meshes/actor/character (the _1stperson, female, and male folders especially). However, there is
no requirement for animations to be in a specific location (other than within meshes/).

Unlike other aspects of Skyrim modding, animations are "all-or-nothing". Changes to a specific file
cannot be easily merged into another. Resolving conflicts can therefore be quite tedious.

Tools for editing animations in Skyrim are scarce, poorly-documented, and often buggy. Experts in
this field can be difficult to contact; many are lurking on the Skyrim Modding Guild Discord. If
you try to obtain help - be nice, be appreciative, and be patient! Animation is hard work, and
Skyrim makes it doubly so.

In general, you will need a copy of hkxcmd and Blender to work with Skyrim animations. Knowing how
to use Nifskope can be important too, especially when working with vanilla files.

-- HKX Files --

HKX files consist of two basic parts: metadata and the animation itself (often called a "spline").

Metadata describes the behavior of the animation and how it communicates with other animations.
This is also where "annotations" are recorded, which define things like when footstep sounds should
occur during a sprint animation. Some types of metadata are confined to "behavior files", applying
to all animations of a certain type (more on that below). Others are specific to each animation, as
is the case with footstep sounds.

Metadata further includes "events" and "states". Mods can use Papyrus scripts to hook into specific
animation events. The RegisterForAnimationEvent() function in Papyrus allows you to "do something"
when an animation event occurs. In Papyrus, xEdit, and the Creation Kit, GetGraphVariable functions
allow you to access the current state of an animation, along with other data such as position.

The animation itself is a compressed data stream of "key frames": data that instructs which part of
the character should be located where, rotated how, and at what time. The parts of the character we
can move are called "bones", and they are defined in the character's "skeleton" file. There are two
types of skeletons: the skeleton.nif is used by the game itself, and skeleton.hkx is the "animation
rig" used for editing animations: defining the relationships and default positions of each bone.

Because animations are compressed, we cannot edit them directly. We use hkxcmd to extract splines
to a KF - key-frame - file, which can then be edited by Blender, Nifskope, and other tools.

Metadata is also extracted with hkxcmd, to XML files. These XML files also contain the animations,
but they remain compressed and cannot be edited here.

-- Behavior Files --

A special type of HKX file is called the "behavior file". These files are often named accordingly
e.g. 1hm_behavior.hkx for the behavior of all one-handed weapons.

Behavior files do not contain any animations by themselves, but instead contain metadata describing
both the default behavior of all animations of that type, while also listing the animation files
themselves. For example, sprintbehavior.hkx describes the general flow of events for sprinting: the
common events that should be triggered when a sprint starts or ends. It also defines the different
types of sprint animations: for one-handed weapons, two-handed weapons, and so on.

Because behavior files define all of a character's available animations, we often need to edit them
when we want to add new ones. This is what tools like FNIS, Nemesis, and Pandora are for: they take
your new animation and inject it into the vanilla behavior files - while keeping other mod-added
animations intact. As a result, you usually do NOT need to edit behavior files yourself.

Behavior files can be edited directly via Skyrim Behavior Tool (SBT) if needed. However, this tool
is often used instead for inspecting and visualizing the behavior itself, as the XML files are too
complex and difficult to follow. Other tools exist for this purpose as well.

-- Creating New Animations --

Strange as it may seem, adding new animations is usually EASIER than editing vanilla ones. The
Skyrim community appears to prefer creating new animations over editing vanilla ones. Most online
tutorials and the help you get on the Modding Guild Discord and in other forums tend to assume you
are doing the former. Getting help for vanilla animations is much harder.

If you have the fortune to possess a working copy of 3ds Max 2010 or 2012 and the associated Havok
Content Tools plugin, you can export to HCT directly from 3ds Max and then use the Filter Manager
in your Havok installation directory to convert it to HKX. This is the basic workflow that was used
by Bethesda itself when developing Skyrim.

Unfortunately, 3ds Max 2010 and 2012 are no longer available for purchase. Users with an existing
perpetual license can no longer activate their copies of this application on Autodesk either. To
export Havok files via this workflow, you need a very specific version of Havok Content Tools; any
other version will not export properly. Newer versions of 3ds Max do not work for this at all.

As such, many Skyrim animators today use a combination of Blender and hkxcmd. If you have access to
Havok Content Tools, you may be able to use other animation programs to export to HCT. Finding help
for the latter workflow can be quite difficult, however.

When creating new animations, N3 Animation Tools (https://www.nexusmods.com/skyrim/mods/34671) can
be useful, as it provides Blender scripts and sample files for quickly setting up and getting your
animation into the game. There are other iterations of this tool - and other tools entirely - for
exporting new animations from Blender.

Keep in mind that you may need a specific version of Blender for different tool setups. Thankfully,
Blender provides a repository of all its previous versions should you need them. There is currently
no "default version" of Blender that should be used for all of Skyrim - it depends on the use-case.
It is common to need different versions for different things; the portable versions of Blender work
very well for this should you require multiple versions on the same computer at the same time.

-- Editing Vanilla Animations --

The basic workflow for changing vanilla animations is as follows:

 1. Use hkxcmd to convert the HKX file to KF.
 2. Import the KF file into Blender and make your animation changes (Nifskope can also be used for
    simpler changes).
 3. Convert the KF file back to HKX using hkxcmd.
 4. Convert both the vanilla HKX file and your new HKX file to XML using hkxcmd, and copy any
    annotations from the vanilla XML into the new one.
 5. Convert the new XML back to HKX using hkxcmd.
 6. Place the final HKX file in your Skyrim Data folder (in the same location as the vanilla),
    overwriting the vanilla animation if present. Make sure to keep backups!

Although the process itself is simple, there are several issues that often occur when working with
vanilla animations:

 - Some HKX animations cannot be exported to KF (such as those in the horse_rider/ folder). My tool
   assists with this; you may need to use different versions of hkxcmd to export without errors.

 - Some KF animations cannot be exported to HKX or get corrupted afterwards. All versions of hkxcmd
   prior to 1.5 had a bug in which 1-2 frames are DROPPED (lost) from the converted animation. The
   newer versions of hkxcmd resolve this problem, but remove Camera animation bones, which breaks
   certain animation types. Camera bones can be exported in my version (1.6), but 1.5+ introduced
   other bugs i.e. regressions I have not yet been able to fix. As such, a few vanilla animations
   cannot be saved as HKX by any means!

 - Some XML files cannot be exported in newer versions of hkxcmd (1.5+). Older versions often work.

 - You often need to change which hkxcmd version you use, depending on the vanilla animation you
   want to edit. You may even need to use a different hkxcmd for importing than for exporting!

 - There is very little documentation as to how vanilla animations work. Bethesda's developers did
   not have a good QA process, leading to many bugs and inconsistencies that make understanding the
   vanilla animations that much more difficult.

 - Because hkxcmd has been largely abandoned, you are on your own when editing vanilla files. Very
   few people seem willing to help with vanilla animations.

In short: expect a LOT of trial-and-error before you get things right.

-- Previewing Animations --

If you want to quickly preview what a specific animation does, you can use Nifskope:

 1. Convert the HKX animation to KF first if necessary.
 2. Open the skeleton.nif (the NIF skeleton file; not the HKX rig!) in Nifskope.
 3. Select Spells -> Animation -> Attach .KF from the toolbar, and select your KF file. You may get
    some errors when opening the file; you can usually ignore these.
 4. Click on the root node of the skeleton so you see the bones in the viewport (they look like a
    bunch of green dots in most Nifskope versions).
 5. Click the Play button to run the animation.

This only works for regular animation bones. Changes to camera bones - Camera Control, Camera1st,
Camera3rd, and (for third-person only) AnimObjectA - can still be previewed, but visualizing the
effect these actually have on the player camera is almost impossible without testing in game. Other
"special" bones may prove likewise difficult to visualize.

Annotations cannot be tested at all without running the animations in-game. Never forget to test
your annotations - this is the cause of many common mod complaints such as missing footstep sounds!

IF IT HAS NOT BEEN TESTED IN GAME, THEN IT DOES NOT WORK! Many Havok errors are NOT caught by the
current tools we have available - and the consequence for any error is a game crash. Make sure you
always test every animation in-game, no matter how small or simple your changes might seem!
