Category Archives: Skyrim

Papyrus for 4coder

Oh, hey. It’s been a while, but I’m catching the Skyrim bug again.

Over the last few months I’ve been gradually shifting my development over to 4coder (from Sublimetext and VS Code, which are actually both pretty great) so I created Papyrus syntax highlighting and a build script. I’m sharing this stuff on GitHub, and you can read more about it on its own blog page.

Time to update my tools, get SKSE64 working, and learn about this Vortex thing.

You guys need a bath.


Now that I have access to the new CreationKit, I’ve rewritten and compiled several scripts to work with Skyrim Special Edition.

Something that has always irked me is that the Papyrus compiler adds your Windows account name and PC name strings to compiled pex files. You can view these strings in a hex editor, and they get spit out by the decompiler.

It isn’t a huge deal, I just don’t really like it; so I wrote a program to cover up the strings in the compiled files. I call it AnonPex and you can find more information about it on this page:

It doesn’t do anything fancy. No code is compiled/decompiled. It just reads the binary and changes the two strings. The string lengths are preserved, so the output should be identical to the compiled Papyrus except that all of the characters in the Windows account name and PC name fields will be question marks.

Skyrim Animations – Poser Hotkeys

Over the winter holiday I ran into a problem that resulted in the creation of a new mod and a new tool for Skyrim. The mod is called Poser Hotkeys and the tool that generates the data for the mod is PoserDataGen.

Recently, I’ve been spending most of my time in Skyrim setting up cool scenes for screenshots. I have several poser mods installed and I was finding it tedious to find a cool pose, apply it to an actor, position the actors and then find a good camera angle. I use several tools for this, but none of them seemed to play together nicely.

I have heard of some tool that allows you to assign hotkeys to iterate through poses in the MCM. That sounded great but I could never find a reliable download source, so I just created my own mod for it. You can get my mod and the data tool for the mod on the Nexus. The source code repositories are also available here and here.

If you want to know how to use them in your game, check out the Read Me or Nexus description. The rest of this post is a breakdown of what these things do, how and why.

Adding animations to Skyrim is made possible through a tool called Fores New Idles in Skyrim, or FNIS for short. If you are interested, Fore has some technical documentation available on the FNIS Nexus page.

When an artist adds animations to Skyrim, they need to supply FNIS with a text file containing a list of the animation files along with a name for each animation or pose. These names provide a means to play the animation through SendAnimationEvent in Papyrus.

Poser Hotkeys is essentially a means to organize animation events and call SendAnimationEvent when a user presses a button. In order to send the correct animation event, Poser Hotkeys has to know the event name to send. This is where PoserDataGen comes in.

PoserDataGen is a .NET tool that scans your Skyrim animations folder for FNIS definitions. These definitions are then placed into data files that Poser Hotkeys can read at run time. Being data driven allows the mod to work with any poser combination that exists on a user’s setup without the need to recompile scripts or make changes in the CreationKit.

Originally, I threw the data into XML and used FISS to read it at run time. This worked reasonably well, but there were some problems. The first is that FISS seems to be unable to handle reading a string from an empty XML attribute. For example, reading from the element “name” below:

I would expect this to return an empty string, but instead FISS sends through the XML starting with the end of the “name” element. In this example, the string returned by FISS for element “name” would be:

This is a problem for me, since there are times I am expecting elements to be empty. A second problem I was having was that I couldn’t scan a  folder for XML files. This meant that I had to either create a hard coded list of XML to look for (thus limiting the poser support) or cram all of the definitions into a single, known XML file.

I opted to cram everything into a single XML file, which then created other problems: I could only handle 128 poser packs since that is the array length limit of Papyrus, whenever a user installed or removed a poser the entire XML file had to be recreated with PoserDataGen from scratch (invalidating their favorites), and the file had to be loaded by the user in MCM before the mod could be aware of data.

Beyond all that, another problem was that I was introducing an additional dependency for the user.

