[FS 15]Add BasicGears spec

Game Version: Farming Simulator 2015
Programs required: Giant's Editor 6.0.3 upwards | Winzip, Jzip, 7zip or WinRar | Notepad / Notepad++


Modding Index | Vehicle Tutorials


As requested, here is a tutorial for adding Xentro's BasicGears specialization to a mod vehicle. I had to edit out a lot of more in-depth explanatory stuff for complete novices. It was too long to fit in a single post. Hopefully, it will still get the job done. If I can do it, the skill level required is pretty low anyway.

Freeware Tools Required: An app to extract and create zip files. I use 7-Zip. Any equivalent will do.
An advanced text editor, such as Notpad++ (Using the basic Notepad app that comes with any Windows OS is not recommended. Just don't do it.) An app that can open .xls spreadsheet files.
I use OpenOffice, a freeware equivalent to the Windows Office suite.

Step 1: Preparation

The first thing you need to do is get the BasicGears script. Xentro has kindly made his scripts freely available for non commercial use. Use the link below and look in the Farming Simulator 15 - Specializations block Download the BasicGears.zip file.

Unzip the BasicGears.zip to a convenient location of your choosing. Inside are an example xml, BasicGears.lua, “shared” folder containing the hud overlay dds image. Fig:1

Unzip the mod you want to work on. For this tutorial, I have selected one that represents the most possible work that you will have to do.

If your mod does not have a folder for scripts, create a new one to keep things organized. Mine is called “specializations”, as seen below.
Fig:2

Copy the BasicGears.lua from the downloaded BasicGears file. Paste it inside your newly created folder in your mod.
Fig:3

Copy the “shared” folder from the downloaded BasicGears file. Paste it in your mod's root folder. The “shared” folder should contain a dds image that the BasicGears script will use for the in-game hud.
Fig:4
Fig:5

Step 2: modDesc.xml

My example modDesc.xml is about as basic as a modDesc can be. Fig:6

I will need to add several sections: <l10n> section for the in-game help hud text. <specializations> section for calling the BasicGears script. <inputBindings> section for defining input bindings. <vehicleTypes> section for defining a vehicle type.

Your vehicle mod may already have these sections.

Create the text info for the F1 Help hud. Copy / Paste what you need from the code below. If your mod has a <l10n> section, just insert the text definitions. DO NOT create duplicate <l10n> sections.

<l10n>
    <text name="CHANGE_GEAR">
        <en>Change gear</en>
        <de>Gang wechseln</de>
    </text>
    <text name="CHANGE_GEAR_DOWN">
        <en>Gear down</en>
        <de>Herunterschalten</de>
    </text>
</l10n>

Define input bindings for the Downshift command. To prevent in-game conflicts, I chose a keyboard combo that is not used by any other mods that I know of. I also chose an Xbox controller command that suits me. You can always alter these bindings in the in-game controls options screen. Copy / Paste what you need from the code below. Again, DO NOT create a duplicate <inputBindings> section if you already have one.

<inputBindings>
  <input name="CHANGE_GEAR_DOWN" category="VEHICLE" key1="KEY_ralt KEY_l" key2="" button="BUTTON_6 BUTTON_10" device="0" mouse="" visible="true" />
 </inputBindings>

It is not necessary to define an input binding for Upshift. It is already defined in the BasicGears script and uses the default game IMPLEMENT_EXTRA4 binding.

Alternative Method: Westmorgan has posted an alternative method, including altering the Upshift binding. You can find it on page 2 of the support thread for the BasicGears for Giants Vehicles mod.

List the specialization, and it's location within the mod folder structure. Copy / Paste what you need from the code below. Again, DO NOT create a duplicate <specializations> section if you already have one.

<specializations>
        <specialization name="BasicGears"   className="BasicGears"   filename="specializations/BasicGears.lua"/>
    </specializations>

Pay special attention to the filename part. Remember that I put the script in a folder named “specializations”. If you put it in a folder with a different name, fix that filepath in the code you copy / pasted.

Now there has to be a vehicleType to actually add the specialization to. As the mod I'm using does not have one in the modDesc.xml, it is using one of the Giants default vehicle types.
Fig:7

The tractor is using the default Giants vehicle type “tractor”. That's a good start, but I need to know what standard specializations this vehicle type uses. As luck would have it, there is a very handy reference posting over at FSModding.

Now I have all the information I need to create a custom vehicleType. Copy / Paste the code below if your modDesc does not have a vehicleType defined. If your mod does have a custom vehicle type already, just add the BasicGears specialization line as seen below.

    <vehicleTypes>
        <type name="tractorGears" className="Vehicle" filename="$dataS/scripts/vehicles/Vehicle.lua">
            <!--  default Giants specializations for vehicle type "tractor" -->
            <specialization name="animatedVehicle" />
            <specialization name="motorized" />
            <specialization name="steerable" />
            <specialization name="drivable" />
            <specialization name="cylindered" />
            <specialization name="hirable" />
            <specialization name="aiTractor" />
            <specialization name="bunkerSiloCompacter" />
            <specialization name="honk" />
            <specialization name="indoorHud" />
            <specialization name="washable" />
            <specialization name="mountable" />
            <!--  added BasicGears specialization  -->
            <specialization name="BasicGears" />
        </type>
    </vehicleTypes>

Step 3: Vehicle xml

Before I forget, I need to change the vehicle type in the tractor xml to “tractorGears”.
Fig:8

Go ahead and find the motor calculator spreadsheet in the FS 15 main install folder. ……/Farming Simulator 15/sdk/vehicleMotorCalculator.xls Open that, we'll be needing it soon.

Before we add the BasicGears stuff, I want to start with the <motor> section.

Let's break it down into components. First, the torque curve. It is already set up to Giants default values. That is good for us. Altering the torque curve is way beyond the scope of this tutorial. To keep things simple, make sure your torque curve values match this for a tractor mod:

    <torque normRpm="0.45" torque="0.9"/>
     <torque normRpm="0.5" torque="0.97"/>
     <torque normRpm="0.59" torque="1"/>
     <torque normRpm="0.72" torque="1"/>
     <torque normRpm="0.86" torque="0.88"/>
     <torque normRpm="1" torque="0.72"/>

Now the top line. If I compare it to the motor section of a similar default Giants tractor, there are only a few minor differences that stick out. To keep this at beginner level, I will adjust a few things to make it as close to Giants default motor as possible. Specifically, the minRpm and lowBrakeForceScale. You can always come back later and experiment with changing things like that to your preference. Adjustments made:

     <motor torqueScale="0.375" minRpm="1000" maxRpm="2200" maxBackwardSpeed="15" brakeForce="2" lowBrakeForceScale="0.22" lowBrakeForceSpeedLimit="1" minForwardGearRatio="20.5" maxForwardGearRatio="130" minBackwardGearRatio="50" maxBackwardGearRatio="130">

The torqueScale will determine the generated horsepower @ max rpm. As we are using the Giants default torque curve, it is simple to get a good torqueScale value. The mod author specifies that this tractor has 85 horsepower. A simple formula is HP divided by 225.5 which works out to 0.3769….. The current torqueScale value is close enough, so I'll leave it alone. (If you change the torque curve, the formula changes. I'm not getting in to that here.)

