Some useful downloadable material, and a guide to creation custom weapons for TTT.
Icon template: PSD file for creating a menu icon in the TTT style.
AK47 weapon: Example SWEP script.
We will look at making a custom weapon for TTT, both the code side and the graphical side. We do this by following along with an example weapon that you can download in the list above. It's a simple AK47.
I will explain standard GMod SWEP concepts when convenient, but I'm not going to tell you everything there is to know, and I'm especially not going to teach you Lua. Use the tutorials and information at http://wiki.garrysmod.com/ to fill in the gaps.
From this point on, I will assume that you are familiar with Lua and that you are somewhat familiar with GMod SWEPs. If not, you may still be able to follow along, but at your own risk.
Download the AK47 weapon. The .zip will contain a weapon_ttt_ak47 folder. Extract it into \garrysmod\gamemodes\terrortown\entities\weapons\.
If you now start a TTT game, you can use the console command "give weapon_ttt_ak47" to get the gun and give it a go.
Let's look at the shared.lua file in the folder you have extracted. At the top is some bog standard SWEP stuff I'll skip past. The first important line is:
All weapons in TTT must derive from weapon_tttbase, directly or indirectly, unless you really know what you're doing. The weapon_tttbase baseclass provides functions that TTT expects to be there.
This is followed by a bunch of fields setting the properties of the weapon like damage and model. Again, standard GMod stuff. Then, there's a number of TTT-specific fields set on the weapon. Some of these are more important than others, so we'll first discuss the important ones.
The most important TTT-specific bit is:
Every TTT weapon must have a Kind specified. It's the category or class the weapon belongs to. You can't carry two weapons of the same Kind, and certain other behavior also depends on type. For example, the special equipment types (WEAPON_EQUIP1, EQUIP2, and ROLE) will not auto-pickup if players walk over them (they must press +use). Mappers can use a weapon checker entity to detect specific types (Kinds) of weapons.
The following categories are available:
Another field most TTT weapons should set (assuming they use refillable ammo) is:
This specifies which ammo entity the player should pick up for this weapon. If a certain ammo entity is not set as the AmmoEnt of one of a player's weapons, they cannot pick up that ammo.
The following ammo entities are in TTT by default:
A bit further down in the AK code:
Every weapon needs an icon, so that it can be displayed in the Body Search dialog for corpses. If the weapon is buyable equipment, it will be used there as well. The creation of an icon is covered later. Important is a unique name, because GMod will not download your icon if one of the same name already exists. So if a player first joins a different server that also has an AK but with a terrible looking icon, they will still see that icon on your server and think you are bad at icons. No one wants to be thought of as bad at icons. Use a name unique to your server, easily done by putting it in the filename.
Here we tell the server that it should send your icon to players. Note that the path has "materials/" added to it compared to SWEP.Icon. Adding the VMT will automatically add the VTF. You can also do this in a separate file, but why bother. It's only in a separate file for the default TTT weapons because I automatically generate a resource.AddFile list to make sure I don't forget things.
That's all for the settings almost every weapon needs. What remains is some special equipment stuff and a couple of other settings.
Special equipment fields
The CanBuy field specifies in a table which roles can see and buy this weapon in their equipment menu. Including both ROLE_TRAITOR and ROLE_DETECTIVE will make a weapon available to both.
The InLoadoutFor field is structured similar to CanBuy, in that it's a table of role identifiers. For those roles, the weapon is given automatically upon the beginning of the round. This is how Detectives get their DNA Scanner. The AK47 isn't default for anyone, so it's nil (could also leave it out).
Weapons that are limited in stock can only be bought once per round.
The EquipMenuData is a table of text that the equipment menu should show for your weapon. The type should be an indication of what kind of thing it is, and the description should... describe it. In the description you will have to manually add linebreaks by inserting
Sets whether a player can drop the weapon using his Q key. It will still drop on death (which you can prevent by removing it in the SWEP:OnDrop function). You can leave this out to allow dropping too, it's only disabled if AllowDrop is set explicitly to false.
If IsSilent is true, victims killed with this gun will never scream (so the kill is silent, not the weapon). Normally, only headshot kills never scream.
If NoSights is true, the player does cannot use iron sights with this weapon.
Only weapons that are not of type WEAPON_EQUIP* and have AutoSpawnable set to true will spawn from ttt_random_weapon entities.
This isn't in the AK47 example, but you will see this field if you look at the standard TTT weapons. Do not set it in a custom weapon. Custom weapons do not need it, and should not have it. That's why the example weapon doesn't have it. I mention it here because people get this wrong all the time.
The IronSights vectors are actually from the default GMod CS:S weapons that the TTT weapons were originally based on, but I'll discuss them here anyway. They determine how the gun is positioned when using iron sights. It will take some experimentation to find good values here, because they differ significantly for every gun.
This covers much of the code you'll need for a simple gun. Moving on to the icon.
The actual image creation is too easy to cover in depth here. Just grab the icon template PSD (link in the downloads section above) and open it in Photoshop or something compatible. The topmost layer should be set invisible and called "example_shading". It has the shadow effect on it that all TTT weapons have. Set it to visible and have a look.
Load up GMod sandbox with gm_construct, and screenshot your weapon model in the white room. To get it on a fully white background, freeze it in the air at eye height before screenshotting it with the camera weapon. Open the screenshot in the image editor and use the magic wand to select the white background and delete it. With the background gone/transparent, you can now easily just rectangle-select the weapon. Cut and paste it into the template image on a new layer. Resize it appropriately, and copy or replicate the shadow effect (in Photoshop, you can copy and paste the layer style of the example_shading layer in its right click menu). That's it for the image editing portion.
Now choose File => Save As, and select VTF as the file type. You will need a VTF plugin for your editor for this (google around). An alternative is to save as TGA (32 bit, alpha channels enabled), and then use another method of converting that into a VTF. For example, you could import the TGA into VTFEdit and then save as VTF.
Whichever method you use, it should have the following VTF settings:
Put the VTF in \garrysmod\materials\VGUI\ttt\.
Let's assume you named it icon_myserver_ak47.vtf.
You can look at the other icon_ files in the TTT content directory and use them as example. That directory is: \garrysmod\gamemodes\terrortown\content\materials\VGUI\ttt\
Opening the default icon VTFs in VTFEdit will show you they all use the above VTF settings and flags. The VMTs are also all very similar, and we'll make one for our AK47 now.
Make a text file called icon_myserver_ak47.vmt (recall that that is the filename we specified in the SWEP code). Open the VMT in a text editor and paste:
That's it. If you load up the game now, spawn as traitor and open the equipment menu, your AK icon should be in the list. If it's a pink checkerboard, check if you got the path in the VMT right, and (if you're playing on a server) that it was downloaded correctly.
Can I make my custom weapon cost 2 or 3 credits instead of 1?
No. I don't want the equipment menu to turn into a CS:S-like store. The decision a player with a credit makes right now is "which equipment is going to help me most". If equipment starts having variable prices, the decision suddenly involves options such as saving for more expensive equipment, and which equipment is the most price-efficient. This seemingly small change will add significant complexity.
In short: this is intentional and will not change.
Balance your weapon for 1 credit. If you're looking for an easy option, limit the weapon's ammo and let players buy another one to get more shots once they run out.