This guide will show how you can setup your custom weapon mod in such a way that I can fully support it in Ammo HUD.
This is also viewable on my site: https://pxcnet.xyz/starfield/guides/UIIconLinkage.html
Problem Statement
Bethesda made Starfield's weapon icon on the HUD more complicated than it needed to be but at the same time making it limited.
The only information that is sent to the HUD for the weapon is as follows:
- uClipAmmo: The size of the ammo clip for the current weapon
- uTotalAmmo: How much ammo the player currently has in their inventory for the current weapons ammo type
- bDisplayAmmo: Boolean determining if the ammo counts should be shown or not
- bShowAmmoAsPercent: Boolean determining if the ammo is a percentage or not (the Cutter for instance is a percentage)
- sWeaponName: The full weapon name
- uExplosiveCount: The amount of equipped throwable (grenades, mines, etc) the player currently has in their inventory
- uExplosiveIndicatorType: Number that correlates to the throwable type
- sExplosiveName: The full name of the equipped throwable
- sIconLinkageName: This is the unique name for the currently equipped weapon which is used to know which icon to use
Now that’s the data bucket from an event named “WeaponData”, this event seems to be built into the engine natively and isn’t linked to a Papyrus script. I had hoped I could extend this to include the name of the currently equipped weapons ammo, but it’s pretty clear that it’s a native event that Bethesda would have to change for me to use it. I’m sure SFSE could do it as well, but since I would like to keep this usable by xbox users, I don’t want to require SFSE for this mod to function.
The only property that is passed to the weaponicons interface files is: sIconLinkageName
Which means I basically have a single string to key off of for the ammo icon, this is fine for vanilla weapons and weapons which do not have the ability to change their ammo type via a weapon attachment. This falls apart if a custom weapon allows for changing the ammo type as it would mean that the ammo icon and label would be wrong when the weapon has an attachment that changes its ammo type.
The alternative to adopting doing it the way this article explains is mods like Ammo HUD would have ammo information for some weapons, but not all, so it would result in inconsistent icon display.
Patching and Adoption
Unfortunately this isn’t something I can just create patch mods for as that would be modifying someone else's mod and I can’t set a small master as a master to another small master ESM.
This means I would need mod authors to adopt doing it this way, both on custom weapons but also other weapon icon mods.
If in the future Bethesda adds ammo data to the event properties then I plan to make a much more dynamic version where it will just key off the actual ammo name instead but until that happens this is the only way I can fully support custom weapons in Ammo HUD.
Downside of Adoption
The primary downside of mod authors adopting this method is that then their mod would rely on Ammo HUD (or other weapon icon mods) to provide their users a weapon icon entirely. Meaning if the user did not install a weapon icon mod they would just have a blank spot on the HUD and favorites menu. I know there are a lot of weapon mods which just use the vanilla linkage names so that there is at least an icon for the UI. If you don’t want to rely on another mod to have this functionality then you could still create a custom linkage keyword, but set it to a vanilla value and then just create a patch ESM which changes just those UI linkage keyword values to a custom value which then I could support.
The other potential option is I could write a guide on how you can create your own weapon icon files in your mod, and users would be covered with your mod being self contained and then if they wanted Ammo HUD they would just install the loose file version or move it to the end of their load order to overwrite your included file with my files so they can have the full support for other mods too. I will look into doing this as well so the modding community has options.
Instructions for Mod Authors
Below are two sections which show how a mod author can add support in their mod which allows me to fully support their weapon’s icon plus the ammo icon. I’ve included instructions for both scenarios, single ammo type and multiple ammo types. This is using CreationKit but it could also be done in xEdit (but I won’t be including instructions for xEdit).
NOTE: For all of the examples below, I will be using the Eon pistol to demonstrate what to set in CreationKit
Basic Creation Kit Overview
This is likely remedial for most mod authors who already make custom weapons, but I decided to add this for posterity or for people trying to get into creating custom weapons. This will only cover how the “sIconLinkageName” property is set.
In order to set whe sIconLinkageName property, you must create a new UI_Icon keyword.
In the tree view, navigate to: Miscellaneous\Keyword\UI Icon Linkage Name
You will see existing UI_Icon_[WeaponName] keywords for each weapon.
Here is the keyword for the Eon:
The UI interface files use this linkage name to load a graphic that is tied to the same name essentially.
This is what it looks like in game with the sIconLinkageName and my ammo icon/label:
Single Ammo Type Weapon
This is the most simple way to add support, it is how the vanilla weapons work.
NOTE: You should ONLY use this if your weapon will never change ammo types with an attachment.
You just create your UI_Icon_[WeaponName] as shown above.
Then you just add it as a keyword to your WEAP form.
Here is how its done with the Eon:
Thats it! Now when the UI interface loads, it will get your linkage name.
All that's left now is for support for your custom weapon to be added to either my Ammo HUD mod or other weapon HUD icon mods.
Multiple Ammo Types Weapon
This is more complicated but ultimately shifts where the linkage name is set.
NOTE: You should use this if your weapon can change ammo types with an attachment.
The major difference here is you wont be adding the UI Icon keyword to your WEAP form, instead you will be adding it to your OMOD forms.
Here is the Eon with the keyword removed:
The first thing you will want to do is create a UI_Icon_[WeaponName] keyword for every ammo variant of your weapon, in this demonstration I only needed to create a second one as we are using the default one for the standard weapon.
Here I have both keywords created:
- UI_Icon_Eon: Standard version of the weapon
- UI_Icon_Eon43: Alternative version of the weapon that is using .43 Ultramag ammo
In this demonstration I modified the tactical mag mod_Eon_Mag_Tactical OMOD form to change the Eon to use .43 Ultramag ammo.
Once I did that I then added two pkKeywords to the Property Modifiers section, one will be an ADD and one will be a REM
The ADD should be the UI Icon keyword that correlates to the ammo this OMOD is setting (see below)
The REM should be the UI Icon keyword that its being changed from (see below)
The reason for having to add both keywords is that you don’t want a conflict, if you are adding one then you must remove the other one.
Now the annoying part for this is, if you have other OMOD forms which either don’t use this alternate ammo, or you have multiple OMOD forms which change the ammo type then you will have to do this for every OMOD form that does this change.
IMPORTANT NOTE: If your weapon has multiple attachments which change the ammo type then you would have more than two on each OMOD. The rule of thumb is lets say you have 4 different ammo types, then you would have one ADD and 3 REM pkKeywords
In this demonstration I only have one OMOD that changes the ammo of the base WEAP form, but you also must do this for all OMODs that use the standard ammo as well. This is for the same reason that you do not want a conflict and we have removed the keyword from the WEAP form, so something must also add it for the standard attachments (and if you have a ‘none’ OMOD as well)
Obviously in this case we are doing an ADD for the standard keyword UI_Icon_Eon and a REM for the alternate keyword UI_Icon_Eon43 as this attachment uses the standard ammo type.
Once you have populated both of these keywords on all of the OMOD forms that change the ammo type, then you are done.
This is a side by side of what it looks like in game with my custom ammo icons/labels and the sIconLinkageName property when I have two Eons, one with the tactical attachment and one with one of the other attachments instead
Now obviously this means that any weapon icon hud mod will need to support both keywords, but this is fairly easy to do.
If you are working with me or another mod author that does weapon icons, it would be helpful to provide all the keywords your weapon mod uses and what ammo they correlate to. It just saves us having to load it in CreationKit or xEdit to find that information.
Questions/Contact
If you have any questions about this feel free to contact me on here or any of my other Socials
You can also submit feedback or requests to me using this form.
0 comments