Farmsim Forensics: Hints, help texts, and tutorials
In this episode of Farmsim Forensics, we’re going to take a look at the different tools that Giants offers you to help users find their way around your custom map. I rarely come across a map that utilizes any of these, so I decided to write this article to help you to use these tools when you make your own map for Farming Simulator 19.
Hints
There’s three types of assistance that the game offers. First of all, there’s hints that are displayed while a map is loading. Short texts displayed below the map title on the loading screen.
These hints are fully editable. To do this, change thegamePlayHints entry in the map.xml to point to your own gameplay hints xml file, like below:
This gameplayHints.xml should have a structure like this:
The game engine will randomly pick three hints to show during map load.
Ideally, as with all resource texts, you would want to use l10n and provide translations, however, out of the box, this is not possible. The game engine ‘isolates’ all l10n entries in a mod into its own ‘namespace’. However, the GameplayHintManager only looks at the ‘global’ translation entries. Apparently, this system wasn’t really made with user customization in mind (surprise, surprise, Giants…).
The only way out is a script solution, where you, from within the context of your own mod, remove the existing entries and add the new ones manually. A (simplified) implementation for that is listed below. It is heavily inspired by how Realismus Modding solved that in their Seasons mod, and the implementation is almost identical to theirs as a result:
Because this technique lets the basegame load the default hints first before overriding them, for the best result you should specify an empty hints file in your map definition. Now you can use $l10n_myhint_01 tags in your hints xml, with the corresponding l10n entries in your translation file, or l10n section in your modDesc xml.
Help texts
Next up are help texts, these are accessible through the in-game help system in the menu.
All of these contents are fully customizable as well, and it can be very useful to put some information in here that is specific to your map, for example about production, certain locations, shop opening times, and whatever else you can think of.
To do this, there’s again an easy way and a hard way. The easy way is to just point to your own helpLine file in the map xml. Unfortunately, you will lose all of the existing entries and you won’t have the possibility to add translations again. We’ll look at the script solution below, but let’s have a look at the actual helpline xml file structure first.
The reference in the map xml looks like this:
The actual helpline xml file looks like this:
Let’s go over the structure. The file defines one or more categories. These are the main headers in the help screen. In the screenshot above, ‘Farming Basics’ and ‘Advanced Knowledge’ are categories.
Below a category, one or more pages can be defined. These pages have a title, that is shown in the menu on the left, and on top of the page itself on the right of the screen. A page has a collection of items. It’s important to know that a help page can’t scroll, so the contents need to fit on a single screen.
An item can be a text, or an image. A text is simply that, a block of text that’s displayed as is on the page. The only special thing is, that you can use $CURRENCY_SYMBOL in the text, and it will be replaced by the currency symbol specified in the game settings.
Images have a few caveats. First of all, an image is always displayed full width. If you want an image that is not full width, include a transparant area to fake the effect. Also, images are assumed to be 1024 x 1024 pixels. If you use a different size image, make sure to specify the imageSize attribute. The last attribute is imageUVs. This attribute specifies the view area of the image that is shown. It allows you to optimize loading by combining multiple images in a single large image. The xml file above will display the following help page:
Even though there are two separate image items specified, they both point to the same image, but with different view areas, like explained above. To illustrate how that works, this is the image file:
The two different imageUVs correspond to the top and bottom half of the image. Using these categories and pages, with text and image items, you can fill your own help system with all the information you need.
Now, as mentioned above, if you want to add to the existing ones, and add translations for your new entries, you will again have to resort to a script solution. An simplified example script looks like this:
It’s a lot simpler than the hints one (it’s basically a one liner in line 4), because fortunately, the helpLineManager does offer isolated functionality to simply load additional entries from a file, and it will nicely add them to the existing ones.
Tutorials
The third and last system to offer help to the players of your map, is through tutorials, or guided tours. The Ravenport map ships with an example of such a guided tour, that teaches you the basics through a series of assignments. The base game also includes a series of tutorials. Unfortunately, as they are accessed through the main menu, it is not possible to add to those. The guided tour however, is also a tutorial implementation, the only difference is that it’s triggered by starting a new savegame on the Ravenport map on ‘new farmer’ difficulty.
The tutorial system is entirely implemented through scripting, so it does require a decent level of experience with lua in general, and the FS19 scripts. It allows you to load vehicles and other equipment, prepare fields, set hotspots on the map, and define user interactions, displaying help texts and controls to the user, as displayed in this example screenshot:
A tutorial doesn’t necessarily have to be triggered by loading a map. You could also use a trigger somewhere on your map to start a small tutorial, for example is you have a complex production placeable, that requires multiple resources and steps, you could include a questionmark trigger on it, and guide the user through the steps the first time they visit the facility.
I will leave the deep dive into creating an actual tutorial from scratch for another article, or video, but I have included the basics in this article to get your thoughts going on how you can apply these tools to your own map, or placeable mod.
If you have any questions, or topics you would like to see in a future article, feel free to leave a comment.
Enjoy modding, enjoy gaming, and stay tuned for new articles!
