HomeDiscordGitHub
Page cover
Edit

New Iconic Weapon: Step by Step

Summary

Published: December 2023 by destinybu Last documented edit: Feb 07 2024 by mana vortex

We'll be making a fully featured new Iconic weapon in this guide, which is designed for first-timers and goes into details into every aspect about weapon modding. (not appearances)

Wait, this is not what I want!

Prerequisites

Before beginning, ensure you have the following software installed and properly set up:

  1. WolvenKit (8.12+) - Installed & Setup

  2. MLSB (MultiLayerSetupBuilder 1.6.7+) - Installed & Setup

  3. A text editor: Notepad++ or, if you want to get fancy, Visual Studio Code

  4. Cyberpunk 2077 - 😑

  5. Core mods: ArchiveXL, TweakXL, Red4Ext

  6. Optional: RedHotTools, RedMod

If you are stuck, refer to the Troubleshooting (Check this when you're stuck) at the end of the page.

Step 1: Create a New Project in WolvenKit

Each Iconic weapon is a variant of a base weapon, with an hidden (from the player) mod. This "hidden" mod contains a statModifiers array (to list all the stat changes this Iconic will have from the base weapon) and an OnAttach array. The OnAttach array is where you'll want a GameplayLogicPackage to go. You may or may not need to define conditional effectors in there, but if you want your weapon to have the customary Iconic yellow description then be aware that there is where it's written (in the UIData of the GameplayLogicPackage).

$base: Items.IconicWeaponModAbilityBase == $type: GameplayLogicPackage

Step 0: Understanding the structure

The rest of this guide will hold your hand through a deep dive, step-by-step, of your first custom Iconic made from zero. If you get lost through it, or if you'd rather find your own flow, you'll be well served by returning to check the code of an Iconic weapon already in the game (as you'll be building up from a base weapon in the same way, and it's solid footing).

RedMod tweak files are much more legible than a "TweakXL override" from WolvenKit for this, as each step there inherits redundant stuff passively and won't clutter your screen. Plus you'll see inlines content directly without having to track down flats. Just use something to search the insides of the files for the definitions (VS can, or some free tools like Agent Ransack)

Step 1: Create a New Project in WolvenKit

  1. WolvenKit (8.12+): Installation & Setup Guide

  2. MLSB (MultiLayerSetupBuilder 1.6.7+): Installation & Setup Guide

  3. Text Editor: Notepad++ or Visual Studio Code

  4. Cyberpunk 2077

  5. Core Mods: ArchiveXL, TweakXL, Red4Ext

  6. Optional: RedHotTools

Step 1: Create a New Project in WolvenKit

Open WolvenKit and create a new project. This will be the foundation for your new iconic weapon mod.

Create a new WolvenKit project as shown here
A clean project should look like this (as of Wolvenkit 8.12, your interface may look different)

Step 2: Choose the Base Weapon

Decide on the weapon you want to modify to make a new new iconic.

Step 2: Choose the Base Weapon

Select a base weapon for your iconic weapon. For this tutorial, we'll use 'Unity' with item ID Items.Preset_Unity_Default.

For this tutorial, we will use the gun 'Unity' as our base (Items.Preset_Unity_Default). If you want to use a different weapon, you can refer to Spawn Codes (BaseIDs/Hashes) or find a list of all in-game items here.

To understand how the base gun works, open the Tweak Browser in WolvenKit and search for Items.Preset_Unity_Default.

Open the Tweak Browser & search "Items.Preset_Unity_Default"

Step 3: Create a TweakXL Override

In the tweak browser, find Items.Preset_Unity_Default, right-click it, and select "Add TweakXL Override". This step is crucial for customizing the weapon.

Red arrow = Tweak Name, where you can override it. Blue Box= Details about selected tweak. White arrow = Overridden (New) Tweak

To read more about Tweak modding, check TweakDB: Game database. This isn't necessary for understanding this guide!

Step 3: Editing and understanding your new tweak

Before you start with this section, make sure to read the block below!

.yaml files use indentation (the number of spaces at the beginning of a line) to organize entries in groups. This is easy to break!

If you run into problems, you can check your file on yamllint.com. If that doesn't help, see if red4ext/plugins/TweakXL/TweakXL.log has any hits for your mod.

Open the overridden tweak file in a code editor of your choice (such as Notepad++ or VS Code). You will be presented with a .yaml file containing roughly a million fields.

Step 4: Open the Overridden Tweak

Open the overridden tweak file in a code editor like Notepad++ or VS Code. You'll see a .yaml file with various fields.

"Items.Preset_Unit

How does it work?

For first time modders, understanding all this in one go will be difficult. You can just keep these explanations handy and revisit them when required.

The .yaml file may seem complex at first glance, but the actual structure is extremely simple. Your weapon has properties – those stand on the left side of the :, such as ammo. The properties have different values, and those stand on the right side of the :, such as Ammo.RifleAmmo. Note: For first time modders, understanding all this in one go will be difficult, so keep these explanations handy and revisit them as and when required)

