Toggle search
Toggle menu
TF2 Classified Wiki
Toggle preferences menu
Toggle personal menu
Not logged in
Your IP address will be publicly visible if you make any edits.

Creating custom weapons - basics: Difference between revisions

From TF2 Classified Wiki
More actions
← Older edit

Static Fanatic (talk | contribs)

842 edits
mNo edit summary
mNo edit summary
 
(77 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{stub}}
{{stub}}
{{todo|Add literally any information that is useful. I'll trim the fat and clean up the remaining stuff afterwards.}}
{{todo|Complete every current section and add new ones if applicable.


Adjust image sizes and potentially add captions.


'''This guide is currently incomplete, so please look for a better one while this is being worked on!
Demonstrate using a c_model with attach_to_hands 2 and possibly a v_model with attach_to hands 1.


Adjust the positions of the examples and text to look less messy.


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 people for help in the #modding-discussion channel in the [https://discord.gg/tf2classified official TF2C Discord].
If you're going to add information, put it in [[Creating custom weapons#Creating your first weapon|Creating your first weapon]] only if it's '''very''' important to creating weapons, and otherwise put it in [[Creating custom weapons - advanced]]. Do NOT overwhelm beginners!


= Getting Started =
Don't try to fix the wonky indentation in the examples. It's inconsequential and fixing it here will make it look bad in Notepad ++, so it's best to leave it as is. Yeah, I'm annoyed by it too lol}}
To begin, create a file named {{code|custom_items_game.txt}} in the {{code|<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 {{code|tf2classified\custom\disabled}} to allow the new custom item schema to load.


= Ideal final list of contents =
* Getting started
** Creating a custom item schema
** Setting up the schema
* Creating your first weapon
** Defining important stuff
** Attributes
** Models and sounds
** Using the weapon in-game
* Advanced weapon creation
** Custom models and sounds / soundscripts
** Customising visual effects
** Making custom attributes
** Link to a separate VScript page to keep this one nice and tidy
* WIP


= Misc info to be added to the finished sections (TEMP!)=
'''This guide is currently incomplete, but it should suffice if you just need the very basics!'''
* It should be noted that custom weapons don't currently show up in the loadout on the main menu. To view them, you need to load into a map first.{{note|rei note! if using a items_game instead of a custom_items_game they will load on the main menu. however this means you are more prone to schema breakage between game versions and you gotta constantly update your copy anytime they update the item schema}}


* It's a good idea to go over the basic parameters that most weapons should have. Failing to include these can either break the weapon in some way or completely prevent the whole pack from loading.
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 help you to start out with creating custom weapons. If it doesn't, consider asking for help in the '''#modding-discussion''' channel in the [https://discord.gg/tf2classified official TF2C Discord].


* Duplicate {{code|name}} parameters in a single weapon entry will prevent the custom item schema from loading. Same goes for duplicate entry IDs.
= Creating a custom item schema =
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 add all of your items into, and is responsible for defining everything about them. It uses [https://developer.valvesoftware.com/wiki/VDF 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.


* Duplicating certain parameters, {{code|attributes}} for example, does work, but it's advised not to do this to keep your weapon entries tidy.
== custom_items_game.txt ==
To begin, create a file named {{code|custom_items_game.txt}} in your {{code|<SteamUserDir>\Team Fortress 2 Classified\tf2classified\custom\<Mod Name>\scripts\items}} directory. This is the file that contains all the information regarding your custom weapons. Please note that you cannot have multiple {{code|custom_items_game.txt}} files loaded simultaneously, so any other mod folders that contain them should be placed in {{code|tf2classified\custom\disabled}} to allow the new custom item schema to load.


* Prefab info
It should be noted that the {{code|custom_items_game.txt}} method is the simplest and objectively best option for defining custom weapons, as it automatically inherits data from the newest version of the vanilla {{code|items_game.txt}} file. It is possible to override the vanilla item schema with one that contains custom weapons, but this method is not recommended as the overriding file must be manually updated each patch for parity with the vanilla {{code|items_game.txt}} file. For you and your players' sake, use the {{code|custom_items_game.txt}} method ''only''.
** Prefabs work as templates. Load order is important; Prefab at the top means you want to overwrite the prefab, Prefab at the bottom means you want prefab to overwrite you
** List based parameters (like visuals and static attrs) will get merged. Single value parameters (like bucket or attach to hands) will get overwritten.
** Prefabs cannot have spaces in the name. This is because spaces are used as a delimiter to apply multiple prefabs. (eg, {{code|prefab "prefab1 prefab2"}} will make the weapon inherit the parameters from both {{code|prefab1}} and {{code|prefab2}})


* {{code|item_name}}, {{code|item_type_name}}, {{code|item_description}} and {{code|description_string}} support localized strings.
== Setting up parameters ==
Shown below are the main parameters that should ideally be included in every single item schema. Copy this exactly into your {{code|custom_items_game.txt}} file.


* {{code|item_name_color}} and {{code|custom_color}} allow weapon names and attributes respectively to be coloured with RGB values.
<pre>
#base "items_game.txt"


* {{code|custom_level_sounds.txt}} can be used to create custom soundscripts for weapons. Please correct this if there's a better way of doing this!
"items_game"
{
"items"
{
}
"prefabs"
{
}
"attributes"
{
}
}
</pre>


* Localization strings in {{code|tf2c_english.txt}}
=== Explanation ===
{{code|preset=3|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, TF2C's items, prefabs and attributes will fail to load.
{{code|preset=3|"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.
{{code|preset=3|"items"}}
: The parameter that contains items. They must be defined here in order for them to appear in game.
{{code|preset=3|"prefabs"}}
: The parameter that contains prefabs, which will be explained later.
{{code|preset=3|"attributes"}}
: The parameter that contains attributes, which will also be explained later.


* {{code|baseitem}} sets an item as the default in its slot. Rather finicky, so avoid using.
= Creating your first weapon =


* Attribute info
== The basics ==
** Weapon attributes are set in the {{code|attributes}} and rarely {{code|static_attrs}} parameters.
To function, item entries must be placed in the {{code|preset=3|"items"}} parameter.
** Attributes are defined in the attributes section of the schema using a similar system to item entries.
 
** Though attributes with custom code aren't possible without VScript (correct this if wrong), variants of existing attributes can be created by making a new attribute with the same attribute class. {{note|rei note! certain attributes HATE being customized and will ONLY work if the attribute is specifically the original one by name?? certain parts of the code specifically check for attribute name and not attribute class}}
Below is a template item entry that contains the essential parameters for most custom weapons. Values in {{code|<>}} brackets are placeholder values that should be replaced by suitable ones.
** Quite a few weapon attributes have interesting behavior if set to additive mode
 
<pre>
"items_game"
{
"items"
{
"<item id>"
{
"name" "<internal name>"
"item_name" "<item name>"
"item_type_name" "<item type name>"
"item_quality" "<item name colour>"
"item_logname" "<dev console name>"
"item_iconname" "<icon name>"
"item_class" "<item class>"
"item_slot" "<backpack slot>"
"anim_slot" "<player model and c_model animations>"
 
"bucket" "<inventory slot override>"
"bucket_position" "<inventory subslot override>"
"model_player" "<view model>"
"model_world" "<world model>"
"image_inventory" "<backpack icon>"
"attach_to_hands" "<view model animation type>"
 
"used_by_classes"
{
"<class>" "<backpack slot>"
}
 
"attributes"
{
"<attribute name>"
{
"attribute_class" "<attribute class>"
"value" "<value>"
}
}
"static_attrs"
{
"<attribute class>" "<value>"
}
"visuals"
{
"<parameter>" "value"
}
 
"mouse_pressed_sound" "<backpack select sound>"
"drop_sound" "<backpack deselect sound>"
}
}
}
</pre>
 
=== Explanation ===
{{code|"<item id>"}}
: The unique ID used by the weapon. This can be any integer from 0 to 65535. Be careful: if shared with another item entry, the custom item schema will fail to load. Try to use random high values (ideally >= 10000) to prevent clashes with vanilla item entries.
{{code|preset=3|"name"}}
: The unique internal identifier used by the weapon. Like {{code|"<item id>"}}, the custom item schema will fail to load if it's shared with another entry.
{{code|preset=3|"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 {{code|preset=3|"propername"}} parameter to the item entry and set the value to 1.
{{code|preset=3|"item_type_name"}}
: The item's type, which is displayed under the name in the description.
{{code|preset=3|"item_logname"}}
: The name used by the weapon when reported in the developer console.
{{code|preset=3|"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 {{code|resource\svgs\deathnotice}} and VTF icons defined in {{code|scripts\mod_textures.txt}} and {{code|scripts\mod_textures_tf2c.txt}}.
{{code|preset=3|"item_class"}}
: The item class to be used as a base for your weapon. A list of available item classes can be found [[List of TF2C item classes|here]].
{{code|preset=3|"item_slot"}}
: The loadout slot that the weapon is located in. Below is a list of functional {{code|preset=3|"item_slot"}} values:
<pre>
primary
secondary
melee
pda
pda2
building
action
utility
</pre>
{{code|preset=3|"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 {{code|preset=3|"anim_slot"}} values:
<pre>
primary
primary2
secondary
secondary2
melee
melee_allclass
pda
pda2
building
item1
item2
item3
item4
passtime_ball
force_not_used
</pre>
{{code|preset=3|"model_player"}}
: The model used in first person.
{{code|preset=3|"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 {{code|preset=3|"model_player"}} parameter.
{{code|preset=3|"image_inventory"}}
: The icon used in the loadout menu and bucket.
{{code|preset=3|"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.
{{code|preset=3|"used_by_classes"}}
: This controls which classes can use the item. Set to 1 to use the loadout slot defined under {{code|preset=3|"item_slot"}}, or set it to a specific loadout slot to get it to appear in that slot for a specific class.
{{code|preset=3|"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 {{code|"hidden separator"}} and {{code|"provide on active"}} that are repeated often. A list of item attributes can be found [[List of TF2C item attributes|here]].
{{code|preset=3|"static_attrs"}}
: A variant of {{code|preset=3|"attributes"}} that should ''only'' be used for attributes like {{code|"min_viewmodel_offset"}}.
{{code|preset=3|"visuals"}}
: This parameter allows you to change the item's effects, like sounds and tracers. This will be explained in more detail later.
{{code|preset=3|"mouse_pressed_sound"}}
: The sound to play when the item is selected in a loadout grid.
{{code|preset=3|"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 [[tf:Winger|Winger]]'s fire sounds. Copy it and give modifying it a go to get a feel for making items. If you're looking for models and soundscripts, try using [https://developer.valvesoftware.com/wiki/Half-Life_Model_Viewer%2B%2B HLMV++] and/or [https://developer.valvesoftware.com/wiki/Hammer%2B%2B Hammer ++], or look at item entries in TF2 and TF2C's item schemas.
 
<pre>
"items_game"
{
"items"
{
"10000" // Custom Pistol
// You can add comments to your item schema with double slashes!
{
"name" "CUSTOM_PISTOL_TEST"
"item_name" "Custom Pistol"
"item_type_name" "#TF_Weapon_Pistol"
"item_logname" "pistol_test"
"item_iconname" "pistol"
"item_class" "tf_weapon_pistol"
"item_slot" "secondary"
"anim_slot" "secondary"
"model_player" "models/weapons/v_models/v_pistol_scout.mdl"
"model_world" "models/weapons/w_models/w_pistol.mdl"
"image_inventory" "backpack/weapons/w_models/w_pistol"
"attach_to_hands" "1"
 
"used_by_classes"
{
"scout" "1"
}
 
"attributes"
{
"clip size bonus"
{
"attribute_class" "mult_clipsize"
"value" "2"
}
"damage penalty"
{
"attribute_class" "mult_dmg"
"value" "0.67"
}
}
"static_attrs"
{
"min_viewmodel_offset" "10 0 -10"
}
"visuals"
{
"sound_single_shot" "Weapon_Winger.Single"
"sound_burst" "Weapon_Winger.SingleCrit"
}
 
"mouse_pressed_sound" "ui/item_light_gun_pickup.wav"
"drop_sound" "ui/item_light_gun_drop.wav"
}
}
}
</pre>
 
Here's how the description looks in game:
 
[[File:example_04_backpack.png]]
 
== Attributes ==
=== Adding 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?
 
<pre>
"items_game
{
"items"
{
"<item ID>"
{
<...>
"attributes"
{
"damage bonus"
{
"attribute_class" "mult_dmg"
"value" "1.33"
}
"clip size penalty"
{
"attribute_class" "mult_clipsize"
"value" "0.5"
}
"can headshot"
{
"attribute_class" "can_headshot"
"value" "1"
}
}
<...>
}
}
}
</pre>
 
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 {{code|"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:
 
[[File:example_07_backpack.png]]
 
=== Making custom attributes ===
Oh dear. It seems the {{code|"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 {{code|preset=3|"attributes"}} parameter explained [[Creating custom weapons#Setting up the custom item schema|here]]? Well, it's time to put it to good use!
 
<pre>
"items_game"
{
<...>
"attributes"
{
"40000"
{
"name" "can headshot VISIBLE"
"attribute_class" "can_headshot"
"description_format" "value_is_additive"
"stored_as_integer" "1"
 
"description_string" "#Attrib_RevolverUseHitLocations"
}
}
}
</pre>
 
In your {{code|preset=3|"attributes"}} parameter (the one with the same indentation as {{code|preset=3|"items"}} and {{code|preset=3|"prefabs"}} - I know, it's confusing), paste the above attribute. This is a copy of the {{code|"can headshot"}} attribute that's been simplified for this tutorial.
 
The {{code|"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 [[tf:Ambassador|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 {{code|"can headshot"}} attribute with the newly created {{code|"can headshot VISIBLE"}}, here's how it should look in game:
 
[[File:example_08_backpack.png]]
 
 
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.
 
<pre>
"items_game"
{
"items"
{
"<item ID>"
{
<...>
"attributes"
{
"can headshot VISIBLE"
{
"attribute_class" "can_headshot"
"value" "1"
}
"damage bonus"
{
"attribute_class" "mult_dmg"
"value" "1.33"
}
"clip size penalty"
{
"attribute_class" "mult_clipsize"
"value" "0.5"
}
}
<...>
}
}
}
</pre>
 
By moving the {{code|"can headshot VISIBLE"}} attribute to the top, it also moves it to the top of the item's description.
 
[[File:example_09_backpack.png]]
 
 
The second problem is the text colour. Crits on headshot is undeniably an upside, so it should be coloured blue to reflect that.
 
<pre>
"items_game"
{
<...>
"attributes"
{
"40000"
{
"name" "can headshot VISIBLE"
"attribute_class" "can_headshot"
"description_format" "value_is_additive"
"stored_as_integer" "1"
"description_string" "#Attrib_RevolverUseHitLocations"
"effect_type" "positive"
}
}
}
</pre>
 
By adding {{code|"effect_type" "positive"}} to the {{code|"can headshot VISIBLE"}} attribute, we can set the colour to the same blue as other positive attributes. If you want an attribute to be displayed as negative, simply replace {{code|"positive"}} with {{code|"negative"}}. The same goes for neutral attributes - replace {{code|"positive"}} with {{code|"neutral"}}.
 
Here's the result:
 
[[File:example_10_backpack.png]]
 
== Models ==
=== 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 {{code|preset=3|"attach_to_hands" "2"}} - the Pistol model that we're currently using. However, what about TF2's c_models?
 
<pre>
"items_game"
{
"items"
{
"<item ID>"
{
<...>
"item_logname" "pistol_test"
"item_iconname" "winger"
 
"item_class" "tf_weapon_pistol"
 
"item_slot" "secondary"
"anim_slot" "secondary"
 
"model_player" "models/workshop/weapons/c_models/c_winger_pistol/c_winger_pistol.mdl"
"image_inventory" "backpack/workshop/weapons/c_models/c_winger_pistol/c_winger_pistol"
 
"attach_to_hands" "1"
 
"used_by_classes"
{
"scout" "1"
"engineer" "1"
}
<...>
}
}
}
</pre>
 
Here, the parameters have been adjusted for c_model animations. With {{code|preset=3|"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 [[tf:Winger|Winger]]'s to be used without visual bugs.
 
Here's how it looks in game:
 
[[File:example_05_world.jpg|540px]]
 
 
=== 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 {{code|preset=3|"model_player_per_class"}} parameter.
 
<pre>
"items_game"
{
"items"
{
"<item ID>"
{
<...>
"model_player_per_class"
{
"engineer" "models/weapons/v_models/v_pistol_engineer.mdl"
"scout" "models/weapons/v_models/v_pistol_scout.mdl"
}
<...>
}
}
}
</pre>
 
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 ==
=== 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 {{code|cl_reload_item_schema}} to show the changes in game. {{code|sv_reload_item_schema}} can also be used to update the custom item schema for the whole server in multiplayer.


= See also =
= See also =
* [[Creating custom weapons - advanced]]
* [[Creating custom weapons - VScript]]
* [[List of TF2C item attributes]]
* [[List of TF2C item attributes]]
* [[List of TF2C item classes]]
* [[List of TF2C item classes]]
* [[List of TF2C weapon assets]]
* [[List of TF2C conditions]]
* [[List of TF2C conditions]]
* [[List of TF2C projectile IDs]]


[[Category:Guides]]
[[Category:Guides]]
Retrieved from "https://wiki.tf2classified.com/wiki/Creating_custom_weapons_-_basics"