Creating custom weapons - basics

This guide is currently incomplete, but it should suffice if you just need the basics!

If you're here, chances are you're looking to create your own weapons for TF2 Classified. Whether for use against bots or other players, this guide should hopefully cover the majority of your questions regarding custom weapon creation. If it doesn't, ask for help in the #modding-discussion channel in the official TF2C Discord.

Getting Started

Before going over how to create custom weapons, we first need a functional custom item schema to put them into. The item schema is basically a big list that you append all of your weapons into, and is arguably the single most important file for that reason. It uses VDF, which is the standard format for storing game-related metadata in Source. If you don't know VDF, don't worry - it won't take long to understand the syntax.

Creating the custom item schema

To begin, create a file named custom_items_game.txt in the <SteamUserDir>\Team Fortress 2 Classified\tf2classified\custom\<Mod Name>\scripts directory. This is the file that will contain all of the information regarding your custom weapons. Please note that you cannot have multiple custom_items_game.txt files loaded simultaneously, so any other mod folders that contain them should be placed in tf2classified\custom\disabled to allow the new custom item schema to load.

Setting up the custom item schema

Shown below are the main parameters that should ideally be included in every single item schema. Copy this exactly into your custom_items_game.txt file.

Explanation

base "items_game.txt"

This line is responsible for merging the data from the custom item schema into TF2C's main item schema. Without this, none of TF2C's items, prefabs or attributes will load, which isn't very ideal.

"items_game"

The parameter that contains everything unique to the item schema. Whilst not particularly interesting, it's vital for the item schema to run.

"items"

The parameter that contains items. They must be defined here in order for them to appear in game.

"prefabs"

The parameter that contains prefabs, which will be explained later.

"attributes"

The parameter that contains attributes, which will also be explained later.

Creating your first weapon

The basics

To function, item entries must be placed under the "items" parameter, with the exact indentation shown in the upcoming template.

Shown below is a template item entry that contains the essential parameters for most custom weapons. Values in <> brackets are placeholder values that should be replaced by suitable ones.

Explanation

"<item id>"

The unique ID used by the weapon. Be careful: if shared with another item entry, the custom item schema will fail to load. Try to use high values (ideally >= 10000) to prevent clashes with vanilla item entries.

"name"

The unique internal identifier used by the weapon. Like "<item id>", the custom item schema will fail to load if it's shared with another entry.

"item_name"

