Custom weapons

Some example content and a guide to creating a custom weapon for TTT.

Downloads

  • Icon template: a .psd file for creating a menu icon in the style of the other TTT icons.
  • AK47 weapon: an example scripted weapon.

Guide

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 (i.e., scripted weapon) concepts when convenient, but I’m not going to be able to tell you everything there is to know, and I especially can’t teach you Lua here. Use the tutorials and information at the Gmod wiki 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.

Preparation

Download the AK47 weapon linked above. 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.

Code

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:

    SWEP.Base = "weapon_tttbase"

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.

Required fields

The most important TTT-specific bit is:

     SWEP.Kind = WEAPON_EQUIP1

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

  • WEAPON_PISTOL: small arms like the pistol and the deagle.
  • WEAPON_HEAVY: rifles, shotguns, machineguns.
  • WEAPON_NADE: grenades.
  • WEAPON_EQUIP1: special equipment, typically bought with credits and Traitor/Detective-only.
  • WEAPON_EQUIP2: same as above, secondary equipment slot. Players can carry one of each.
  • WEAPON_ROLE: special equipment that is default equipment for a role, like the DNA Scanner.
  • WEAPON_MELEE: only for the crowbar players get by default.
  • WEAPON_CARRY: only for the Magneto-stick, default equipment.

Another field most TTT weapons should set (assuming they use refillable ammo) is:

    SWEP.AmmoEnt = "item_ammo_smg1_ttt"

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:

  • item_ammo_pistol_ttt: Pistol and M16 ammo.
  • item_ammo_smg1_ttt: SMG ammo, used by MAC10 and UMP.
  • item_ammo_revolver_ttt: Desert eagle ammo.
  • item_ammo_357_ttt: Sniper rifle ammo.
  • item_box_buckshot_ttt: Shotgun ammo.

A bit further down in the AK code is the icon:

    SWEP.Icon = "VGUI/ttt/icon_myserver_ak47"

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 in the equipment menu as well. The creation of an icon is covered later. Important is a unique filename, 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. Use a name unique to your server/addon, easily done by putting your server name or username in the filename.

    if SERVER then
       resource.AddFile("materials/VGUI/ttt/icon_myserver_ak47.vmt")
    end

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. Note that TTT’s built-in weapons don’t have this, because every Gmod player already has the icon installed.

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 lines followed by an explanation:

    SWEP.CanBuy = { ROLE_TRAITOR }

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.

    SWEP.InLoadoutFor = nil

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 (can also be left out).

    SWEP.LimitedStock = false

Weapons that are limited in stock can only be bought once per round.

    SWEP.EquipMenuData = {
       type = "Weapon",
       desc = "Example custom weapon."
    };

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 \n where you want one. It’s a hassle, I know.

Other
    SWEP.AllowDrop = true

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). Dropping defaults to being allowed, it’s only disabled if AllowDrop is set explicitly to false.

    SWEP.IsSilent = false

If IsSilent is true, victims killed with this gun will never scream (meaning the scream sound effect is not played, so the kill is silent). Normally, only headshot kills never scream. Note that this is not related to the weapon’s gunshot sounds.

    SWEP.NoSights = false

If NoSights is true, the player cannot use iron sights with this weapon.

    SWEP.AutoSpawnable = false

Only weapons that are not of type WEAPON_EQUIP* and have AutoSpawnable set to true will spawn from ttt_random_weapon entities.

    SWEP.WeaponID = ...

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.

    SWEP.IronSightsPos = Vector( 6.05, -5, 2.4 )
    SWEP.IronSightsAng = Vector( 2.2, -0.1, 0 )

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. Next we’ll look at the icon.

Icon

Note: this outlines how you can create an icon in the same style as TTT’s icon. You can of course make an icon in any style you want if you so choose.

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 already 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 (like an old-school modder).

Whichever method you use, it should have the following VTF settings:

  • Format: BGRA8888
  • Uncheck/disable mipmaps and thumbnail generation
  • Flags:
    • Point Sample
    • No Mipmap
    • No Level of Detail
    • (Eight Bit Alpha will be automatically checked due to the format)

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:

"UnlitGeneric"
{
 "$basetexture" "VGUI/ttt/icon_myserver_ak47"
 "$vertexcolor" 1
 "$vertexalpha" 1
 "$translucent" 1
}

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.

Questions

Can I make my custom weapon cost 2 or 3 credits instead of 1?

No, and this is intentional. I don’t want the equipment menu to turn into a CS:S-like store. The decision a player with a credit should make 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 a bunch of complexity.

In short: this is intentional and will not change.

The solution is to 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.