Since I already require PapyrusUtil for functions related to NPC packages (to stop them in place while they play an animation) I took a look at the Json library that comes with it. It turns out that JsonUtil works very well, so I changed PoserDataGen to spit out .json data files that JsonUtil can read at run time. This lets me update and save parts of the loaded .json files on the fly during run time and save things, like the currently selected pose, directly in the pose’s data file. There is also a function to get an array of all .json files in a specific directory, which lets me scan for poser data files without having to know which ones to look for ahead of time.

How it works now is that PoserDataGen loads all of the FNIS animation lists and organizes the pose data by poser and by “poser pack.” I define a poser to be an FNIS list file and a “poser pack” to be animation definitions that share a similar prefix. For example, Halo’s Poser S comes with two FNIS files which results in two poser data files. Each FNIS file has several groups of animations starting with a similar prefix. For example, all poses that are part of Halo’s Poser Module 11 start with “H11P” resulting in a “poser pack” called H11P in the data file.

I allow a user to specify their Skyrim directory in the accompanying config file. If it’s not there, I try to find it in the registry. Failing that, I try a hard-coded default path that Steam uses when it installs the game. Here is the C# for it:

Once I find a valid animations folder, I save the Skyrim directory in the config so I don’t need to keep asking for it every time you open the app:

A neat feature I added is the option to validate that animation files actually exist for each animation event before adding them to the data file. If I simply trust the FNIS file, Poser Hotkeys could send animation events to an actor that do not have a matching animation file, resulting in the actor simply doing nothing. Since the SendAnimationEvent function has no return value, Poser Hotkeys does not know if sending the event succeeded or failed. Users would be left without any information as to why they pressed a button to start a pose and nothing happened, which is obviously a bad experience for the user.

I added this because my copy of Pinup Poser includes many animation events for animation files that are absent, resulting in lots of data records that did nothing when executed. With this option turned on, PoserDataGen skips the missing animations, making them invisible to the user.

When parsing the FNIS files, I only worry about a single FNIS list file in each directory. I may change this to handle multiple files in the future, but I have never come across a poser that had more than one in a single folder, and I think FNIS enforces that only one list file can be in a given directory anyway.

I then go line by line to find the animation events. FNIS allows the author to define some options in between the animation event and the animation file path, so I need to check and skip the unneeded data if present. I need the animation file path to verify the file actually exists, assuming the user has selected the option:

All of this data is written out to .json in a structure matching what is expected by JsonUtil. The structure is unintuitive to me, though I have to assume it’s needed for the utility to function. Since Papyrus has no concept of objects, it is difficult to serialize related data in a meaningful way. JsonUtil seems to prefer to nest elements according their data type. For example, all strings are nested under an element called “string” and all integer lists under “intList.”

Something peculiar I found while using JsonUtil was that it refused to read data from keys that started with a capital letter. When JsonUtil creates data, it seems to always start with a lower case letter. Since I am not using JsonUtil to create the data files I didn’t know about this and I had a hard time discovering why I could not read from an element with the key “Name” while I could read and write other data to the file perfectly fine. Changing the key to “name” solved the problem.

As far as the Papyrus goes, the bulk of it is MCM magic to handle key assignments, drop down lists and user experience. Perhaps the most important parts are the functions that start and stop posing, so I’ll post them here.

Here is the Papyrus used to show a pose on an actor:

Some things to note:

  • The akTarget argument passed in is determined by looking at the player’s cross-hair reference. If there is an NPC in the cross-hair the NPC is the target, otherwise the player is the target.
  • For NPCs, I take an empty AI package I made called “PackageStop” and apply it with ActorUtil to freeze them in place. I also set “IsNPC” to false, which stops them from head-tracking the player
  • For both the player and NPCs, I set “bHumanoidFootIKDisable” to true, which turns off the inverse-kinematics used to position the legs/feet of actors on uneven terrain.

These settings result in a pose that should be as close to the artist’s intent as possible. You shouldn’t see posed  NPCs engaging in combat or breaking their backs trying to face you while talking. They also should keep their feet flat on the ground, preventing weird leg positions that could result from the inverse-kinematics.

