Gearsc

Gearscript Walkthrough


Introduction to Gearscripts
A gearscript (GS) is a script file read by the mission to assign gear to infantry units and cargo to vehicles in a mission. One gearscript is required per faction - they operate on the NATO, AAF and CSAT troops, and each side's vehicle classes.
Each side present in the mission is required to use a gearscript - we don't use alternatives such as DSF's factions. If it's not NATO, AAF or CSAT, it's incompatible with our zeus and mission framework. If you neglect this, don't complain if your mission is denied by QA.

Creating a gearscript can be as simple or as complex as you need or want. Putting time and thought into them is encouraged, and this walkthrough will take you through all the steps to make a comprehensive GS.

Glossary of terms:
Side - The side of the unit; BLUFOR, OPFOR, INDFOR
Class- The class of unit; Rifleman, Grenadier etc.
Classname - The name by which the game refers to any item. This can be anything from a soldier class, a magazine, a hat or a banana.
Define - A definition in a gearscript. Can be comprised of one or multiple classnames.
Inheritance - Some classes may inherit properties from others, to avoid redundantly re-stating said properties.
Property - A proprety of a class, as defined in a gearscript. This can be weapons, vests, uniforms, magazines etc.
Export List - The right-hand list seen on the right-hand side of the screen in Virtual Arsenal
Export Button - The Export button displayed beneath the Export list
Vanilla Export Button - The Export button along the bottom of the screen in Virtual Arsenal.

Setup:
Notepad++ - Probably the best, most lightweight text-editor for this purpose
Notepad++ SQF Library - Highlights stuff and shit
CMF - Mission framework, contains gearscript templates
Mission making tutorial - If you haven't read this already, go do so first.


== Starting off: ==
1: Open ArmA 3, and from the main menu go to Tutorials > Virtual Arsenal
2: Go through all the tabs on the left, and set each of them to empty, also setting them to "Sorted by Mod" in the top-left drop-down.
3: Once done, hit "Save" at the bottom and name the loadout "#empty".
4: Open cfgLoadouts.hpp in <missionname.island\ in Notepad++
5: Rename baseTemplate_EAST.hpp <missionname.island>\C\Loadouts to SOV.hpp, and open in Notepad++
6: Open common.hpp in <missionname.island>\C\Loadouts in Notepad++

Assuming you've already extracted the framework and given the mission a name and terrain, you will find 3 template .hpp files in <missionname.island>\C\Loadouts.
These are baseTemplate_WEST, _EAST and _IND. Each is pre-configured with different gear sets, but all of it can be changed. If you know one side is going to be Americans, and the other Russians, EAST and WEST are the ones you want to look at.

Throughout this tutorial, we will be using ~50s-era Soviets as an example - if you want to follow in this fashion, that means we'll be starting with baseTemplate_EAST.hpp.
The first thing we will do is give this gearscript a clear, concise name. Rename the baseTemplate_EAST file to "SOV.hpp".

We want to give it a clear, concise name because we're now going to change an entry in cfgLoadouts.hpp. !WARNING! - getting this wrong will result in an immediate CTD when loading the mission in the Eden editor.
Looking at cfgLoadouts.hpp, we see this:
https://i.gyazo.com/114c965649c91ab5d8ec2a916d5b1590.png

The only things we're concerned with are:
allowMagnifiedOptics = 0; (default). Changing this to 1 will allow assignment of any magnified optics as defined by gearscript.
For our example, we will be assigning a scope to Squad Leaders, so set it to 1.

allowChangeableOptics = 1; (default)
This will allow players to select an alternative optic during SafeStart. We're going to assign an alternative scope to the Squad Leader, so leave this at 1.

And finally,
class opf_f {//OPF
	#include "c\loadouts\civilians.hpp"
	};
