🔫ItemAdditions: Weapons
Adding weapons
Last updated
Adding weapons
Last updated
Published: July 08. 2023 by manavortex Last documented update: Feb 07 2024 by @manavortex
This guide will teach you how to change the ArchiveXL item addition process to make it work for a weapon.
For a much more detailed step-by-step guide, check New Iconic Weapon: Step by Step
For an overview of weapon properties, check Cheat Sheet: Weapon BaseStats
For an overview of weapon audio profiles, check Cheat Sheet: Weapon Audio
Weapons work a little different from regular ArchiveXL items, starting right at the root entity. With the help of @Apart and psiberx, I was able to figure out the process and document it for you.
Start by finding the .app file of an original weapon of the type you want to make (Theres a list here) and adding it to your project. We will change that file, rather than assembling anything by hand.
In the app file, you can also find the value for the yaml file's $base property:
You need the correct mesh entity to go with your appearance file. You can find them under base\weapons\ - search for the name of your weapon, or just navigate through the folders.
This file makes the weapon show up in photo mode. Instead of going into the PartsValues, it will be linked in the app file's root as baseEntity (there's a screenshot below). Leave it alone for now, it's easier to make the appearances working correctly in the .app file and then copying over an entire component array.
For guns with a receiver, you have to edit two .app files instead of just one. The name of the extra file will contain _rcv.
Instead of a root entity file, you need to point your factory.csv directly to your iron's app file (the one from the section above).
An equipment item's lookup chain goes from the appearanceName in the yaml to the root_entity, where the appearanceName will lead to the correct appearance in the .app file.
With a weapon, all that happens through visualTags.
Native weapons often use one shared VisualTags to reference multiple appearanceName and randomize the result. If you want to use a specific native appearance present in a VisualTags native group, you can use appearanceName to specify which. E.g:
visualTags: [ Neon ]
appearanceName: neon2
visualTags (violet): Must match the visualTags in your .yaml file. If multiple entries match, one will be chosen at random.
Unlike with an entity file, the appearance name doesn't matter. You can name all of them foo, and as long as you had the visual tags right, it still works (I would advise against it, though)
As the process is finicky and there can be all sorts of sudden unexpected behaviour, here's the best way to go about this.
The list links you to sections of the guide which tell you to change things. Optimally, you do a dry run with one appearance to make sure that something shows up in the game at all, then start fine-tuning, but you do you.
Here's what's worked for me (@manavortex):
Find the .app file of a suitable base weapon, add it to your project, and rename it. Don't change anything for now, future you might need the original data for troubleshooting later.
Find the correct .ent file. It might be linked in the .app's baseEntity field. If not, you can find it with the following Wolvenkit search query:
Optimally, the number of components in the .ent file should be the same as in any appearance's component array (red arrow on the screenshot above).
If it's not, that could indicate that you have the wrong .app file. It could also mean nothing, but if you run into trouble in step 6, this might be why.
Configure the yaml as described here
Set up one (1) appearance for testing by assigning the correct visual tags. Do not delete the other appearances yet, future you might need them for troubleshooting.
Start the game and make sure that you can spawn a custom weapon with the appearance you picked and that it
shows up in inventory/photo mode
shows up in first person
If that's not the case, check the (see the blue box in step 2).
If that doesn't help, you may have taken the wrong .app file - go looking again.
You haven't changed anything at this point: the goal here is to make sure that your visual tags are correct and that you can spawn a weapon addition.
It's crucial that you make this work — anything you do after this point will add complexity and make troubleshooting more difficult, so this is where you shore up your bases.
Optional: You just added a weapon to the game that didn't exist before. Take a moment to bask in the success!
Custompath your :
Create a copy of the file and move it to a custom folder
rename it
Change the baseEntity path in your .app file
Optional, but recommended: Repeat step 5 and make sure that everything spawns
Now it's time to actually change things. Open your appearance's component array and make sure that the MeshComponents load your custom stuff (anything that has a depotPath pointing to a .mesh file).
After you've changed the paths, launch the game and make sure that your weapon
shows up in your inventory with your meshes
shows up in first person with your meshes
shows up in photo mode at all (it shouldn't be invisible, but will still have the default appearance)
all parts and extra meshes are visible
is in the right position in regards to V's hands (at least as much as for the Tactician shotgun)
all parts and extra meshes show the correct appearances
Fix any issues that might arise before you proceed.
This is why we kept the original appearances around: if you run into any issues here, you can compare your stuff with the original, un-changed game variants.
Don't forget that you can
split off meshes or submeshes for individual pieces (for chunkmask hiding or extra materials)
add more components (duplicate existing ones, or copy them from the mesh entity)
Once everything works, delete all the default appearances, then duplicate and adjust the one you customized to show your color variants.
Now, finally, copy a working appearance from the .app file to your . This will make your weapon show up in photo mode.
Luanch
If you wish to add a custom icon, follow the steps in the corresponding guide.
To make your own HUD icons for the lower right corner, check here.
You can change which weapon audio preset your custom iron uses by changing the following property in the .yaml (see a list under Cheat Sheet: Weapon Audio):
You can set up throwing weapons just like a regular weapon, but the projectile (when you throw it) will default to . Check here for how to have custom projectiles.
When exporting an existing weapon mesh for your custom weapon, make sure to uncheck LOD Filter — the lower LOD mesh is used for calculating the hitbox.
This is especially important if you add a melee weapon of a different size than the original: if you only replace LOD 1, there will be a separate, invisible hit box that does not align with your new weapon.
In Blender, put your custom mesh in both LODs.
If your weapon is significantly bigger than the original one, you'll notice that the hitbox won't auto-scale with your mesh. If you know how to solve this problem or want to brainstorm, hit up @Mx_OrcBoi on Discord!
First of all, unequip and re-equip the item. If that doesn't fix it, try respawning it.
That is due to a base game change (bug?): iconic weapons don't show fluff texts anymore (huge thanks to @RMKSoundSystem on Discord for learning that).
To make it work again, you need to either
Add the following line to your .yaml:
Set $base like this:
Make sure all the items under "resolvedDependencies" are deleted in your appearances, especially if they are using "Soft" or "Embedded" flags. The game might load vanilla meshes instead of your own meshes.