The displayed name of the item, which can either be plaintext or a localised string (e.g. #TF_Weapon_Pistol). If you want to add "The" to the beginning of the name, add the "propername" parameter to the item entry and set the value to 1.

"item_type_name"

The item's type, which is displayed under the name in the description.

"item_logname"

The name used by the weapon when reported in the developer console.

"item_iconname"

The name of the weapon's main killicon. If an invalid icon is pointed to, then the default skull icon will be used instead. Supports SVG icons in resource\svgs\deathnotice and VTF icons defined in scripts\mod_textures.txt and scripts\mod_textures_tf2c.txt.

"item_class"

The item class to be used as a base for your weapon. A list of available item classes can be found here.

"item_slot"

The loadout slot that the weapon is located in. Below is a list of functional "item_slot" values:

primary

secondary

melee

pda

pda2

building

action ^[note]

utility ^[note]

"anim_slot"

The third-person and (if applicable) c_model animations to use. If absent, the item will use the default animations for its class. Below is a list of functional "anim_slot" values:

primary

primary2

secondary

secondary2

melee

melee_allclass

pda

pda2

building

item1

item2

item3

item4

passtime_ball

force_not_used

"model_player"

The model used in first person.

"model_world"

The model used in third person. If this parameter is absent from the item entry, the game will automatically use the model defined in the "model_player" parameter.

"image_inventory"

The icon used in the loadout menu and bucket.

"attach_to_hands"

This parameter controls what model's animations are used. If set to 1, the class' c_arms will be used for the animations. If set to 2, the item model's animations will be used instead.

"used_by_classes"

This controls which classes can use the item. Set to 1 to use the loadout slot defined under "item_slot", or set it to a specific loadout slot to get it to appear in that slot for a specific class.

"attributes"

The list of attributes that modify the weapon's behaviour. You can add as many attributes as you'd like, just as long as the attribute class isn't repeated. Some attributes can be condensed into a single line if you wish (e.g. <attribute name> "<value>"), which is helpful for meta-attributes like "hidden separator" and "provide on active" that are repeated often. A list of item attributes can be found here.

"static_attrs"

A variant of "attributes" that should only be used for attributes like "min_viewmodel_offset".

"visuals"

This parameter allows you to change the item's effects, like sounds and tracers. This will be explained in more detail later.

"mouse_pressed_sound"

The sound to play when the item is selected in a loadout grid.

"drop_sound"

The sound to play when the item is selected in a class' loadout screen.

Example

Below is an example item entry for a custom Pistol with a clip size bonus, a damage penalty and the Winger's fire sounds. Copy it and try modifying it to get a feel for making items. If you're looking for models and soundscripts, try using HLMV++ and/or Hammer ++, or look at item entries in TF2 and TF2C's item schemas.

Here's how the description looks in game:

Attributes

Adding / adjusting item attributes

As mentioned above, the Custom Pistol has two attributes: a clip size bonus and a damage penalty, which gives it a clip size of 24 and a base damage of 10. It's a bit boring, so how about we spice things up a bit?

Now, the Custom Pistol instead has a damage bonus and a clip size penalty, resulting in 20 base damage and a clip size of 6. More importantly though, the "can headshot" attribute has given it the ability to deal crits on headshot. Pretty cool, eh?

Let's see how the description looks in game:

Making custom attributes

Oh dear. It seems the "can headshot" attribute lacks a description string, and is therefore hidden. This, of course, isn't ideal for stat clarity, so how exactly do we go about fixing this?

Remember the "attributes" parameter explained here? Well, it's time to put it to good use!

In your "attributes" parameter (the one with the same indentation as "items" and "prefabs" - I know, it's confusing), copy the above attribute. This is a copy of the "can headshot" attribute that's been simplified for this tutorial.

The "description_string" parameter is responsible for the stats displayed in an item's description. Here, it's been set to the plaintext "Crits on headshot", which means that it won't be affected by language. Thankfully, in this instance, there's a suitable localised string that can be used instead to ensure that it's understandable to a wider range of people.

By setting the value to #Attrib_RevolverUseHitLocations (the localised string used by the Ambassador's headshot attribute), the same text will be displayed, but will now also be localised to the user's language.

After replacing the Custom Pistol's "can headshot" attribute with the newly created "can headshot VISIBLE", here's how it should look in game:

Now we're getting somewhere! There's still a couple of issues that we need to fix though, so let's go through how to do that.

The first problem is the position of the attribute in the description. In order from top to bottom, item descriptions should always list neutral (white) stats first, then positive (blue) stats, and finally negative (red) stats, with informational text like "This weapon will reload when not active" and "Can be defused by the Wrench" being positioned at the very end.

IMAGE GOES HERE

By moving the "can headshot VISIBLE" attribute to the top, it also moves it to the top of the item's description.

Changing the model(s)

c_models

What's that? You want to change the model too? Well, with the base selection of models in Classified, there's only one that works with "attach_to_hands" "2" - the Pistol model that we're currently using. However, what about TF2's c_models?

Here, the parameters have been adjusted for c_model animations. With "attach_to_hands" set to 1, the Custom Pistol will use the secondary animations from the class' c_arms - in this case, the Scout's pistol animations. This allows for pistol c_models like the Winger's to be used without visual bugs.

Here's how it looks in game:

Class-specific v_models

If your item is multi-class and uses the c_models system, you don't need to worry about changing the model between classes. However, if the item uses the v_models system, you should change the model used between classes so that the animations don't look off. The question is: how do you get them to change between classes?

The answer lies with the "model_player_per_class" parameter.

By adding this to the first version of the Custom Pistol, you can change the v_model used by each class, allowing you to have the weapon on both Scout and Engineer without making them share animations.

Testing the weapon

Loading into a map

To get the custom item schema to load, boot up any map. Once you do, the weapon should appear in the loadout grid.

Making changes

If you make changes to the custom item schema, use the command cl_reload_item_schema to show the changes in game. sv_reload_item_schema can also be used to update the custom item schema for the whole server in multiplayer.

Advanced weapon creation

Creating custom models, effects and sounds

TEMPTEXT

Making custom attributes

TEMPTEXT

VScript

TEMPTEXT Link to a separate VScript page

See also

• List of TF2C item attributes
• List of TF2C item classes
• List of TF2C conditions