In order for YASTM to support a certain soul gem, it needs to know its capacity and contained soul sizes. When the player fills a soul gem in vanilla Skyrim, the data on the trapped soul is stored in a separate list. This keeps the base form, but faulty handling of this list led to a number of bugs, like losing souls when dropping the item or silently "merging" the trapped souls when there are several soul gems of the same type.

YASTM (like GIST) works around this by distinguishing soul gems only by their base form. Since the game handles base forms perfectly well, it's a much safer way of storing such information. However, the tradeoff is there's no reliable way to answer questions like "I have a common soul gem and I want to fill it with a petty soul, which form do I replace it with" using only the information provided in ESPs.

Enter the configuration files, the subject of this article. Every individual configuration file* resides in the game's "Data" folder (and only in that folder, it does not look for files in subfolders) and their names must have the format "YASTM_<whatever>.toml". They're written in TOML v1.0. You shouldn't need to read the TOML specs to write a configuration file though, but if you're curious, here you go.

*There's also a global configuration file called "YASTM.toml", but you normally don't need to touch this file. It stores data like which global variable form stores a particular configuration setting.

For this guide, we're going to tackle the most complex scenario: adding support for a reusable black soul gem that can contain both black souls and white souls. For simplicity, we're going to just use the Black Star from the vanilla game. This will utilize almost all the features available in YASTM, so it makes an ideal tutorial.

Let's get started creating the new forms first:

Creating Forms #1
Required software: xEdit and your favourite text editor.

For xEdit you can use Creation Kit instead, however, Creation Kit can't easily make ESL-flagged ESPs without opening it again in xEdit, so you might as well stick to xEdit.

For the text editor, I use Visual Studio Code with the Even Better TOML extension. If you want code highlighting you need to pick an extension that supports at least TOML v1.0. Windows Notepad is also fine if you don't want to install anything.

Creating Forms #2
Find the soul gem you want to add support for. At this point, take note of how many forms you'll need to add, and check if any you need already exists. For example, in vanilla, both the filled and unfilled variants of the non-reusable soul gems are already created. You should use the existing forms if they exist and only create the ones that don't.

The Black Star only has the base empty form. Since this can store black souls, you'll need a variant that's filled with a black soul. Since we want it to also store white souls, you'll need to have variants for The Black Star filled with petty, lesser, common, greater, and grand white souls. This totals to 7 variants of The Black Star, and 6 you'll need to make.

Creating Forms #3
Right-click the original soul gem, and pick "Copy as new record into". Make a new editor name. I normally use <original_name>FilledPetty, <original_name>FilledLesser, so on, until <original_name>FilledWhite (white grand) and <original_name>Filled (black). The max-filled version (whichever size it ends with) will end with just "Filled" to keep it in line with the vanilla naming conventions.

For our example, we'll be naming the record "DA01SoulGemBlackStarFilledPetty". I suggest you do not create the forms for other contained soul sizes yet, since this is a reusable soul gem. You'll see why in a bit.

Pick the ESP you want to add them to (I normally use ESL-flagged ESP if making a new one), then proceed.

Creating Forms #4
There are 3 fields on the form you'll want to pay attention to: value, contained soul (SOUL) and linked soul gem (NAM0). The NAM0 field is only important when dealing with reusable soul gems.

First, change the value of the SOUL field to Petty.

Because this is a reusable soul gem, the game needs to know which soul gem form to replace the form with when you use the soul gem (for charging or enchanting). YASTM patches things so that it uses the NAM0 field, so change the value in the NAM0 to the empty soul gem form "DA01SoulGemBlackStar". This field is also why I mentioned not to copy the other variants in step #3, since you'll otherwise need to fill it for each size if you copy from the empty form instead of this one.

Lastly, the value field. If you don't care about buying/selling prices, you can skip this, but basically the game engine does not take the contained soul sizes into account when calculating its value. The only vanilla soul gems that actually have a modified value are the max-filled variants of the non-reusable soul gems.

YASTM fixes this by setting the value according to a formula. You don't need to follow this formula if you dislike it, but I'll just present it as an option if you lack a better opinion.

First I'll list the "true" values of each soul size:

None = 0
Petty = 250
Lesser = 500
Common = 1000
Greater = 2000
Grand = 3000

