Store Page
Insurgency
All Discussions Screenshots Artwork Broadcasts Videos Workshop News Guides Reviews

Insurgency

Store Page
Insurgency > Guides > Gypsum's Guides
62 ratings
♥♥♥♥♥'s crash guide to theater modding [Public Demo]
By Gypsum and 1 collaborators
This guide is a Work In Progress run through of how to properly configure your own custom theater for Insurgency
   
Award
Favorite
Favorited
Unfavorite
Created by
Arc
Online
Gypsum
Offline
Category: Characters, Classes, Co-op, Game Modes, Maps or Levels, Modding or Configuration, Multiplayer, Walkthroughs, Weapons, Workshop
Languages: English
Posted
Updated
2 Aug, 2015 @ 9:16pm
5 Sep, 2015 @ 5:04pm
3,017 Unique Visitors
131 Current Favorites
Guide Index
Overview
Getting Started 
Getting started: Default Files and Key Value Trees 
Customizing Insurgency: Creating the theater file 
How To Make: Custom Squads & Loadouts 
How To Make: Custom Gear & Accessories 
How To Make: Custom Weapons & Explosives 
How To Make: Custom Upgrades 
How To Make: Custom Ammunition ***critical*** 
How to make: All of that work together 
Additional advice and warnings 
Comments
Getting Started
You need GFScape to open the game's files
http://nemesis.thewavelength.net/?p=26