Now let's look at minForwardGearRatio and maxForwardGearRatio. The minForwardGearRatio determines your top end speed. maxForwardGearRatio is the low end speed. If you are not familiar with how gear ratios work, this can appear counter-intuitive at first. Just take my word for it.

Let's check the minForwardGearRatio value of “20.5” with the vehicleMotorCalculator.xls spreadsheet. Go to the second section labeled “Calculate speed for some motor RPM”. Enter 20.5 for Gear Ratio. Enter our maxRpm value of 2200 for Motor RPM. We get a calculated speed value of 40.45 km/h. I'm good with that, we'll leave it alone.

Now the maxForwardGearRatio. I already know that I am going to want my BasicGears low gear to have a top speed of 5 km/h. This time we will use the first section of the motor calculator labeled “Calculate gear ratio from max speed and motor RPM” Enter 5 for Max KM/H. Enter our maxRpm value of 2200 for Max Motor RPM. We get a calculated Gear Ratio of 165.87 (rounded off to 165 gives a speed of 5.02 km/h)

So I know that my maxForwardGearRatio needs to be changed to 165 or more. After making that change, my <motor> section looks like this:

    <motor torqueScale="0.375" minRpm="1000" maxRpm="2200" maxBackwardSpeed="15" brakeForce="2" lowBrakeForceScale="0.22" lowBrakeForceSpeedLimit="1" minForwardGearRatio="20.5" maxForwardGearRatio="165" minBackwardGearRatio="50" maxBackwardGearRatio="130">
        <torque normRpm="0.45" torque="0.9"/>
        <torque normRpm="0.5" torque="0.97"/>
        <torque normRpm="0.59" torque="1"/>
        <torque normRpm="0.72" torque="1"/>
        <torque normRpm="0.86" torque="0.88"/>
        <torque normRpm="1" torque="0.72"/>
    </motor>

