Welcome, Guest. Please login or register. Did you miss your activation email?

Author Topic: [v0.5] NPC Equipment Kits 2.0 Tutorial  (Read 204 times)

0 Members and 1 Guest are viewing this topic.

Offline BIZ

  • 32-Bit Hobo
  • *
  • *
  • +0% chance to make useful post
  • BIZ hides in shadows.
    • BSNOOCH.COM
[v0.5] NPC Equipment Kits 2.0 Tutorial
« on: February 22, 2021, 04:43:04 AM »
NPC Equipment Kits 2.0
Current Ver: BSMOD v0.5.7a



With the new and improved NPC Equipment Kits, you are able to add equipment (items and models) into an NPC's inventory in a two-step process using plain text files. These equipment items will appear attached to NPC's and can be made to have numerous effects.

The files are located at:
.../BSMOD/scripts/npc_equipment.txt
.../BSMOD/scripts/npc_equipment_kits.txt


Equipment Kits are controlled in-game by the cvar:
sm_npc_enable_equipmentkits
valid settings are: 0=Off;1=On



STEP 1 - Creating Equipment

The first part of the process of creating Equipment Kits is to define different types of equipment to give to NPC's. To do this we will use the text file located at:
.../BSMOD/scripts/npc_equipment.txt

First thing is first, your npc_equipment.txt file begins with the following section:

Code: [Select]
BSMODEquipment {}
This is our opening array for the file, and likely lets the game know that all of the data that follows are different types of equipment. Everything you add to this file needs to go between the two curly braces, period. If you add stuff outside of these braces, you are going to have a bad time (i.e. best case the equipment won't work, or worst case, your game will crash.)

Now here is the basic format of how equipment is added:

"EquipmentName"
{   
   "key" "value"
   "key" "value"
   "key" "value"

}

Lets break it down:

EQUIPMENTNAME: Give the piece of Equipment that you are creating a unique name for the game to refer to.
Example: If you are creating a hat for a citizen, you could name it "Hat_Citizen_01".

KEYVALUES: Keyvalues are two part entries which give our equipment different characteristics and attributes. They can be used to define anything from the model to use for the piece of equipment, to where we attach the equipment on an NPC.


We will now go over the different KEYVALUES available to us in BSMOD. You may use any combination of the following for each piece of equipment depending on how you want the equipment to function.

LIST OF EQUIPMENT KEYVALUES:
Code: [Select]
"Model" "<model_path>" : Points to a model file to use for this piece of equipment.

"Attach" "<attachment_name>" : An attachment point to use on an NPC.

"Rotate" "<X Y Z>" : Allows setting additional rotation to the attachment angles. Can use positive and negative numbers.

"Offset" "<X Y Z>" : Allows setting an additional space offset from attachment point origin. Can use positive and negative numbers.

"Durability" "<min> <max>" : Set the range of health that this piece of Equipment should have. When equipment health reaches 0, it breaks. When min and max durability are different, the game randomly selects a number between the the two to use as equipment health. Use -1 for infinite health.

"Gibs" "<model_path>" : Set a model to use for gibs when this equipment breaks.

"GibDissolve" "<bool>" : Should gibs dissolve when Equipment breaks? 0=No;1=Yes.

"BreakSound" "<Sound_ID>" : Define a sound to play when the Equipment breaks. Must use SoundId.

"BreakOnDeath" "<bool>" : Should this Equipment break when NPC dies? 0=No;1=Yes.

"StumbleOnBreak" "<bool>" : Should the NPC play a stumble animation if it has one, when this Equipment breaks? 0=No;1=Yes.

"ExplodeOnBreak" "<bool>" : Should this Equipment explode when it breaks? 0=No;1=Yes.

"ExplodeType" "<int>" : Defines explosion type. 1=Normal;2=CombineBall.

"ExplodeDamage" "<int>" : Define the amount of damage the explosion does.

"ExplodeRadius" "<int>" : Define the radius in which the explosion does damage.

"SpawnEntOnBreak" "<string>" : Define an entity by classname which will spawn when this Equipment piece breaks. You can alternatively use a path to a model and it will spawn a prop_physics using that model.

"SpawnCount" "<int>" : Number of entities to spawn when Equipment breaks.

"SpawnVelocity" "X Y Z" : Add velocity to the spawning entities.

"BaseColor" "<R G B>" : Specify a color to add to this Equipment model in RGB format. From 0-255.

"ColorRange" "<max>" : Create a color range for randomly selecting a color for this Equipment model. Takes RGB value from "BaseColor" and randomly adds or subtracts an amount up to the "ColorRange" max.

"Item" "<classname>" : Specify an item class to attach to NPC.

"FemaleSupport" "<model_path>" : Points to an alternate model file to use for this piece of equipment when it is attached to female NPC (npc_citizen only). In HL2, female citizen variants have slightly different dimensions then their male counterparts.

"Cosmetic" "<bool>" : Sets equipment as cosmetic item. Will not block bullets or break. It will not fall off of ragdoll. 0=Off;1=On.


Now lets look at some example pieces of equipment. Comments are any text preceded by two slashes "//" and are added by me and not read by the engine.

EXAMPLES:
Code: [Select]
BSMODEquipment {

// SMOD-style combine riot shield.
"RiotShield"
{
"Model" "models/misc/shield.mdl" //Path to shield model.
"Attach" "anim_attachment_RH" //Attach to NPC right hand.
"Rotate" "-5 20 0" // Add additional rotation when attaching.
"Offset" "-2 10 -13.5" // Add additional origin offset when attaching.
"Durability" "32 64" // Spawn with between 32-64 health.
"GibDissolve" "1" // Gibs dissolve On Break.
"BreakSound" "Wood_Furniture.Break" // play this sound when breaking.
"StumbleOnBreak" "1" // Enemy stumbles when shield breaks.
"BreakOnDeath" "1" // Equipment breaks when NPC dies.
}
// A unbreakable shield on the arm.
"ArmShield"
{
"Model" "models/misc/armshield.mdl"
"Attach" "LHand" //Attach to NPC left hand.
"Rotate" "10 -180 22" //Rotate model so it faces right way.
"Offset" "0 -5 10" //Moves shield to proper position.
"Durability" "-1 -1" //-1 is infinite health.
}
// A pouch that explodes when broken.
"GrenadePouch"
{
"Model" "models/misc/grenadepouch.mdl"
"Attach" "belt_slot0" //Some attachment point I made up.
"Durability" "10 25"
"ExplodeOnBreak" "1" //Should explode when broken.
"ExplodeType" "1" //Normal explosion.
"ExplodeDamage" "100" //Does this much damage
"ExplodeRadius" "256" //With this much radius
}
// A medic's bag which drops health when broken.
"MedicPouch_Small"
{
"Model" "models/misc/medicbag01.mdl"
"Attach" "lower_back"
"Rotate" "0 180 0"
"Offset" "0 0 -5"
"Durability" "32 32"
"BreakSound" "Cloth.Break" // Play this sound when breaking.
"SpawnEntOnBreak" "item_healthvial" // Spawn minor healthvial when broken.
"SpawnCount" "2" // Spawn 2 of them.
"SpawnVelocity" "200 0 100" // Add some velocity when spawning.
}
// a working healthvial attached to the chest.
"HealthVial_3"
{
"Item" "item_healthvial" //the item class we are attaching.
"Attach" "chest_armor" //where to attach to.
"Rotate" "0 0 90" // rotate it to face up and down.
"Offset" "-10 0 17" // adjust position.
}
// A kevlar vest with a different model for females.
"KevlarVest_01"
{
"Model" "models/misc/kevlar_armor.mdl"
"Attach" "chest"
"Rotate" "0 0 0"
"Offset" "0 0 0"
"Durability" "48 64"
"FemaleSupport" "models/misc/kevlar_armor_fem.mdl" // If NPC is female, use this model.
}
// This is a cosmetic item, for decoration only.
"clipboard"
{
"Model" "models/props_lab/clipboard.mdl"
"Attach" "bs_beltl2"
"Rotate" "90 180 0"
"Offset" "0 2 -5"
"Cosmetic" "1" // Makes this item cosmetic, for decoration only.
}
}


STEP 2 - Using our new custom Equipment to create Equipment Kits

Now that you have defined some custom pieces of equipment, lets take a look at how we create Equipment Kits. Equipment Kits are groups of custom equipment that can be attached to NPC's based on their classname or targetname.

Equipment Kits are handled by a plain text file located at:
.../BSMOD/scripts/npc_equipment_kits.txt


As with the the first file we looked at, your npc_equipment_kits.txt file begins with the following section:

Code: [Select]
BSMODEquipmentKits {}
To repeat, this is our opening array for the file, and likely lets the game know that all of the data that follows are different equipment kits. Everything you add to this file needs to go between the two curly braces, period. If you add stuff outside of these braces, you are going to have a bad time (i.e. best case your equipment kits won't work, or worst case, your game will crash.)


Here is the basic format of how Equipment Kits are created:

"MapName"
{
   "ClassName/TargetName"
   {
      "equip" "EquipmentName"
      "equip" "EquipmentName"
      "equip" "EquipmentName"

      
      "RankedGroup"
      {
         "equip" "EquipmentName"
         "equip" "EquipmentName"
         "equip" "EquipmentName"

      }
   }
}


Okay lets break it down:

MAPNAME: This is the name of the map you want these equipment kits to be used on. It MUST match the name of the map exactly, but please don't include the .bsp file extension. This also opens a new data array.
Example: For map d1_canals_06.bsp you would use "d1_canals_06"

*NOTE ON MAPNAME:
There is one special MapName called "default_map". Placing any data inside this section will apply to every map that DOES NOT have its own MapName entry in the file.


CLASSNAME/TARGETNAME: Now that we've set up which map these EquipmentKits should be used on, we define which NPC they should apply to in that map. We can either apply these Equipment Kits to a class of NPC's by using ClassName, or we can target specific NPC's by their TargetName, a special keyvalue which lets us give NPC's a unique custom name. By setting a ClassName/TargetName, we open a new data array.
Example: To apply EquipmentKits to all Civil Protection units, we would use "npc_metropolice" as their NPC ClassName.
Example: To apply to a specific metrocop name Jimmy, we would use "Jimmy" as a TargetName.

*NOTE ON CLASSNAME/TARGETNAME:
For each map you can include multiple NPC's. In fact you could give every NPC in the game a different kit on every map if you wanted to. A smart move is to make a standard kit for every NPC class in the "default_map" section, and then adjust on a per map basis as desired.

For a list of all NPC classes in HL2, see here: https://developer.valvesoftware.com/wiki/Category:Half-Life_2_NPCs
For more info on how targetnames work, see here:
https://developer.valvesoftware.com/wiki/Targetname


EQUIP: the first (key) part of a keyvalue. Equip tells the game we are going to give this NPC a piece of equipment.

EQUIPMENTNAME: the second (value) part of our keyvalue. Tells the game what type of equipment we are giving to the NPC. EquipmentName needs to be defined in the npc_equipment.txt file, which we covered in STEP 1.
Example: To equip a helmet we made called helmet2, we could use "equip" "helmet2".

RANKEDGROUP: This is a number between 1-99 signifying Rank, which defines a new data array group. A RankedGroup contains another list of Equip and EquipmentName keyvalues. Ranked groups may be randomly selected by the game to spawn with the likelyhood being tied to the Rank number assigned to it, with higher numbers increasing the chance of being selected. You may have multiple RankedGroup's per NPC, but only one will be selected.
Example: Create a RankedGroup with moderately high chances of being chosen by using "60" {}

*NOTE ON RANKEDGROUPS:
It should be noted that Equip/EquipmentName keyvalues placed inside the ClassName/TargetName data array will always be spawned with that NPC, while ones placed inside a RankedGroup will only spawn if randomly selected. In this manner you are able to create baseline equipment for an NPC, while also allowing the game to randomly select extra Equipment to add to the NPC's Kit through the RankedGroups system. By using different Rank numbers in multiple RankedGroups, you can create common and rarer Equipment Kits.



This all might seem a bit confusing, but lets look at some examples that are illustrative. Comments are any text preceeded by two slashes "//" and are added by me and not read by the engine.


EXAMPLES:
Code: [Select]
NPCEquipmentKits
{
//Default_map kits will apply on every map,
//except maps we specifically define in this file.
"default_map"
{
//Give all citizens these Equipments.
"npc_citizen"
{
"equip" "Makeshift_Vest" //Attaching custom equipment.
"equip" "Belt_Holster" //You can have as many of these
"equip" "HealthVial_3" //as you want/need.
}

//Give all combine soldiers these Equipments.
"npc_combine_s"
{
"equip" "FragGrenade_Belt1" // These equipments will always
"equip" "FragGrenade_Belt2" // spawn since they are NOT
"equip" "Holster_Thigh" // in a RankedGroup.

//RankedGroup. If randomly selected by game,
//will add these equipments to this NPC's Kit.
"50"
{
"equip" "RiotShield" //Add a Riot Shield.
}

//Another RankedGroup.
"50" {
//This one left blank to provide a chance for no shield
//to spawn. Both Groups share same Rank # so have even
//chance to be selected.
}
}
}

//Lets define EquipmentKits for a specific map.
"d2_prison_05"
{
//EquipmentKits from default_map won't apply here.
//Lets use these ones instead for all combine.
"npc_combine_s"
{
"equip" "FragGrenade_Belt1"
"equip" "FragGrenade_Belt2"
"equip" "Battery_2"

//RankedGroups. Same as in default_map,
//but this time with a twist...
"50"
{
"equip" "RiotShield" //Add a Riot Shield.
}

"50" {
//This one left blank to provide a chance for no shield
//to spawn. Both Groups share same Rank # so have even
//chance to be selected.
}

//Add an extra ranked group. Lower rank means rarer spawn!
"20"
{
"equip" "RiotShield" //Add a Riot Shield,
"equip" "LegShield_L" //same as before.
"equip" "LegShield_R" //But since this is a rarer
"equip" "FaceMask" //group, also spawn more armor
"equip" "ChestShield" //pieces, to create a
"equip" "BackShield" //heavy combine soldier :)
}
}

//Now lets pretend we added a npc_combine_s named Big_Boss
//to this map. Lets give him a special EquipmentKit instead
//of the regular ones all other combine soldiers get,
//by using his TargetName instead of his ClassName.
"Big_Boss"
{
"equip" "BossBattle_Helmet"
"equip" "BossBattle_Vest"
"equip" "BossBattle_Legs"
"equip" "BossBattle_WeakPoint1"
}
}
}
« Last Edit: February 22, 2021, 05:42:03 AM by BIZ »

 

SimplePortal 2.3.6 © 2008-2014, SimplePortal