Insurgency's default theaters can be found in the root insurgency folder.
You'll want to open this file in GFScape: insurgency_misc_dir.vpk
Then extract the scripts/theaters folder and its contents to your insurgency root directory (Or wherever, but having /scripts/theaters in /insurgency helps you test more easily, we'll discuss that soon)
After extracting, navigate to the /scripts/theaters folder, and you should see:


base_common_ammo.theater - This holds the game's ammunition data.

base_explosives.theater - Base explosives (simple bases), called by default_weapon.theater.

base_player.theater - This holds player data, such as speed, stamina and damage resistance.

base_weapon.theater - Base weapons (simple bases), called by default_weapon.theater.

base_weapon_upgrades.theater - Base weapon upgrades (simple bases), called by default_weapon_upgrades.theater.

default_gear.theater - Contains gear definitions for all default vest, armor and accessory types.

default_weapon.theater - Contains weapon definitions for all default weapons and explosives in the game.

default_weapon_upgrades - Contains upgrade definitions for all upgradeable weapons in the game, including ammunition upgrades

default.theater - A default theater that fleshes out basic team parameters, called by most gamemode theaters.

default_*gamemode*.theater - Theater file containing parameters for the associated gamemode.

Getting started: Default Files and Key Value Trees
Each base theater inherited by and including the default.theater file has sections nested under thier "theater"{ root. Here we'll go over what they are and what they do.

  • Default_*gamemode*.theater
    Inherits: "default.theater"
    The generic theater, IE: any theater called as a gametype's name (for example default_checkpoint.theater), has the following sections below its "theater" root:
    1. "teams"
      The "teams" tree allows you to flesh out team parameters, This includes the team name, logo and squad structures.
    2. "player_templates"
      The "player_templates tree allows you to define the classes which are members of a squad. This includes the classes name, model, default equipment and which equipment the class is allowed to purchase. The classes are called inside the "teams" tree.
  • base_player.theater
    The base_player theater which defines the stats of character entities. It has the following sections below its "theater" root:
    1. "player_settings"
      The "player_settings" tree allows you to set character entity stats including point rewards, max carry weight and movement speeds.
  • default_gear.theater
    The default_gear theater which defines the gear objects available to a character entity, has the following sections below its "theater" root:
    1. "player_gear"
      The "player_gear" tree contains the definitions of gear in 3 categories: Armor, Vests and Accessories.
  • default_weapon.theater
    Inherits: "base_weapon.theater", "base_common_ammo.theater", "base_explosives.theater"
    The default_weapon theater defines the weapon objects available to a character entity. It has the following sections below its "theater" root:
    1. "weapons"
      The "weapons" tree contains all weapon definitions, including explosives (Note that an explosive "weapon" differs from the "explosive" entity which is defined elsewhere in this file)
    2. "explosives"
      The "explosive" tree contains all explosive entity definitions, note that the entities differ from the explosive weapon itself, example: The RPG-7 Is a weapon but the rocket it fires is an entity
  • default_weapon_upgrades.theater
    Inherits: "base_weapon_upgrades.theater"
    1. The "weapon_upgrades" tree contains the attatchments that go onto weapons in the primary and secondary slots, where on the weapon they attach to and which weapons they work with.
Customizing Insurgency: Creating the theater file
WARNING: DO NOT MODIFY INSURGENCY'S DEFAULT THEATERS.
If you want to customize something, make your own theater file. Let us go over how:

  • Step 1:
    Create a blank text file called *your theater name*.theater (Ensure that you save it in such a way that the file type is .theater)
  • Step 2:
    Call the files your theater will be using. Best beginner's practice (Note: this is in my experience) is to call default.theater, which in turn already calls all the necessary component theaters. Therefore, the very beginning of your file should look like this:
"#base" "default.theater" "theater" { }
  • Step 3:
    After declaring your theater, you will be able to insert one of the default theater subsections (defined in the previous part of this guide.) For instance if you wanted to modify a weapon, you would call the "
How To Make: Custom Squads & Loadouts
Teams structures are defined uniquely for each gamemode_theater.
The key nesting structures for defining teams is as below:

"theater" { "teams" { "security" { } "insurgents" { } } "player_templates" { "template_name" { } } }

These are the team and unit template definition sections. They do not correlate to any base_file.theater, so you will either have to build it in your gameplay theater, or inherit it from default.theater with #base. The "teams" section depends on content from the "player_templates" section.
"security" //Subsection for the security team { "name" "Security" //Name of team {This can be customized} "logo" "gameui/fac_sec" //Logo of team {This can be customized} "squads" //Subsection for squads in this team { } }
The "security" and "insurgents" teams are the default game aliases, and will be where we define our squads. Each team can hold multiple squads.
"squads" { "Squad 1" //Name of squad {This can be customized} { "Squad Position 1" "unit_template_1" "Squad Position 2" "unit_template_2" "Squad Position 3" "unit_template_3" "Squad Position 4" "unit_template_4" "Squad Position 5" "unit_template_5" "Squad Position 6" "unit_template_6" "Squad Position 7" "unit_template_7" "Squad Position 8" "unit_template_8" } //End of Squad 1 subsection "Squad 2" //Name of squad {This can be customized} { "Squad Position 1" "unit_template_1" "Squad Position 2" "unit_template_2" "Squad Position 3" "unit_template_3" "Squad Position 4" "unit_template_4" "Squad Position 5" "unit_template_5" "Squad Position 6" "unit_template_6" "Squad Position 7" "unit_template_7" "Squad Position 8" "unit_template_8" } //End of Squad 2 subsection }
Each squad can hold a maximum of 8 members defined in the form: "Squadmember Title" "unit_template". The value of "unit_template" is defined in the "player_templates" section after "teams".

Suggestions:
  • Remember to close the "teams" section with } before starting the "player_templates" section.
  • Avoid using the same template more than once in a squad, as it can lead to errors.
  • If you are using default.theatre as a #base, consider creating your own unit templates, this decreases your chance of errors.

"player_templates" //The player template section, contains templates for both teams { "unit_template_1" //Here where the unit is defined { } "unit_template_2" { } "unit_template_3" { } "unit_template_4" { } "unit_template_5" { } "unit_template_6" { } "unit_template_7" { } "unit_template_8" { } }
The "player_templates" section contains all unit template definitions for both the security and insurgent teams (they are not seperate.) Each template gets its own subsection under "player_templates"

"unit_template_1" //This subsection defines the unit_template_1 character { "models" //This subsection defines the player model { "player" "models/characters/security_specialist.mdl" "viewmodel_hands" "models/weapons/v_hands_sec_l.mdl" } "team" "security" //Does this unit belong to "security" or "insurgents" "print_name" "Recon" //Name of unit in overlay {This can be customized} "buy_order" //This subsection defines the template's default loadout { "weapon" "weapon_kabar" //Equip a melee weapon "weapon" "weapon_m590" //Equip an M590 in the primary slot "weapon_upgrade" "optic_eotech" //Add a holo sight to the M590 "weapon" "weapon_m45" //Equip an M45 in the secondary slot "weapon" "weapon_m67" //Equip an M67 grenade in the explosive slot "gear" "sec_heavy_armor" //Equip Heavy Armor "gear" "sec_chest_rig" //Equip Chest Rig } "allowed_items" //This subsection sets what equipment can be used by the template { "weapon" "weapon_m590" "weapon" "weapon_m16a4" "weapon" "weapon_m14" "weapon" "weapon_m4a1" "weapon" "weapon_m45" "weapon" "weapon_m9" "weapon" "weapon_makarov" "weapon" "weapon_m67" "weapon" "weapon_m18" "weapon" "weapon_anm14" "weapon" "weapon_m84" "weapon" "weapon_kabar" "gear" "sec_chest_carrier" "gear" "sec_chest_rig" } "cost_modifiers" // (Optional) Allows you to micromanage costs at the class level { "weapon" // List of modified costs to weapons for this class { "weapon_m4a1" "1" // Add 1 point to the cost of this item for this class } "weapon_upgrade" // List of modified costs to weapon upgrades for this class { "optic_2xaimpoint_sec" "-1" // Subtract 1 point from the cost of this item for this class "sec_silencer" "-1" // Subtract 1 point from the cost of this item for this class } } } //End of "unit_template_1" definition

Suggestions:
  • A player template must be closed before another is opened.
  • A template must carry a melee weapon in it's buy_order.
  • A weapon listed in buy_order must be in allowed_items
  • The kit selection menu can hold 5 items, but the sixth will clip at the top of the screen, so try to limit the amount of items in each category (primary, secondary, explosive etc.)
  • Some objects will show up in the kit menu even when excluded from allowed_items, this is due to team dependence parameters, which we will cover later in the guide.
How To Make: Custom Gear & Accessories
All default gear and accessories are defined in the default_gear.theater file, which is then included by the default.theater file. The key nesting structure of the gear theater is as below:

"theater" { "player_gear" { // All common gear "?nightmap" { // Items under this subsection are only available on maps designated as night maps } } }


There are 3 main "slot" types of gear:
  • "armor"
  • "vest"
  • "accessory"

Armor determines damage reduction from incoming attacks. The basic formula for damage reduction is: damage_taken = damage_amount * hitgroup_reduction. Using the armor example below, if a player is hit in the chest by a round with a 100 damage base, they will take 100 * 0.40 = 40 damage.
Here is an annotated example of the security light armor:
"sec_light_armor" //The default light armor for security { "print_name" "#gear_light_armor" //Name of the gear in UI "print_desc" "#gear_light_armor_desc" //Description of the gear in UI "gear_slot" "armor" //The gear slot determines where the object appears on the menu "gear_cost" "0" //The default supply cost of the item "gear_weight" "64" //The weight of the object added to total weight "DamageHitgroups" //This subsection lists the damage reduction applied to the 7 hit groups { //-Bodypart- -percent of incoming damage to be applied to player (1=100%)- "HITGROUP_HEAD" "1.00" // 0% Damage reduction to headshots "HITGROUP_CHEST" "0.40" // 60% Damage reduction to chest shots "HITGROUP_STOMACH" "0.40" // 60% Damage reduction to gut shots "HITGROUP_LEFTARM" "1.00" // 0% Damage reduction to arm shots "HITGROUP_RIGHTARM" "1.00" // 0% Damage reduction to arm shots "HITGROUP_LEFTLEG" "1.00" // 0% Damage reduction to leg shots "HITGROUP_RIGHTLEG" "1.00" // 0% Damage reduction to leg shots } "team_access" "security" //Security use only }

Vests are a bit more complicated than armor. They determine the amount of weapons and ammunition a player can carry. By default, the game allows a player without any vest to hold 1 Primary, 1 Secondary and 1 Explosive.
Here is an annotated example of the security chest rig:
"sec_chest_rig" { "print_name" "#gear_chest_rig" // The name of the vest in the UI "print_desc" "#gear_chest_rig_desc" // The description of the vest in the UI "gear_slot" "vest" // The gear slot the weapon occupies "gear_cost" "1" //The point cost of the vest "gear_weight" "64" //The weight of the gear "extra_ammo" //This subsection lists how much extra ammo this vest gives the player { "primary" "2" //Add two extra primary weapon magazines to the player's inventory "secondary" "2" //Add two extra secondary weapon magazines to the player's inventory "explosive" "0" //Add no extra explosives to the player's inventory } "weapon_slots" //Allows additional weapon slots to be added to the default amount { "explosive" "1" //When this vest is worn there are default+1 "explosive" slots open } "team_access" "security" //security use only }
Be very careful with weapon slots, as they can adversely affect the inventory UI. When adding extra slots under "weapon_slots" remember that the number is indexed from zero. The default player always has one of each slot (primary, secondary, explosive) so always treat these numbers as 1+(Your number.)
The "extra_ammo" subsection can also be used to allocate ammo to additional and specific slots.
For this example, pretend the model vest is configured like:
"weapon_slots" { "primary" "1" // default + 1 additional primary slot = 2 primary slots in UI "explosive" "2" // default + 2 additional explosive slots = 3 explosive slots in UI }

For this layout, the "extra_ammo" subsection could look like:
"extra_ammo" { "primary" // Opening up a slot subsection allows you to micromanage extra ammo amount { "0" "6" // Add "6" extra magazines for a weapon in slot "0" (default primary) "1" "3" // Add "3" extra magazines for a weapon in slot "1" (extra primary slot) } "secondary" { "0" "3" // Add "3" extra magazines for a weapon in slot "0" (default secondary) } "explosive" { "0" "1" // Add "1" extra explosive in slot "0" (default explosive slot) "1" "2" // Add "2" extra explosives in slot "1" (extra explosive slot) "2" "2" // Add "2" extra explosives in slot "2" (extra explosive slot) } }

Last is the accessory slot, which holds any miscellaneous gear not belonging to the above types. The only current default accessory is the Night Vision Goggles item. See below.
"ins_nightvision" { "print_name" "#gear_nvg" // Item name "print_desc" "#gear_nvg_desc" // Item description "gear_slot" "accessory" //Item slot "gear_cost" "2" // Item point cost "gear_weight" "30" // Item weight "entity" "nvg" "model" "models/characters/a_nightvision.mdl" //The helmet model for the NVG "settings" //misc. settings for the nightvision effect { "material" "dev/ins_nightvision" //particle effect for nvg "sound_on" "Weapon_NVG.InsNvgOn" //activation sound "sound_off" "Weapon_NVG.InsNvgOff" //deactivation sound "chromatic_aberation" "0" "dust_power" "1.2" "fade_in_time" "0.3" "fade_in_hold" "0.1" "fade_in_tonemap" "170" "fade_out_time" "0.5" "fade_out_hold" "0.1" } "team_access" "insurgent" //which team can purchase this object }

If you wish to use the NVG on day/custom night maps you must remove the NVG from the "?nightmap" section. This can be done using the following easy workaround:
//First create a new entry under "player_gear" but outside of the "?nightmap"{} subsection "sec_dayvision" // Custom "player_gear" entry { "import" "sec_nightvision" //"import" clones the stats of the security NVG onto our new item "gear_cost" "0" // Let us remove the item point cost "gear_weight" "0" // And the Item weight "team_access" "security, insurgent" //Lets give both teams access to the new NVG }
And now we have NVG that can be equipped at any time :^)

Suggestions:
  • Extra slots are calculated when the theater is loaded, be aware that the highest number of extra slots will be available to all players, unless restrictions are put in place by the theater maker.
  • Gear items can be class restricted, but try avoid restricting vests, as the way extra slots are allocated can be broken by the global availability of the item in question.
  • The UI menu expands to accommodate weapon slots and their attachments, however if too many slots are filled the 'equipped' inventory UI begins to clip through the top of the screen, Consider this when adding extra weapon slots.
  • If the UI does not update after changing weapons in a many slot scenario, try clicking the labels of the weapons slots to refresh the UI panel.
How To Make: Custom Weapons & Explosives
Foreword:
Modifying and creating weapons while superficially simple, gets pretty hairy when you start to peck apart the little details. The default weapons theater is very closely dependent on the custom ammunition theater, so keep that in mind when building objects here.

The structure of the default weapons theater is as follows:
"#base" "base_weapon.theater" // please note dependencies "#base" "base_explosives.theater" "#base" "base_common_ammo.theater" "theater" { "weapons" {} "explosives" {} }
The "weapons" section defines the interactive object a player equips in game. That goes for everything from the AT4 to the TOZ.
The "explosives" section defines all munitions belonging to the "projectile" weapon family, that is, weapons that fire a non hitscan entity (anything that isn't a bullet). This is important because hitscan weapon munitions (bullets) cannot have explosive properties, and projectile munitions (like an RPG7 warhead or a thrown brick of C4) have a strict speed limit. All "explosives" should have a corresponding entity in "weapons", but not all objects in "weapons" are linked to entities in "explosives"

Lets take a look at the standard AKM weapon code:
"weapons" { "weapon_akm" { "import" "ballistic_base" "weapon_class" "rifle_automatic_fire" "print_name" "#weapon_akm" "print_desc" "#weapon_akm_desc" "view_model" "models/weapons/v_akm.mdl" "world_model" "models/weapons/w_akm.mdl" "rounds_per_minute" "600" "weapon_slot" "primary" "act_table" "shortrifle" "weapon_abilities" "ironsight" "weapon_weight" "200" "weapon_cost" "0" "class_restricted" "1" "barrel_length" "22" "viewmodel_attachments" { "foregrip" { "model" "models/weapons/upgrades/a_standard_akm.mdl" "fallback_for_slot" "underbarrel" } } "fov" { "priority" "0" "fov_wpn_default" "60" "fov_wpn_sprint" "60" "fov_wpn_ironsight" "68" "fov_wpn_focus" "73" "fov_plr_ironsight" "-25" "fov_plr_focus" "-12" } "sounds" { "shot_single" "Weapon_AK47.Single" "shot_single_local" "Weapon_AK47.SingleLocal" "shot_silent" "Weapon_AK47.SingleSilenced" "shot_silent_local" "Weapon_AK47.SingleSilencedLocal" "empty" "Weapon_AK47.Empty" "clipin" "Weapon_AK47.Magin" "clipout" "Weapon_AK47.Magout" "boltback" "Weapon_AK47.Boltback" "boltrelease" "Weapon_AK47.Boltrelease" "rofdown" "Weapon_AK47.ROF" "rofup" "Weapon_AK47.ROF" } "particles" { "particle_muzzleflash_1st" "muzzleflash_akm_1p" "particle_muzzleflash_3rd" "muzzleflash_akm_3rd" "particle_tracer" "weapon_tracers_green" } "recoil" { "recoil_lateral_range" "-0.75 1.00" "recoil_vertical_range" "2.775 3.225" "recoil_aim_punch" "0.5 0.8" "recoil_rest_rate" "7" "recoil_rest_delay" "0.12" "recoil_roll_range" "-1.8 -1.8" "recoil_roll_rest_rate" "190" "recoil_additional_rest_per_shot" "2.5" "recoil_shot_reset_time" "0.5" "recoil_shot_max_shots" "6" "recoil_punch_additive_factor" "0.85" } "ballistics" { "spread" "0.22 0.22 0.22" "FireModes" "semi, full" "bulletcount" "1" "maxrange" "10000" } "ammo_clip" { "ammo_type" "762x38_box" "clip_max" "12" "clip_max_rounds" "30" "clip_default" "3" } "attachments" { "attachment_addon" "primary" } "kitui_offset" { "position" "23 -3 1" } "team_access" "insurgent" } }
Theres alot of stuff going on here, some self explanatory and some not, so let's take a closer look at each of the sections.

Directly under the subsection "weapon_akm" we have:

  • "import" : The template/object from base_weapon.theater to use as the weapon's base. Available types are:
    1. "pistol_base" (base pistol template, imports ballistic_base)
    2. "ballistic_base" (base firearm template, imports weapon_base)
    3. "weapon_base" (base weapon template)
    4. **TIP** Any weapon already defined in the default_weapon file can be used as a template for a new weapon with the "import" command. for example: "import" "weapon_akm" will tell the weapon to mimic the exact stats of the AKM unless otherwise modified.

  • "weapon_class" : The class of the weapon. The weapon classes available are:
    1. Ballistic weapons: "rifle_automatic_fire" (ex. AKM), "rifle_controlled_fire" (ex. M16a4), "smg" (ex. Mp40), "pistol" (ex. M9), "shotgun" (ex. M590), "lmg" (ex M249), "sniper_rifle" (ex. Mosin nagant rifle)

    2. Ordinance/projectile weapons: "grenade_frag" (ex. F1 grenade and M67 grenade), "grenade_incendiary" (ex. Anm14 and Molotov), "grenade_smoke" (ex. M18 grenade), "grenade_flash" (ex. M84 grenade), "other_explosive" (ex. C4 and IED), "launcher" (ex At4 and M203 grenade launcher), "melee" (ex Kabar knife)

  • "print_name" : The weapon's name in the UI
  • "print_desc" : The weapon's description in the UI
  • "view_model" : The weapon's first person model
  • "world_model" : The weapon's third person model
  • "rounds_per_minute" : The weapon's rate of fire
  • "weapon_slot" : The weapon's slot in UI
  • "act_table" : The weapon's animation table
  • "weapon_abilities" : The weapon's default deploy actions (ironsight, bipod)
  • "weapon_weight" : How many in game units the weapon weighs (Will be explained later)
  • "weapon_cost" : Base supply point cost of this weapon
  • "class_restricted" : Boolean. 0- available to all classes by default. 1- only available if listed
  • "team_access" : Which team can access this weapon. Linked with "class_restricted"
  • "barrel_length" : Distance before a weapon folds against part of the world (collision length
How To Make: Custom Upgrades
How To Make: Custom Ammunition ***critical***
How to make: All of that work together
Additional advice and warnings
22 Comments
< >
游侠--和平至上 27 May, 2021 @ 5:01am 
how to custom ammo ; I want to create an new 762x54R ;the origin 762x54 use the 762x51 Nato Danmage .
1v4n94 18 Aug, 2020 @ 7:58am 
It works, but not in the way it is recommended, since some of the default theater files get replaced.
1v4n94 18 Aug, 2020 @ 7:56am 
I'd like to make my mod work when using overwrite command, and not by modifying the default files. How do I make it so it works as I intend? I did not add custom weapons nor anything else other than changing the default values. Here's my mod: https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=1851500508
Cap'n Beens 17 Aug, 2020 @ 4:40pm 
HELP :) I can't get my custom theater to work. My server loads it (confirmed with mp_theater_override command), but when I try to connect to the server, it gives me 0\0 players and says the server is full (checkpoint mode). I then went back in and changed the map from a checkpoint map to a different mode, which let me in, but then wouldn't let me choose a team/loadout. I set mp_theater_override and I do NOT set sv_playlist as I read that causes errors.

I also do not see a scripts\theaters folder in my insergency dir, so I just created it manually and tried placing my custom theater in there, then tried copying all theaters into that dir. Nothing seems to work. I even re-downloaded a new server and tried nothing else but setting a custom theater. I have tried modding just the section I want to mod (right now just trying to change the name of the light armor, just to prove custom theaters are working).

Help is much appreciated!

NOTE: Source/metamod never worked, not installed!
bird0861 7 Jul, 2020 @ 5:28am 
the link for GFScape is a dead link now
Ketocity 17 Nov, 2018 @ 1:58pm 
Hi there, very good guide! But how can I use the "logo" "gameui/my_own_flag" option on my dedicated server? Where do I have to place the custom Image? Thanks in advance!
ToddTheRuse 5 Jul, 2018 @ 3:42pm 
Gizmo. Its not a link, its a header with no body, that part wasnt filled out.

to make your server use the theater file, include this line in each server_{gamemode}.cfg file:
mp_theater_override {theater name for this game mode}

this is what I did for my theater mod.
Gizmo 5 Jul, 2018 @ 5:46am 
Clicking / Selecting "How to make: All of that work together" doesn't do anything.
Like how do I get my listenserver.cfg to see and use my modded "mod_default_checkpoint.theater" file?
Lawanater 26 Jan, 2018 @ 6:03pm 
hey sent you a friend request. I got a few questions on theater files and would like to get your thoughts
Shadycuz 18 May, 2017 @ 10:22am 
Hey Gypsy, could you help me get the suicide vest working again? I tried using your absoluteharlemv58b and it didn't work and I tried pasting the suicide vest into my knife only theater but it doesn't work. I get error success written backwards as the model and instead of the name of the weapon I get weapon_suicidevest