Add in the gear definitions. I like to keep the </BasicGears> section near the top of the xml so I can find it quick for tweaking. So, I make a bit of space under the motor section and Copy / Paste the code below.

    <BasicGears inputBinding="IMPLEMENT_EXTRA4" inputBinding_down="gearDown" resetGear="false" activeInput="false">
        <gear value="165" />   <!-- 5 kmh -->
        <gear value="x" />     <!-- 7.5 kmh -->
        <gear value="x" />     <!-- 10 kmh -->    <!-- keep a 10 km/h gear for matching speed with combines -->
        <gear value="x" />     <!--  12.5 kmh -->
        <gear value="x" />     <!-- 15 kmh -->
        <gear value="x" />     <!-- 23 kmh -->
        <gear value="x" />     <!-- 30 kmh -->    <!-- keep a 30 km/h gear for matching speed with traffic vehicles -->
        <gear value="20.5" />  <!-- 40.4 kmh -->
    </BasicGears>

The pre-defined <!– ## kmh –> notes are to avoid confusion. We want to get our gears in the right sequence, and have an actual strategy in place for the incremental steps. Now we are going to calculate the missing gear ratio values.

We already determined that our low gear would be set up for 5 km/h and a gear ratio of 165. We also determined that this tractor's top end speed is 40.4 km/h at a gear ratio of 20.5. I have already filled those in. Adjust the high gear speed/gear ratio for your tractor. You may need to add more gears if you have a faster tractor. I would recommend not much more than 10-ish km/h between gears once you get into the high end (over 30 km/h). I would also strongly encourage you to keep the small step increments up to at least 15 km/h. That jump between 15 and 23 km/h might even be too much. I'm still experimenting with that.

For a frame of reference, you might want to go to tractordata.com and look at the transmission data for some tractors with conventional gearboxes. You will see that the speed increase between low end gears is small. I'm not going to get into a detailed explanation of the principle. Just suffice it to say that the basic concept translates to FS gameplay pretty darn well. You will, at some point, appreciate having all the low end gears. You might even find that you want more low end gears with smaller steps. I'm still working that out myself.

Okay, back to work. Let's calculate our gear ratio for the other gears. We will use the first section of the motor calculator labeled “Calculate gear ratio from max speed and motor RPM” Enter 7.5 for Max KM/H Enter our maxRpm value of 2200 for Max Motor RPM. We get a calculated Gear Ratio of approximately 110.5 for 2nd gear.

Go to the tractor xml and put this value in for 2nd gear.

    <BasicGears inputBinding="IMPLEMENT_EXTRA4" inputBinding_down="gearDown" resetGear="false" activeInput="false">
        <gear value="165" />     <!-- 5 kmh -->
        <gear value="110.5" />  <!-- 7.5 kmh -->
        <gear value="x" />       <!-- 10 kmh -->    <!-- keep a 10 km/h gear for matching speed with combines -->
        <gear value="x" />       <!--  12.5 kmh -->
        <gear value="x" />       <!-- 15 kmh -->
        <gear value="x" />       <!-- 23 kmh -->
        <gear value="x" />       <!-- 30 kmh -->    <!-- keep a 30 km/h gear for matching speed with traffic vehicles -->
        <gear value="20.5" />  <!-- 40.4 kmh -->
    </BasicGears>

Repeat this procedure for all the remaining gears. What? You thought I was gonna do it for you?

Now you are familiar enough with the process that you can calculate the gear ratios for any number of gears/speeds you want.

Step 4: Testing

We are ready for a test drive. Zip up you mod and put it in the mods folder.

I like to make a new game in an empty slot for testing, and use a money cheat.
The only concern here is to get the testing done.

Check the ability to purchase your mod, crank her up and engage cruise, run up and down the gears one at a time to verify your shifting is functional and the gears are sequenced correctly, check the log.txt for errors/warnings even if everything seems okay.

If you can't buy your mod, you probably made an xml editing error somewhere. The log.txt will give you some clue.

Enjoy.
tater


Original Author: tater salad | Date: September 21, 2015

Modding Index | Vehicle Tutorials