Step 5: Understand the .yaml File

The .yaml file might seem complex. Here's a breakdown of key fields from another weapon tweak (Items.Preset_Sidewinder_Default). Keep these explanations handy for reference. (Thanks to BuffMcMuff)

An annotated example

Here's a breakdown of key fields in a different weapon (Items.Preset_Sidewinder_Default) : (Thanks to BuffMcMuff)

Step 4: Making a new weapon

4.1: New weapon, same as the old weapon

Making a new weapon is fairly simple. In your tweak file, change the Item ID in the very first line to "Items.Hand_Of_Midas" and save (Hotkey: Ctrl+S).

Step 6: Create a New Weapon

Change the item ID at the top of your .yaml file from Items.Preset_Unity_Default to Items.Hand_Of_Midas. Save the file to create your new weapon.

That's it, you've created a new weapon now. This weapon will look & behave exactly like the Unity handgun, but trust me, it's new. To test it out, boot up your game and load any save.

At this stage your tweak file exists only in your mod's project folder. It can't do anything in game from there, so you will need to use the "Install" button to install your tweak file to the game directory. Then you can test it.

To test it out, boot up your game and load any save.

Now open up the CET Console:

Red arrow = Open CET Console. Green arrow = Command to spawn in the newly created gun

Type in the command below and hit Enter.

Your newly created weapon is now in game.

You can now see your newly created weapon in your inventory.

Unfortunately, there is no way to tell it apart from the Unity handgun.

We'll get to fixing that, but first, a little cleanup: open up your WolvenKit & rename your overridden tweak file to "hand_of_midas.yaml". We will store all the edits that need to be done to our new weapon in this file.

4.2: Changing the carbon copy

Let's change something that will differentiate our weapon from the default Unity.

To do this, open your renamed tweak file & find the crosshair tag (hotkey: Ctrl+F). Replace it as shown below, and save your file.

Now hot reload your game (Insert how to link here) or close it, reinstall your mod in WolvenKit & relaunch your game (From here on, this will be referred to as hot reload).

Spawn in both the Unity & Hand of Midas using the CET console:

Default Unity crosshair
Hand of Midas crosshair

You should now be able to see that both the Unity & Hand Of Midas, although otherwise identical, now have different crosshairs.

How did we figure out the crosshair ID?

How do we know that it's called "Crosshairs.Tech_Round" ?

Method 1: The REDmod DLC

If you have the REDmod DLC installed, you can use a text editor like Notepad++ to do a full-text search under Cyberpunk 2077/tools/REDmod. By searching for crosshair:, you can find all value assignments in the game files.

Method 2: The Wolvenkit Tweak Browser

By searching for "Crosshairs." in the Tweak Browser. Most things we find inside the weapon tweak will be searchable within the Tweak Browser, and some within the Asset Browser.