The max-filled value of a soul gem with capacity "grand" will have the ratio of 3000/3000 = 1.0. Partially-filled soul gems will have this ratio reduced, so common-filled grand soul gems will have the value 1000/3000 = 1/3 of the maximum value.

However, soul gems also have a base value, so we add this separately.

The final version of the value formula used in YASTM is thus:
Value = BaseValue + (Ratio)(MaxValue - BaseValue)


(We round up the value if it's not an integer.)

For The Black Star, we don't actually have a max value defined in vanilla, so we pick a value. For our example, we just use 2000, which is twice the empty form's value.

For our petty-filled Black Star, we calculate the value to be 1000 + (250/3000)(2000 - 1000) = 1083.33 or 1084. Enter 1084 into our Value field.

Creating Forms #5
Copy the petty-filled soul gem form you've just made and add the variants for lesser, common, greater, grand, and black-filled soul gems, modifying Value and Contained Soul fields as you go.

Once that's done, keep xEdit open so we can start writing our configuration file.

Writing the Configuration File
Create a new text file named "YASTM_<whateveryouwant>.toml" in your game's Data folder (if you're using MO2, create a new empty mod and put this file in there) and open it up in your text editor.

Then add these lines:

[[soulGems]]
id = "The Black Star"
isReusable = true
capacity = 6
members = [
    [0x63b29, "Skyrim.esm"], # Empty
    [0x837, "YASTM.esp"],    # Filled
]

"[[soulGems]]" should be placed at the beginning of each soul gem group.

The "id" key is primarily used for debugging, however, future updates to YASTM may require this to be unique, so try to pick a unique name. I normally just use the in-game name of the soul gem unless it collides with another name.

The "isReusable" key is technically optional and defaults to "false" if missing. All it does right now is change the priority of the soul gem group, which can also be done in the "priority" field (not shown, but we'll get to that in a bit).

The "capacity" key contains the capacity of the soul gems in this group. Since The Black Star is a black soul gem, we give this the value of 6. It can be any integer from 1 to 6. This number must match the capacity in the soul gem form or the entire group will error and not be added. Both 5 and 6 translates to the "Grand" capacity (since there is no "black" capacity in the game engine).

The "members" key is a very important key. It contains an array of [formID, pluginName] pairs that points to the actual loaded form. The first member in this list is the empty soul gem form. Since this form is a black soul gem form, we only have two members: the empty form and the filled form.

The form ID provided is the local form ID of the soul gem, independent of the load order. Look up the load order-dependent form IDs from xEdit, then convert.

If the form is in a normal ESP/ESM, strip the first two hex digits and write out the rest. If the form is in an ESL/ESL-flagged ESP, only keep the last 3 digits. Skyrim.esm is the first kind, while YASTM.esp is the second. The "# Empty" and "# Filled" are just comments and added for readability. They aren't required.

The above alone will allow YASTM to fill our Black Star with black souls. In order to allow it to accept white souls, create another soul gem group. This time, we're creating a grand soul gem group.

[[soulGems]]
id = "The Black Star (white)"
isReusable = true
capacity = 5
members = [
    [0x63b29, "Skyrim.esm"], # Empty
    [0x833, "YASTM.esp"],    # Petty
    [0x834, "YASTM.esp"],    # Lesser
    [0x835, "YASTM.esp"],    # Common
    [0x836, "YASTM.esp"],    # Greater
    [0x839, "YASTM.esp"],    # Filled
]

Notice that we've changed the "id" key slightly to avoid future collisions. Also note that we've changed the "capacity" to 5 (grand). Like all grand soul gems, we need six members.

In order for our "dual soul gem" to work, the empty member of these two soul gem groups must be identical (note that the plugin name is case-sensitive and they have to match as well). Secondly, the max-filled member (the last member listed) must not match. Notice the form ID is different compared to our previous group. Once these two requirements are satisfied, YASTM will "magically" create a dual soul gem group that supports getting filled with both black and white souls.

Save this file and try opening up the game. Once the main menu finishes loading, Alt+TAB out of the game and check SKSE/YASTM.log in your "My Games/Skyrim Special Edition" folder. Read through the logs and see if it produces any errors. Check the soul gem mappings to see if it produces something you expect. If something's wrong, the log should tell you why. If nothing's wrong, you're done!