This is what we renamed the gearscript file for. Once again, pay attention here - we're switching the entry for opf_f to read "c\loadouts\SOV.hpp". If we crash when loading
the mission in editor, we've done this wrong.
<CFGLOADOUTS IMAGE 2 - OPF_F SET>

So, assuming we've done all this correctly, it's time to move on to the gearscript its self!

Gearscript:
Opening up SOV.hpp (Previously baseTemplate_EAST.hpp), we are greeted with this:
https://i.gyazo.com/be9f3a8e2ca6d6a8c4b287699f6b4ae0.png

As you see, between the two lines, some extra input is required. We now tab back into ArmA 3's Virtual Arsenal.
<VIRTUAL ARSENAL IMAGE 1>

Let's break it down. On the left, we have the gear selections. This is divided up into primary weapons, sidearms, launchers, hats, vests, uniforms etc.
On the right, we have our Export list. This is what we'll use to fill the initial part of the gearscript.
Along the bottom, we have several controls. The one we're most concerned with is "Export" - referred to as "Vanilla Export" henceforth.

So, we want an early Cold-War Soviet gearscript. This calls for AKMs, RPG-7s, PKMs, not enough food and too much vodka.
The first field to fill in is "Uniform". This is all 4 uniform items - Uniform, Helmet/Hat, Vest and Backpack. Go through each of the gear tabs on the left, and fill them in as appropriate.
For this, we will choose the M88 uniform from RHS, the 6b47/Vydra-3M (Khaki) from RHSGREF, the SSh-68 (Olive) helmet from the Soviet Pack, and the Sidor backpack from RHS. Once we've filled all these slots, we'll hit "Add uniform" on the Export List.
<VIRTUAL ARSENAL IMAGE 2 - UNIFORM ASSIGNED>

Now we have our uniform assigned, it's time to move on to weapons.
First up is our standard Rifle. This is issued to AARs. For this we'll be using the AKM from RHS, but we want a random chance of it being an AKS-47 instead. For now though, we will just add the AKM in the same fashion.
We select the AKM from the left-hand gear tab, and as before with the Uniform, we click "Set Rifle" on the Export list.

NOTE: If multiple magazine types are added to the arsenal man, these will be added to the export list. Make sure he only has the one type of magazine you want. It's best practice to use magazines from the same mod as the weapon, as some mods like RHS and NIArms have special shit going on with magazines.

NOTE: If you intend for the players to have optics (reddot or otherwise) or any other attachments, you should put them on the rifle via Arsenal before hitting "Set Rifle". This way, JIPs won't be stuck with ironsights.

<VIRTUAL ARSENAL IMAGE 3 - RIFLE ADDED>

The process is the same for all other weapon types:
<VIRTUAL ARSENAL IMAGE 4 - EXPORT LIST FILLED>

At this point, we can hit the Export Button beneath the list, and paste it into the template for a functional gearscript, making sure to glance over it for anything anomalous.
If any #DEFINE says "NotSet" you MUST fix this or bad shit will happen.
A properly-exported gear list will look like this:
<GEARSCRIPT IMAGE 2 - TEMPLATE FILLED>

NOTE: The Export List will aim to give Riflemen enough magazines to equal at least 300 rounds; ARs and MMG 500 rounds. Keep this in mind if assigning bolt-actions etc.
You can reduce or increase the number of a given magazine by changing the number immediately following the classname, eg. "rhsgref_5Rnd_762x54_m38:60" to "rhsgref_5Rnd_762x54_m38:20".

Saving the gearscript and loading the mission, we should see OPFOR looking like this:
<IG IMAGE 1 - GEARSCRIPT APPLIED>


Further Customisation:
However, in this example there are many things we want to change, add and remove. For example, the MP-443 pistol would be anachronistic in an early Soviet gearscript.
Referring to our SOV.hpp, we see a list of #DEFINEs following everything we just pasted in.
<GEARSCRIPT IMAGE 3 - DEFINES>