List of crosshairs obtained with a Tweak Browser search

Editing the Tweak will allow us to modify all of our gun's behaviors, and I encourage you to play around with these.

Step 5: Removing redundant code

We're only changing a single property in the Hand of Midas. For that, we have a tweak file with more than 200 lines of code. Can't we do this in a better way?

We can, and we should!

In later steps of this guide, you'll need to look up properties. Either keep a copy of your full tweak file (e.g. on your desktop), or refer to An annotated example above.

Using $base instead of $type

As shown above, when using $type to define a tweak, we need to add all the required properties for the type, but when using $base to define one, we only need to add the properties we are changing, the rest are taken from the parent.

Now go ahead and change it so we use a $base & only define the crosshair. Your entire tweak should now look like this:

Step 6: The personal touch

What good is a new gun without a new name? We need to tell our game about these.

  1. Open your WolvenKit project and navigate to the archive folder

  2. Create a new folder named after your mod, for example midas_collection

  3. Within this folder, make a subfolder named localization

mod name folder & localization folder

How does the game assign display names?

In your full tweak file, search for the field called displayName. You'll likely encounter something like displayName: LocKey#49794.

This connects the displayName property of your item with a locaization key, which is the mechanism that the game uses to support multiple languages. Think of the LocKey of a list entry, with different lists being used for different languages.

If you want to take a look at these lists, use WolvenKit's LocKey browser or search for onscreens.json.

LocKey Browser search for LocKey#49794

So we edit onscreens.json?

Good thinking, but no. In Cyberpunk, only one mod can edit any given file. That is why ArchiveXL exists, and we'll use it to create a new translation entry for us.

Place a dedicated en-us.json file in your midas_collection\localization folder. This is where we'll add our own translation entries – after that, we only need to tell ArchiveXL about the file and lean back.

Red arrow = localization json added correctly. Green arrow = add new element in the json. Yellow arrow = key fields in new entry

Setting up a localizationKey

Open the file in Wolvenkit and create a new entry in localizationPersistenceOnScreenEntry. It has the following properties:

Property name
your value
explanation

femaleVariant

Hand Of Midas

the default translationse

maleVariant

only set this if you want to show a different translation when your item is equipped by a person of the male body gender

primaryKey

0

The actual entry in the translation list, make sure to set this to 0 so that it's autogenerated

secondaryKey

MC_gun_name

The key used in tweak files to identify this translation string

secondaryKeys must be globally unique, or they will overwrite each other.

Create another entry with the secondaryKey of MC_gun_description and write a little fluff text for the description.

For more detailed guidance on these properties, check out the ArchiveXL Wiki.

Tell ArchiveXL about our new translation file.

In your WolvenKit project, go to the resources folder and create a plain text file with the following contents:

Rename this file to midas_collection.archive.xl.

Wolvenkit will move the .xl file to the same directory as your mod's .archive file, where ArchiveXL will see and process it.

Next, revisit your "hand_of_midas" tweak file to establish the weapon's name and description in the game.

Add the following lines under the existing properties:

This localizedDescription: is not the yellow text you see on the weapon, but the red-colored description that is shown in the Inspect screen. The text that is shown (as yellow-colored) on the weapon is instead defined in the UIData of the Iconic Mod (at Step 12)

These lines set the display name and the description of your weapon using the keys defined in your localization file. The values on the right side of the : must match the secondaryKey values from your en-us.json file and be globally unique.

After completing these steps, install your mod and launch the game. Your new weapon, "Hand Of Midas", should now appear with its unique name and description, fully integrated into Cyberpunk 2077's multi-language environment.

Name & Description of the gun are now taken from "en-us.json" that we've created

Step 7: Make it Iconic

To elevate the 'Hand of Midas' to its iconic status, we need to modify the .yaml again, where we set all of the gun's unique features:

The new things you're seeing are arrays, which is a technical term — you can think of them as lists, since they can hold multiple items.

