Differences

This shows you the differences between two versions of the page.

Link to this comparison view

intropt2a [2017/05/24 14:27] (current)
Line 1: Line 1:
 +====== Introduction to modding - Part 2A - The modDesc ======  ​
  
 +Game Version: ​ FS13 and later\\
 +GE Version: ​ ? and later
 +
 +----
 +
 +[[modding_tutorials|Modding Index]] | [[general_modding|General Modding Tutorials]]
 +
 +----
 +
 +===== Intro =====
 +
 +This tutorial is dedicated to the modDesc and what you need to put in it. It is the sequel to my first tutorial, Introduction to modding Part 1. There will be a tutorial about the XML file itself released in the next few weeks ;) Enjoy!
 +
 +===== Prep Work =====
 +
 +
 +
 +===== Full Details =====
 +
 +Hello everyone, ​
 +
 +As the first part of the introduction to modding tutorial was a success, I decide to make a sequel to it. This part 2 will be dedicated to XML scripting. First, let's concentrate on the modDesc. I will cover the main XML file in the next tutorial that should be released soon enough!
 +
 +I tried to make this as clear as possible, good reading!
 +
 +[b]1. General information [/b]
 +
 +[color=green][i] What is XML used for in FS13? [/​i][/​color]
 +
 +The XML language occupies a key role in how your model will behave in game. What makes the wheel turn? What makes the tipper tip? What defines the speed at which your mod goes? XML does all that. 
 +
 +If you import your model into the game, and don't have a proper XML file to go with it, it won't move, won't be useable, won't react to pretty much everything, basically it will be a static (or dynamic) object that you can't really interact with. 
 +
 +
 +[color=green][i] What is the difference between the modDesc.xml and the X.xml - X being the name of the mod)? [/​i][/​color]
 +
 +The modDesc defines everything that is related to buying your mod. It contains the path to the store image, the mod name, the price, the daily maintenance price, and so on. It also defines (call) the specializations and custom scripts, and it defines the input bindings.
 +
 +The X.xml file is the one that is the most complex to work with - between these two.  That'​s where you will define pretty much everything, from the engine RPMs to the braking force, to the wheel turning angle and the cameras. ​
 +
 +Now that you should have a basic understanding of what XMl is and what it is used for, let's move on to the required things to work with XML.
 +
 +[b] 2. What you will need[/b]
 +
 +Firstly, you will need one essential program in order to make some proper XML scripting. ​
 +
 +[i] Notepad++ [/i]
 +
 +Notepad++ is a wonderful text editor that is totally free, and that will color the code, make it more readable and easier to work with. You can download it here : 
 +[url=http://​notepad-plus-plus.org/​]http://​notepad-plus-plus.org/​[/​url]
 +
 +Of course, you could use another program, although this one is in my eyes the best free to work with. [b]Never [/b] use Notepad (the regular one) to work with XML scripting, it's a pain to work with and you are a lot more likely to make errors if you use it. 
 +
 +
 +Now, you will need three other "​basic"​ things. ​
 +
 +#1. Giants Editor - You need GE to count the node numbers, and to grab all the other details about your model you might need. 
 +
 +#2. Patience - It's not easy to learn and it will take time ;)
 +
 +#3. Brain - You need to use your brain and to have a bit of creativity, my tutorial doesn'​t explain everything and doesn'​t work in every case, you have to use your common sense and experiment a bit to make things right.
 +
 +You have all that? Great! Time to get to work! =)
 +
 +[b] 3. The modDesc.xml file [/b]
 +
 +Let's get into the real subject!
 +
 +FIrst step, create a new file in Notepad++. Name it "​modDesc.xml"​. The easiest way to get the starting code is to grab it from the sampleMod, that Giants provided us.
 +
 +You can find it in your sdk folder, which is located in FS13 main directory. Copy the content from the sampleMod'​s modDesc, and paste it in your newly created file. This is what you should get
 +
 +[code]<?​xml version="​1.0"​ encoding="​utf-8"​ standalone="​no"​ ?>
 +<modDesc descVersion="​9">​
 +    <​author>​My Name</​author>​
 +    <​version>​1.0</​version>​
 +    <​title>​
 +        <​en>​Sample Mod</​en>​
 +        <​de>​Beispiel Mod</​de>​
 +    </​title>​
 +    <​description>​
 +        <​en>​Sample mod description</​en>​
 +        <​de>​Beispiel Mod Beschreibung</​de>​
 +    </​description>​
 +    <​iconFilename>​store_deutzAgrotronX720.png</​iconFilename>​
 +    <​multiplayer supported="​true"/>​
 +    <​storeItems>​
 +        <​storeItem>​
 +            <​en>​
 +                <​name>​Deutz Agrotron X720 Sample Mod</​name>​
 +                <​description>​
 +<​![CDATA[This is the sample mod]]>
 +                </​description>​
 +            </​en>​
 +            <​de>​
 +                <​name>​Deutz Agrotron X720 Sample Mod</​name>​
 +                <​description>​
 +<​![CDATA[Dies ist der Beispielmod.]]>​
 +                </​description>​
 +            </​de>​
 +            <​rotation>​0</​rotation>​
 +            <image active="​store_deutzAgrotronX720.png"​ brand="​brand_deutz.png"/>​
 +            <​price>​9995</​price>​
 + <​dailyUpkeep>​95</​dailyUpkeep>​
 +            <​xmlFilename>​deutzAgrotronX720.xml</​xmlFilename>​
 + <​brand>​$l10n_shopItemBrand_deutz</​brand>​
 + <​machineType>​tractors</​machineType>​
 +        </​storeItem>​
 +    </​storeItems>​
 +</​modDesc>​
 +[/code]
 +
 +Now, I will explain what each tag does and how to edit it for yourself. If I don't talk about a specific tags, it's because you don't need to edit it and are best to leave it like that.
 +
 +[color=orange]<​author>​[/​color] - This is where you put the name of the author of the mod, most likely yours. ​
 +
 +[color=orange]<​title>​ [/color]
 +     <en> - You put the english name of your mod between these tags
 +     <de> - You put the deutsch name of your mod between these tags *Not required if <en> has been filled
 +
 +[color=orange]<​description>​[/​color]
 +     <en> - You put the english description of your mod 
 +     <de> - You put the deutsh description of your mod  *Not required if <en> has been filled
 +
 +[color=orange]<​multiplayer supported="​true"/>​[/​color] - This tag is different; it contains an attribute. Attributes are common, they are often used in the X.xml file (where X is the name of the mod), simply change the value between the " ", true in this case. The fact that the word "​true"​ is between the " " suggest that we need to either put a true or a false in there. If you want your mode to be supported in multiplayer,​ put true. If not, put false.
 +
 +[color=blue] Note : If there was a number, like 3 for example, between the " ", it would mean that the XML file expects us to put a number in there, you coudn'​t put "​true"​ or "​false"​ in this case. [/color]
 +
 +[color=green][i] <​storeItem>​ [/​i][/​color]
 +
 +The following tags are dedicated to the shop aspect. The tags above were providing general information,​ but you can't see it ingame. The code that you will write between the tags below will appear in the shop information box. 
 +
 +[color=red] Important : Make sure that you are now working in the section between the <​storeItem>​ tags, don't alter the information that we previously wrote above. [/color]
 +
 +[color=orange]<​name>​[/​color] - This is the name of your mod as it appear ingame. Pay a particular attention to the spelling, since this will directly appear in the game as your write it, unlike the previous <​name>​ tag that we filled, which was for information purpose. ​
 +
 +[color=orange]<​description>​[/​color] - This is the mod description that will appear in game. Put as much information as you want. 
 +
 +[color=orange]<​rotation>​[/​color] - This is the rotation of the mod when it will be bought. If you put a rotation of 90, your mod will be at a 90 degrees angle from the other mods with a rotation of 0. You are best to leave that at 0. 
 +
 +[color=orange]<​image active="​store_deutzAgrotronX720.png"​ brand="​brand_deutz.png"/>​[/​color] - Attributes, we meet again! The text between the active " " is the path to the store image. Considering that your store image should be in the same folder as the modDesc.xml,​ the code should be simply the image name, like in this case.
 +
 +The code between the brand "​tags"​ refers to the brand image, which is just under the store "​main"​ image. Again, it should be in the same folder as the modDesc.xml,​ so just write down the brand image name.
 +
 +[color=orange]<​price>​[/​color] - Obviously, this is the price of the mod :P
 +
 +[color=orange]<​dailyUpKeep>​[/​color] - Specific to FS13, this allows you to determine the daily maintenance cost of your mod
 +
 +[color=orange]<​xmlFilename>​[/​color] - This needs to redirect to your mod X.xml file (where X is the mod name). It doesn'​t matter if we haven'​t created it yet, as long as we keep the same name later on
 +
 +[color=orange]<​brand>​[/​color] - New to FS13, this is where you put the brand of your tractor, machine, implement or whatever. You can use "​$l10n_shopItemBrand_x"​ and replace X with a default brand name, like deutz, amazone, etc.
 +
 +[color=orange]<​machineType>​[/​color] - This is the type of machine that your mod is, you can pick from one of these : 
 +
 +[quote author=Napalm link=topic=122331.msg799925#​msg799925 date=1351173682]
 +tractors, frontLoaders,​ harvesters, potatoHarvesting,​ beetHarvesting,​
 +tippers, cultivators,​ plows, sowingMachines,​ fertilizerSpreaders,​
 +sprayers, manureSpreaders,​ slurryTanks,​ mowers, windrowers, tedders,
 +loaderWagons,​ baling, feeding, weights, misc
 +[/quote]
 +
 +And ... that's it! That's all that you need to fill to make your modDesc. It might seem a bit long, but it's very basic, you only need to take your time and to double-check everything to make sure it's as you want it.
 +
 +
 +[b] 4. Specializations,​ custom scripts and input bindings [/b]
 +
 +The part above was pretty simple, concerning the basic XML in the modDesc for basic mods. Now, let's talk about something that more complex mods need to behave properly.
 +
 +[color=green][i] What is a specialization?​ [/​i][/​color]
 +
 +To keep it simple, a specialization is a feature of your tractor. ESLimiter is a specialization (and a custom script), articulatedAxis is a specialization for tractors like the Case Steiger, and so on. 
 +
 +For a model, you can use the default specializations,​ like steereable, motorized, foldable, fillable, to describe the basic features of your mod. This information won't be seen by the user in game, but it's needed for the game to know what to do with your mod.
 +
 +You can also use custom specializations,​ like ESLimiter, interactiveControl,​ controlPanelAttacher,​ and so on. These specializations are not found in the default game itself, so you need to tell the modDesc where to look for. This can be achieved using a few tags.
 +
 +To add a custom specialization,​ or to call a default one, you need to scroll down in your modDesc.xml file, and 
 +go to the section right before the store items. This means that you will write the following tags before the tags describing the price of the mod, the daily maintenance price, etc.
 +
 +[color=green]1. Adding (or calling) a default specialization[/​color]
 +
 +If you want to add a default specialization to your mod, like steerable, articulatedAxis,​ you simply need to add the following piece of code : 
 +
 +[code]
 +<​vehicleTypes>​
 + <type name="​Name"​ className="​Vehicle"​ filename="​$dataS/​scripts/​vehicles/​Vehicle.lua">​
 + <​specialization name="​steerable"​ />
 + </​type>​
 +</​vehicleTypes>​
 +[/code]
 +
 +Easy enough? First, you need to specify a name for your vehicle type. You can put whatever you want.
 +Now, you need to adjust the className to the class of your mod, in this case it's a tractor, so it will be a vehicle, like it is at the moment.
 +
 +The filename can be left like that, it's referring to the default game files. ​
 +
 +The $ symbol tells us that it is referring to the default game files, in the installation folder. It's accessing the 
 +dataS.gar file, something that you can't access (it's encrypted).
 +
 +Now, you simply need to put the name of the specialization that you want to add, in the name=" " part. 
 +Of course, you can repeat this line as many time as you want, to add the specializations you want.
 +
 +
 +[color=green]2. Adding a custom specialization[/​color]
 +
 +Now, let's go deeper in the subject. If you have a complex mod, there is a lot to bet that you will want to add custom specialization,​ either made by you or someone else. To do this, it's not really harder. You need to do two things.
 +
 +First, you need to tell the modDesc where to look to find your specialization. If you are well organized, you should put your custom specialization in a script folder, like most mods author do. To tell the modDesc where to look, simply add this code : 
 +
 +[code]
 +<​specializations>​
 +       <​specialization name="​interactiveControl"​ className="​InteractiveControl"​ filename="​scripts/​InteractiveControl.lua"​ />
 +</​specializations>​
 +[/code]
 +
 +Previously, we called the specialization using the vehicleTypes tags. This time, we are simply telling the file where to look for the scripts, using the specializations tags.
 +
 +[color=orange]name[/​color] = Name of your specialization
 +[color=orange]className[/​color] = Not sure of what this does, in this case you can leave it like that, same thing as the name
 +[color=orange]filename[/​color] = This is the path to your script. As I said above, you should put your scripts in a scripts folder, this is why the filename starts with scripts/... ;)
 +
 +We are not done yet! We only told the modDesc where to look, we are not actually calling this specialization on our mod. To do this, we need to do what we did above, putting information in the vehicleType tags
 +
 +[code]
 +<​vehicleTypes>​
 + <type name="​Name"​ className="​Vehicle"​ filename="​$dataS/​scripts/​vehicles/​Vehicle.lua">​
 + <​specialization name="​interactiveControl"​ />
 + </​type>​
 +</​vehicleTypes>​
 +[/code]
 +
 +Piece of cake :D
 +We do like we did above, to call a default specialization,​ we simply adjust the name and make sure that we did the previous step, telling the modDesc where to look.
 +
 +This should be easy enough to do, it's simply a matter of putting things at the right place.
 +
 +[color=red] Important notice : I know this is not part of the modDesc, but I'd rather talk about it in here than forget later. If you add custom specializations to a mod (ESlimiter, interactiveControl,​ etc) it is [b] imperative [/b] that you go in the X.xml file (the main XML file of the mod, X being the name of the mod), and delete this line : [/color] [code] ​
 +<​typeDesc>​ $l10n_TypeDesc_X </​typeDesc>​ [/code]
 +[color=red]... where X is the type of your mod, tractor, sprayer, etc . If you don't do this, your mod most likely won't appear in game! [/color]
 +
 +
 +
 +[u][b]Summary:​[/​b][/​u] Since the part above that we just discussed might be a little bit more complex to understand, I decide to summarize it here. Basically, if you are using the default scripts and only them, you don't need to use the <​vehicleType>​ tags. You simply need to fill in the <​specialization>​ part. However, if you are using custom scripts, you need to declare each of the specialization in the <​vehicleType>​ [b] and[/b] add them in the <​specialization>​ part! Finally, if you are using the default scripts and only them, you must use a default vehicle type in the XML file.
 +
 +
 +Now that this is done, let's cover the input bindings! =)
 +
 +[color=green]Input bindings[/​color]
 +
 +If you want to do things right (and I'm sure you do), it's a much better idea to use input bindings to assign specific keys to a certain functions than hardcoding it in your scripts. This will allow the users to modify the key used for your mod, without having to mess with your custom scripts, and breaking the MP.
 +
 +So, what is an input binding? Basically, when doing that, we are binding a certain keyboard input, mouse input or joystick/​steering wheel input to a function of our mod.
 +
 +Let's say you want the spacebar to activate IC - interactive control - you could do it in the script itself, and it would be the same for every user. But, let's say that another mod is using the spacebar key for another function, they will conflict! This is why you use input bindings. ​
 +
 +Alright, let's get into the subject! ​
 +
 +This is the code we need to add to make a custom input bindings ​
 +
 +[code]
 +<​inputBindings>​
 + <input name="​INPUT_example_turnOn"​ category="​VEHICLE"​ key1="​KEY_space"​ key2=""​ button=""​ device="​0"​ mouse=""​ />
 +</​inputBindings>​
 +[/code]
 +
 +It's as simple as that. We need to add this code to the bottom of our modDesc, right before putting the closing </​modDesc>​ tag ;)
 +
 +
 +[color=orange]name[/​color] = That's the name of the function operated by that key, you get it from the lua custom script itself!
 +
 +*from the lua script
 +ex: g_currentMission:​addHelpButtonText( g_i18n:​getText("​[color=red]example_turnOn[/​color]"​),​ InputBinding.[color=red]INPUT_example_turnOn[/​color]);​
 +
 +
 +[color=orange]key1[/​color] = The first key that will operate this function (you usually only fill key1, not key2
 +[color=orange]button[/​color] = That is to use a joystick/​gamepad button instead of a keyboard key
 +[color=orange]device[/​color] = The device number is ... the number of your device! (oh wow) Basically, if you have a joystick and a wheel both plugged in, one of them will be the device 1, the other the device 2. 
 +
 +
 +We need to use the <​l10n>​ feature to put text beside our input bindings in the F1 help box, top-left of the user's screen.
 +
 +[code] ​
 +<​l10n>​
 +        <text name="​INPUT_example_turnOn">​
 +         <​de>​auf</​de>​
 +         <​en>​On</​en>​
 +      </​text>​
 +</​l10n>​
 +[/code]
 +
 +You can put multiple <​text>​ tags between the same <​l10n>​ tags, you only need to open it once and close it once. Now, a bit of explanation.
 +
 +[color=orange]<​text name> [/color] This is the name of your input that you defined in the input bindings, at the bottom of the modDesc. It's also the same input that is written in the lua code, as explained above.
 +
 +*from the modDesc file 
 +ex: <input name="​[color=red]INPUT_example_turnOn[/​color]"​ category="​VEHICLE"​ ... (it was shrinked due to characters restriction
 +
 +
 +[color=orange]<​de>​ <en> <fr> ... [/color] This it the text that will appear in the F1 box, <en> for the english version, <de> for the german version, and so on ;)
 +
 +To summarize, the input that appears in the lua script is the same as the one in the input bindings part name, and the l10n text name. Those three entries should all be the same, as you can see above in red.
 +
 +
 +
 +Alright, that pretty much cover everything you need to know about the modDesc. I didn't cover every aspect with the same depth, if you want more information,​ especially on the specializations,​ I strongly recommend that you have a look at Sandgroper'​s tutorials :  [url=http://​fs-uk.com/​forum/​index.php?​topic=100121.0]http://​fs-uk.com/​forum/​index.php?​topic=100121.0[/​url]
 +
 +It's for FS11, but I'm sure that some information is still accurate and will still apply to the newest version of the game. He also covers better than I do the complex subject of specializations.
 +
 +I sincerely hope that you liked this tutorial! I appreciate any kind of feedback and constructive critism, I'm not the master of XML on this forum, but I did my best at doing something that a lot of people want, at least now you will have a starting point to ingaming your mods, a complete tutorial that covers about everything in the modDesc =)
 +
 +Feel free to correct me if I'm wrong on some parts, it'll be a pleasure to edit it to make it as accurate as possible!
 +
 +Marx
 +
 +Huge thanks to Sandgroper for his help, DOCTORHILTI and seederman for their feedback!
 +
 +
 +----
 +
 +Original Author: ​ Marxtai | Date:  February 15, 2013,
 +        ​
 +[[modding_tutorials|Modding Index]] | [[general_modding|General Modding Tutorials]]