Adding to and changing defines isn't a worry, but be wary of subtracting from them. More on that later.
For now, we want to replace the pistol with the Tokarev TT-33 from RHSGREF. As you've probably seen, there is no field for the pistol on the Export List. This is what the Vanilla Export button is for, at the bottom of the screen in Arsenal.
Tab back into ArmA 3. Find the Tokarev TT-33 in the left-hand list, and check his vest/uniform to ensure there are magazines present.
Next, hit the Vanilla Export button, and paste the result into an empty text document:
<EXPORT IMAGE 1 - TOKAREV>

We are looking for the classnames related to the Tokarev and its magazines. The former will be around the bottom of the exported text, while the magazines will be in the meaty bit between the middle and top.
<EXPORT IMAGE 2 - HIGHLIGHT TOKAREV & MAG CLASSNAMES>

As you see, the classnames we see are highlighted. We're going to copy and paste these into the pertinent #DEFINEs in the gearscript
<EXPORT IMAGE 3 - GEARSCRIPT TRANSPLANT>

We must ENSURE that, since these are classnames, they are surrounded in quotes - ". Since we want more than one magazine, the classname will read as such: "classname:4".

Now we have our pistol and its magazines defined, great! Start the mission as an AR or SL, and check it out, ensuring players have the proper number of mags and no errors are thrown.
<GEARSCRIPT IMAGE 4 - DEFINES DEFINED>

This process is the same for all the other pre-defined equipment.

Our next step, since we're making a historical gearscript, is to eliminate all pieces of equipment that don't fit the era/faction. In this case, we want to remove the NVGs, MicroDAGR, Chemlights and IR Strobes.

Removing NVGs and chemlights is simple. The NVGs are set in the definitions of the gearscript as BASE_LINKED alongside COMMON_LINKED. Simply removing ",NODS" (Make sure you get the comma too!) from this line will achieve this.
Chemlights are defined along with BASE_GRENADES. The process is the same.
<GEARSCRIPT IMAGE 5 - NODS & CHEM>

For the rest of these items, we need to go into Common.hpp. Note that if you make changes here, you should post it along with the gearscript on the forums.

Common.hpp contains many different definitions that are shared by all gearscripts. More on that later - for now, we're only concerned with the following:
<COMMON IMAGE 1 - COMMON_TOOLS>

Once again, simply delete the pertinent classnames - in this case "ACE_MicroDAGR","ACE_IRStrobe", and save the file.


Class Manipulation
Classes are the gear-sets for each role in the ORBAT. By manipulating the classes, we can further customise each individual class to our preference. This has uses from giving Squad-Leaders different headgear to visually distinguish them, to giving everyone pistols since it's a special-forces team.

The first class we're going to concern ourselves with is Soldier_F, AKA Rifleman. This is the class that ALL others in the gearscript inherit from - if a class doesn't have a given property defined, it will use what is set for the Rifleman. This is expressed as, eg. "class Fic_Soldier_Carbine: Soldier_F". The first classname is the one we're defining here; The second is what it's inheriting its properties from. Note, all classes here reflect an existing unit's classname. These can be seen in the editor by mousing-over a unit in the right-hand list.

<GEARSCRIPT IMAGE 6 - CLASSES>

Here we can see all the properties as defined in Soldier_F. A list of all possible properties is seen immediately above.

So, for our gearscript we want to do five things:
Give FTL+ a 1p29 scope
Give SL+ a choice between the 1p29 or PSO-1
Give SLs a Beret
Give the Rifleman AT an RPG-carrier backpack.


Gearscripts and AI
- GP Count
- Fake NVGs

Gearscripts and TvTs
- Balancing armour v weapons
- GP Count
- Necessary equipment

Misc
- Setting up alternate optic choices
- Randomisation
- Magazine Compatibility
- RHS/NIA magazine-switching/foregrip systems

Troubleshooting
- BAD VEHICLE TYPE
- Missing [/{/]/}/=