You can read more about how array operations work in TweakXL.

statModifiers will hold all the stats for your gun. from recoil to damage. Since the $base: Items.Preset_Unity_Default already defines statModifiers, and we'd like to keep those. So we're adding an entry to the list, using!append-once followed by the new entry Quality.IconicItem.

This makes the weapon iconic, which means:

  • it has a fancy golden background

  • there's a dialogue box when you disassemble it

To prevent it from being disassembled, we also add IconicWeapon to its tags array.

Go test

Once these modifications are in place, install your mod and enjoy the newfound Iconic status of the 'Hand of Midas' in the game.

Setting "Quality.IconicItem" will give it a special background in the inventory & also specify that the item is Iconic.

Technically, you've already made a new Iconic weapon & I should call quits on this tutorial, but it's never as easy as that, is it? Give yourself a pat on the back & onto the next step.

Step 8: Finishing up the Tweak

There are a lot of values to play around with in a tweak file. You are often better off leaving most of them alone. These are some properties you probably should look at when designing a gun.

  1. Blueprint (mandatory change for iconic weapons)

  2. Item Quality (optional)

  3. Buy & Sell Price (optional) (fixed value example)

Step 9: Making an Iconic Mod (Special Ability & Stats)

The main thing that makes an iconic weapon so special is its iconic mod. These are like any other weapon mod, but hidden from the UI. They carry the Stat changes from the base model of the weapon, the golden text description on the UI Tooltip and any dedicated Effectors.

Before you start hacking up your own, it is very important you have a look at the existing Iconic Mods in game.

For now, let's look at Items.Preset_Lexington_Wilson (also known as "Dying Night").

A big part of tweak modding is exploration — poking through tweaks until you find just the right thing to copy or change, or looking for something specific in hundreds of files.

Wilson's iconic iron

The example (together with instructions on finding your way around the TweakDB) has moved to Browsing the tweak database -> Example: browsing .tweak files

We'll end up with WilsonWeaponMod (slotted on the weapon) and WilsonWeaponModAbility (GameplayLogicPackage of the previous)

iconic_mods.tweak
mods_abilities.tweak

For an explanation of what these do, please see Types of tweak records -> Effector

Adding an iconic mod

We have found the iconic mod of Wilson's gun, so now let's see that we apply the same structure to the Hand of Midas.

Since our weapon demands perfection, we'll punish the player for not hitting headshots & reward them for hitting headshots. And because we want to make it hurt, we'll use HP reduction & Healing rewards.

You can add the tweaks below to your weapon's yaml file or create a new one.

Will make it so the weapon has this iconic mod slotted in the appropriate modslot, on weapon acquisition.

Defining the mod

This is the stage where we define how the stats of this weapon will differ from its base variant, plus add a reference to the "mod ability" record that holds the gold description and any desired Effectors

You can find an overview of existing weapon stats under Cheat Sheet: Weapon BaseStats

StatModifiers will stack with all other StatModifiers present on the weapon

Defining the ability

In this section, we first define our special ability Items.Cranial_Cashback:

The ability contains

  • two effectors, which we are yet to implement

  • the description for our iconic ability as a localizedDescription

Let's start by registering the description.

  1. Open the .json file that you've created when Setting up a localizationKey

  2. Add another entry (you can duplicate an existing entry)

  3. Set the secondaryKey to the value in your tweak file, MC_gun_iconic_description

  4. Set femaleVariant to your text — this will be showin on the tooltip in yellow.

  5. . Make sure that it has the correct secondary key , and enter your fluff text as femaleVariant.

Now that we have an ability, we need to register it as a mod:

Everything hangs together now, let's see if it works.

Full mod adding

Go test

Install your mod — if your gun shows the yellow iconic description on hover, you're good to go. If not, you may have to respawn it via CET.

Iconic description is visible when hovering over gun

Designing effectors

