🔫ItemAdditions: Weapons

Summary

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.

Wait, this is not what I want!

• 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

Prerequisites

• You are familiar with ArchiveXL item additions as per the "Adding new Items" guide

Selecting the base

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:

Getting the mesh_entity.ent

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.

Factory: .app instead of root_entity

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).

Appearance selection

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.

YAML: Define the field:

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

.app file: Define the visual tag

visualTags (violet): Must match the visualTags in your .yaml file. If multiple entries match, one will be chosen at random.

Step by step

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):

1. 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.

2. 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:

base\weapons > entities > .ent

1. Configure the yaml as described here

2. 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.

3. Start the game and make sure that you can spawn a custom weapon with the appearance you picked and that it

   1. shows up in inventory/photo mode

   2. shows up in first person

If that's not the case, check the mesh entity (see the blue box in step 2).

If that doesn't help, you may have taken the wrong .app file - go looking again.

1. Optional: You just added a weapon to the game that didn't exist before. Take a moment to bask in the success!

2. Custompath your mesh entity:

   1. Create a copy of the file and move it to a custom folder

   2. rename it

   3. Change the baseEntity path in your .app file

3. Optional, but recommended: Repeat step 5 and make sure that everything spawns

4. 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).

5. After you've changed the paths, launch the game and make sure that your weapon

   1. shows up in your inventory with your meshes

   2. shows up in first person with your meshes

   3. shows up in photo mode at all (it shouldn't be invisible, but will still have the default appearance)

   4. all parts and extra meshes are visible

   5. is in the right position in regards to V's hands (at least as much as for the Tactician shotgun)

   6. all parts and extra meshes show the correct appearances

Fix any issues that might arise before you proceed.

1. Once everything works, delete all the default appearances, then duplicate and adjust the one you customized to show your color variants.

2. Now, finally, copy a working appearance from the .app file to your mesh entity. This will make your weapon show up in photo mode.

3. Luanch

If you wish to add a custom icon, follow the steps in the corresponding guide.

Your own HUD icons

To make your own HUD icons for the lower right corner, check here.

Weapon Audio

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):

# for guns etc
weaponAudio: wea_set_achilles

# for melee weapons
audioWeaponConfiguration: audio_melee_metadata_katana

Custom throwing weapons

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.

Editing weapon meshes

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.

In Blender, put your custom mesh in both LODs.

Troubleshooting

My weapon is fully invisible, no matter what I do!

First of all, unequip and re-equip the item. If that doesn't fix it, try respawning it.

My iconic melee weapon ignores its localizedDescription!

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 a blueprint:

Add the following line to your .yaml:

  blueprint: Items.Iconic_Melee_Blueprint

change the base type

Set $base like this:

  $base: Items.IconicWeaponModBase

My weapon is spawning as the original weapon/my mesh edit isn't reflecting!

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.