Clearing a pose from an actor is done essentially the same way, but in reverse: restoring the old AI package and turning on head tracking and inverse-kinematics:

Sending the “IdleForceDefaultState” animation event at the end clears the current pose from the actor, returning them to their normal idle state.

The core functionality of this mod was spun up over a weekend, but polishing it to make it user friendly took nearly two weeks. I hope I made these tools intuitive and robust, but I’m sure users will quickly show me the holes when I release it this week.

SKSE Water Detection

Bathing in Skyrim 1.10 is out and I wrote a new way to handle water detection that I thought I’d share.

For some background – something that has been a problem with many of the basic-needs mods for Skyrim is that the CreationKit does not expose a reliable way to detect if an Actor is standing in water.

Early on, someone discovered that there is something in the CreationKit that lets you mark the water as “dangerous water” along with a float that represents the amount of damage per second received while standing in it (which can be set to 0). This is helpful since Papyrus and the CreationKit have an exposed method named IsInDangerousWater that will detect an Actor in dangerous water even if they just dip their toe into it. This is how mods like Realistic Needs and Diseases detects water.

A problem comes up, though, if a mod makes additional edits to WaterTypes. Like all Forms, the changes made last will win any conflict. That means if you load a mod like Realistic Water Two (that makes changes to water) after Realistic Needs and Diseases, the “dangerous water” flag will be set to false and water detection breaks. If you load them in reverse order, water detection works but the water will look like vanilla water.

To fix this problem, people started making “patches” that are ESP files existing solely to set the “dangerous water” flag to true in a way that merges the change with the changes from the water mod. This is how Bathing in Skyrim detected water until 1.10.

This method is fine, but it requires mod authors to write patches for every DLC and water mod combination that users want to use. It’s not complicated but it is tedious. It also requires users to activate several ESPs in their load order for a single mod. Since people have recently been hitting the 255 ESP cap, this presents a problem.

A few months ago, two of the three biggest water mods decided to bundle their mods with other mods and change the ESP names. This made all of my patches worthless. I did not want to re-patch all the water mods/DLC again, so I looked for alternatives.

In a recent release of SKSE, there is a new exposed method of getting the height of the water level in a cell. This is how iNeed started detecting water recently. The idea is that if you know the water level of an area and test it against the player’s position you can tell if they are standing below the water level and therefore standing in water. Theoretically, this solves all the problems with patching and lets people use any water mod/DLC combinations they want.

I tried implementing this method of water detection with Bathing in Skyrim 1.05 but I ran into problems and switched back to patching. My main issue was that I could not reliably detect water in areas that had stepped water levels – for instance, the stairway up to Dragonsreach in Whiterun. The water level reported in the cells was the same even though the water was placed at different heights, breaking the detection in those areas. So the trade off is that I could do less work and support more water mods, but some areas would just be off-limits. I decided not to go this route since I believe it’s a worse overall experience for the user.

More recently I became interested in writing my own SKSE plugins. I was originally playing around with camera controls and thought I might try to find some automatic SKSE way of setting the water to “dangerous water.” I managed to do just that, allowing Bathing in Skyrim 1.10 to take advantage of the new method.

In mzinWaterUtil.dll I expose two Papyrus methods for water:

The first tells you if the “dangerous water” flag is checked or not on a given Form. The second will set the flag to true or false based on the Dangerous parameter.

This is what the SKSE code looks like:

I found that the unknown value “unk075” represents the “is dangerous” flag by dumping all of the data out of a WaterType and comparing a “patched” version vs a vanilla version. I found that unk075 changes from 0 (false) to 1 (true) when patched. unk075 is a UInt8 and I’m not sure if any other flags might get stored there (with bit-sets or whatever) so instead of just hard setting it to 0 or 1, I decided to use bit-wise operations with this bit-mask:

This might be total overkill, but it should produce the same results as water patching when checking the “dangerous water” box in maybe a safer way then setting the UInt8 directly as 0 or 1. I’m also checking that the passed Form is a WaterType before doing any operations since Papyrus has no exposed WaterType Form, making it unenforceable as a type in the Papyrus script itself.

So now there is a way to mark the dangerous water flag dynamically in Papyrus, but it needs to know the Form IDs to do it. So, I created a FormList in the CreationKit and placed all the vanilla Skyrim WaterType Forms inside which gets processed by a script at startup.

This is what the Papyrus code looks like to mark the water:

Pretty simple – it just iterates through the FormList and uses SKSE to set the flag.

For Dragonborn and Dawnguard I just wrote down the Form IDs to add them to the list dynamically. This happens just before processing the FormList:

Game.GetModByName() is awesome since it lets me know if someone has a mod loaded or not. If it returns 255 then the mod is not loaded and I won’t try to add the WaterTypes to the FormList. Since DLC and user-made mods are treated the same, I have a similar block for Falskaar and I can add new ones whenever new user-made mods add new WaterTypes. Mod authors could also write their own methods for this since it’s all in Papyrus.

The changes to the Forms do not stick through a save, so they must be reapplied every time a user loads the game. To do this, in the main Bathing in Skyrim Quest I added a ReferenceAlias for the Player and call this:

Which calls the Quest to check for DLC and process the FormList of WaterTypes.

I’ve been trying to get this same behavior contained within the mzinWaterUtil DLL entirely so that once the game loads it will just automatically patch all the water without the need for Papyrus, but so far I’ve been unsuccessful. Hopefully it’s something I can add in the future so players can just drop the DLL in a folder and magically get patched water for Bathing in Skyrim, Realistic Needs and Diseases, etc without the need for a single water patch ESP regardless of water mods or DLC installed, but so far no luck.

The full source for the Papyrus is available on Git here:

Skyrim Mod Pages and Repos

I’ve added some pages for some mods I’ve made to keep things organized. They should be listed on the navigation bar to the right. I’ve also added the mods and their source files to GitHub and posted links to the repos on the mod pages.

The decision to version mods on GitHub did not occur to me until I started getting deep into Bathing in Skyrim 1.03. There was a bug reported where users were unable to use soap in the inventory until they dropped it on the ground and picked it back up. I looked into this and found there is an issue where scripts attached to stackable inventory items can lose their associations:

To fix this bug, I had to invert the detection of soap-use which required a pretty heavy re-write of the scripts. As I was testing I accidentally overwrote older versions of scripts several times which made it clear pretty quick that I needed some sort of version control to prevent setbacks like that.

All of the script source code is included on GitHub and in the installable .zip files for anyone to use.

Skyrim Modding

I wanted to take a break from C++ for a bit so I started messing around with Skyrim modding.

Begin a programmer, I’m really interested in scripting in particular. Skyrim uses a proprietary scripting language they call Papyrus, which is fairly well documented on the CreationKit wiki:

I have spent an absurd number of hours with Skyrim and have messed around with modding in the past, but I usually don’t release anything since people can be (understandably) vicious if you screw up their game. I made sure to do a lot testing and I added as much polish as I could before releasing it.

It started as a fork from another mod that I wanted to polish up and add some features to. I took the bathing component of this existing mod – Drink Eat Sleep Bathe – and separated it out. I also changed some of the mechanics and bonuses to fit my own preferences. I added a FOMOD installer and uploaded it to the Skyrim Nexus, which you can find here:

Included in the zip on the Nexus are all of the source files for the scripts, in case anyone is curious. Much of it existed already from the previous version of the mod, but I made some improvements here and there. If anyone has feedback I’d be eager to hear it since finding quality examples of Papyrus scripts is not easy.

It’s actually unexpectedly nerve wracking to release something like this. Even after all of my testing, I’m afraid of breaking people’s games or ruining their experiences, so I’m paying really close attention to the comments to look for any reported problems. So far, people have been giving me positive feed back, which is nice. I already have a couple of feature requests that sound like alright ideas.