Custom Weapons

A new weapon system in this mod can create new weapons without a client update, without introducing input lag, and without breaking lag compensation. This is done through config files that define the attributes and event-based behavior for the weapon. It is more limiting than a scripting system, but easier to for newbies to get started with. No coding experience is required.

Config format

Configs follow the INI file format. Here's an example weapon config and an example ammo config. Comments begin with ; or // or # and are ignored by the weapon parser. For explanations of each section and attribute, see these guides:

Custom Weapon Attributes
Custom Weapon Events
Custom Ammo Attributes

Creating a new weapon

To create a new weapon, add a new .txt file to the valve_downloads/weapons/ folder and register it in the map CFG. The following CFG line will register a weapon using the config at weapons/my_map/weapon_big.txt.

custom_weapon my_map/weapon_big

You can then add a weapon_big entity somewhere in the map or add it to the map CFG equipment. You'll probably want to start by copying settings from an existing config so that the weapon is registered without errors, then edit it from there. Only the [general] section is required.

After creating a new weapon config and loading it into a map, type in the autoreloadweps command in your client console. This will automatically scan all loaded weapon configs for updates and refresh your settings live. No need to restart the server or rejoin (unless you added new models or sounds that aren't precached yet). If you want to reload the configs manually then type in reloadweps instead.

When you've finished the weapon, use the dumpwepcfg command to create a nicely formatted config file in the valve/weapons/dump/ folder. It will organize events by actions and align all the attribute values.

Creating a new ammo entity

Ammo entities are much simpler than weapons. They are registered with the custom_ammo CFG command, which works the same as custom_weapon command. The config layout is the same as custom weapon configs.

Replacing a stock weapon with a custom version

Let's say you've created a new weapon called weapon_good_glock and you want it to completely replace weapon_9mmhandgun. That is, a SevenKewp player should never be able to pick up a normal glock - it must always be the custom version. To do that, add the following lines to your map CFG:

custom_weapon my_map/weapon_good_glock
custom_weapon_alias weapon_good_glock weapon_9mmhandgun
entity_remap weapon_9mmhandgun weapon_custom_ini
hl_weapon_remap weapon_9mmhandgun weapon_good_glock

• custom_weapon registers your weapon, which you should already have in your CFG.
• custom_weapon_alias enables the weapon to be spawned with the classname of the weapon you want to replace.
• entity_remap forces the stock weapon to be created as a custom weapon. Once that happens, your alias logic kicks in and loads your custom weapon settings.
• hl_weapon_remap forces all glocks picked up by SevenKewp players to be replaced by the good version. This is necessary because Half-Life clients can drop the Half-Life glock if you've configured that as the hl_client_classname for your weapon. You can possibly skip this if you allow Half-Life clients to use your custom glock, but I don't recommend that for hitscan weapons.

weapon_custom_ini is the generic weapon class that all config-based weapons are created with by default. If you had a custom implementation for your glock then you would remap to that instead of weapon_custom_ini, as seen below:

custom_weapon my_map/weapon_good_glock weapon_good_glock
custom_weapon_alias weapon_good_glock weapon_9mmhandgun
entity_remap weapon_9mmhandgun weapon_good_glock
hl_weapon_remap weapon_9mmhandgun weapon_good_glock

Replacing a stock ammo entity with a custom version

Replacing stock ammo entities is simpler because all of them are config-based. There's no need for the entity_remap or hl_weapon_remap commands. These two CFG commands are enough to replace ammo_357 with ammo_50cow:

custom_ammo my_map/ammo_50cow
custom_ammo_alias ammo_50cow ammo_357

Advanced usage

Weapon data is sent to clients on demand, meaning you can edit weapon behavior live, even if the weapon is being used by a player. An example of this is a weapon that has a silencer attachment. You could update the sounds, accuracy, recoil, etc. when the silencer is added. Or maybe you want an experience mod where the fire rate and reload speed increases with your power level.

This and other server-side logic can be added by creating a subclass of CWeaponCustom for your weapon. Register the weapon using the classname override, like so:
custom_weapon my_map/weapon_good weapon_good
and then link your C++ class to the weapon_good classname. Check the virtual methods in CWeaponCustom.h to see where you can inject your custom logic.

Weapon HUDs

Create a new weapon HUD

Create the following BMP files and place them next to the hud_create.py script. The base resolution is the 640 sprite size. The script automatically creates 320, 1280, and 2560 resolution images for HL25.

Required bitmaps:

• weapon.bmp = deselected weapon icon (170x45)
• weapon_s.bmp = selected weapon icon (170x45)

Optional icons:

• ammo.bmp = primary ammo icon (24x24)
• ammo2.bmp = secondary ammo icon (24x24)
• crosshair.bmp = weapon crosshair (24x24)
• autoaim.bmp = autoaim crosshair (24x24)
• zoom.bmp = scope sprite (size doesn't matter, as long as it's less than 512x512)

Run python hud_create.py weapon to compile the weapon HUD. You'll need to edit the sprite paths in the resulting .txt file to point to wherever you want the sprite to be.

If you ever update need to update this HUD after distributing to a server, then you need to move the HUD config to a new folder. You can't rename the HUD .txt file without also renaming the weapon, and clients won't get the new version if it's edited without being moved.

Convert an existing HUD

HL25 HUD sprites support higher sprite resolutions, so you have to convert HUDs from other mods for them to work properly. Use the hud_create.py script to do this automatically.

python hud_create.py weapon sprites/asdf/weapon_test.txt

In the above example, weapon_test.txt is a HUD configuration file for a weapon. The script will parse that and create a new sprite atlas and config that's HL25 compatible. If it complains about missing sprites like 640hud* or crosshairs then copy those from your Half-Life/valve/sprites/ folder into the sprites/ folder next to your script.

For Sven Co-op weapons, you'll need to copy the 640hud* sprites from its mod folder or else ammo icons will be cropped wrong. You can keep the HL crosshairs.spr for consistent coloring.

Custom icons

Custom weapon HUDs can have custom icons which you name yourself. Make a folder and place BMP files inside. Use 640 resolution sprites. 320, 1280, and 2560 resolution images are created automatically. The folder path and name determines what will be written in the hud config. Use sprites/my_map/hud_firemodes/ if the sprite will be sprites/my_map/hud_firemodes.spr. Then run this command to generate the sprite and hud config:

python hud_create.py custom sprites/my_map/hud_firemodes

You'll get a hud_firemode.txt and a hud_firemodes.spr. Copy the sprite to the target folder if it looks good. Then copy lines from the .txt into your weapon HUD config (don't forget to increase the sprite count on the top line). You should then be able to reference the new icons in your weapon config.