Now that we have New Iconic Weapon: Step by Step, we'll fill in the two effectors, one to punish the player for missing, and the other to reward them for headshots.

Heal on headshot

We'll heal for 80 HP every time the player pops somebody else's skull with the Hand of Midas. How do we do that?

Let's do what Edison did — we find something to be inspired by. A search for effector in the Tweak Browser finds an awful lot of entries, so I've picked an example for us — a Netrunner item that restores memory:

The player's health is also a statPool item, it's called BaseStatPools.Health. We can copy this example and change it to meet our needs (for the final result, see The final effector):

However, the prerequisite for this effector is Items.MemoryReplenishmentEffector_inline0, which doesn't sound helpful.

We could now try to find an existing preReq that checks for headshots, but we can also write our own.

Creating a custom prereq

Now we have a custom preqrequisite, but we still have to fine-tune and link it:

Creating a custom condition

For more information on this, check Types of tweak records ->Condition

Conditions are at the heart of a prerequisite, and here we have four.

  1. Perks.IsHitTargetAlive_inline2 -> We don't want headshots on deadbodies to heal the player

  2. Perks.HitIsBodyPartHead_inline0 -> Actual condition to check for headshots

  3. Prereqs.Is_Attack_Ranged -> (Custom) We don't want quick melee attacks to heal

  4. Prereqs.Is_Weapon_Ranged -> (Custom) We don't want grenades to be counted for this check.

The final effector

Now let's change our effector to use this prerequisite.

Instead of punishing the player for just missing headshots, we can make our job easier by removing the HP every time they shoot, and compensating for the reduction in HP when hitting headshots by increasing our heal. Here's how we can do that:

Test it!

Uncomment the effector in your weapon tweak and test your mod. You should now be healing every time you hit headshots.

The full tweak file

Bonus: Audio - Gun Go Boom

Firing sounds of guns are dictated by the value of their audioName flat. Swapping them to those of another gun is as easy as changing that value.

For a list of soundsets already in the game, refer to Cheat Sheet: Weapon Audio

Beware that firing sounds are, natively, separately set for each firing mode.

Meaning, for example, giving the audioName of a weapon that usually fires as Burst to a weapon that doesn't could result in missing sounds (or the other way around).

Having Trigger Mode Control installed passively fixes this problem in the background, allowing for correct sounds on all firemode combinations. (refer to its own documentation if interested about how to customize firemodes and attack types)

Adding custom sounds

We can add custom sounds using RedMod but, due to how that works (as a replacer), we could end up influencing other guns and/or generating conflicts.

An explanation for how audio works internally, should you decide to go the RedMod route.

Summary: The iconic weapon in action

Here's a demo for how iconic weapon should behave.

Heal on headshot demo
Damage player on miss demo

You are now a certified weapon modder. Pat your self on the back twice, you've done it. A special request from me (@DestinyBu). If you found this guide helpful, go ahead and document your own findings on the Wiki and maybe ping me if you ever get around to finishing your Mod. A big thanks to mana vortexfor (inspiring) forcing me to do this.

Troubleshooting (Check this when you're stuck)

You've created/modified a tweak but it doesn't show effect in game, what next?

  • Open the CET Console in game search for your Tweak in the Tweak Browser. If your tweak doesn't show, there's a validation error in the tweak.

  • Validate your .yaml tweaks here to check for errors.

  • Open Cyberpunk 2077\red4ext\plugins\TweakXL\TweakXL.log and look for any error messages towards the end, this can help when TweakXL has issues loading a tweak.

  • Check for other mods with same Tweak/Archive names.

    Tweak Folder - Cyberpunk 2077\r6\tweaks

    Archive Folder - Cyberpunk 2077\archive\pc\mod

  • Look at WolvenKit logs located towards the bottom. Yellow or Red text means there's warnings/errors in your file that need addressing.

PreviousItemAdditions: WeaponsNextStandalone Weapon Appearance

Last updated