[EN] Recursive Extras
Before proceeding, be sure to read the Introduction.
The current variation part system of GTA SA is very limited. This function aims to eliminate these limits.
It works on a whole new system (without replacing the current game extras system), providing many advantages.
- Unlimited amount of extra parts (originally is only 6);
- Extras on literally any part of the vehicle, can vary doors, bumpers, wheels etc, including working damage. This allows the creation of different vehicles in the same file;
- Recursive system: When an extra is selected, it will select a child, and so on, creating a "grouping" where an extra will only appear if the other appears;
- You can define how many extras from each grouping will be selected;
- Possibility to add extras also on trains (originally is possible in all vehicles types except trains);
- Can be used in conjunction with the Characteristics para criar variar características de um veículo.
- If the player who download your vehicle mod doesn't have VehFuncs installed, all extras will be visible by default.
- Using extras on bumpers or wheels, when installing a tuning part on bumper or wheel, will delete that extras.
The basic syntax is as follows:
Note that the name "extra" is just an example, it can be anything else.
Before proceeding I want to make it clear that the system is very flexible and convenient, you do not need to use too much memory, even, the names of the functions can be written in any order and as you please. In fact, each node doesn't even need some visible model inside it.
If you want to do wheel variations, you need to read also about Variable Wheels. See an image.
f_extras is a "trigger", that is, a node that represents the starting point; it will always be visible, however, there doesn't have to be any model inside it, it can simply be a dummy (an empty node).
All childs of f_extras will be considered "extras". Note that they can have absolutely any name, don't need to be called "extras" as in the image above.
Read this as "select X childs", for example :2 will select 2 childs; :1 will select 1 child (the default); :0 may select 1, or none.
As said, if you use : by default will select 1 child, but if the parent has only 1 child? So will have 50% of chances to the child be selected. To force that the single child always be selected (100% of chance), use the suffix :1 on parent.
As said, you can use :0 to create a chance to select no child. For example, there's 3 childs and you want to select one of them, but you also want a chance to select none of them, just use :0 on parent.
But probably what you will most use is the :0+ or :1+. To understand, the + at the end is literally "randomize up to maximum quantity", so, if you use :0+, it will select no one, or one, or some, or all childs! As so :1+ will select at least one, or some, or all. In short, the number after : mean "select at least this" and the + mean "...randomly up to the maximum possible".
You can use extras inside damageable parts, as bump_front_dummy, just add normally inside it and include _ok or _dam at end of the extra part name as needed.
Previously it was still necessary to have some bump_front_ok/dam out of the f_extras for the damage to work, no more! You now can put the _ok and _dam parts normally inside the f_extras.
Note that VehFuncs treats the nodes _ok and _dam as normal extra parts, it doesn't make any connections between them, so you will usually organize them as brothers having a parent :2, according to the image above, and below:
It is possible to use the Characteristics along with extras, thus enabling the vehicle to have certain features based on which extras were selected.
In the above example,
- The mod will select randomly the extras
gasorcargo; - If select
gas, will also apply a custom ID driver (190) configured atdrv=190("drv" from "driver") and the paintjob 1 configured atpj=1(from "paintjob"), which would be a gas truck painting; - And what is that
:2? How many child extras will be selected; - In this case, the childs of
gasextra iscylindersandinterior, will select both; -
cylindershave 2 extras which contains variations of cylinders, will be selected and 1 of them will appear; -
Interiorhas 3 extras and is set to select 2 extras (:2), so you will select 2 of 3:magazinesand/orbottlesand/orcrowbar. If selectbottles, there is also a chance to selectcup; - And if
gaswas not selected? Will be selectedcargo; - Selecting
carga, the script will apply a custom driver of ID 160 or 161; - And we have 2 extras:
furnitureandrubble, where ifrubbleis selected, will apply between 7 and 9 dirt level ("drt" from "dirty") (the setting goes from 0 to 9).
If you find it confusing, that's fine, at the bottom of the page there's an easier example, but it's also important that you understand the basics of this.
Read more about Characteristics.
Right, we learned to put extras somewhere in the car, but how to communicate between different parts of the car?
After all, for example, we want a decal to appear on the doors if a ladder appears on the roof (chassis).
In the example above we have f_class that will select unocompany ou unoold. If unocompany is selected, the category will be defined [unocompany].
When you process door extras, you can apply the companydecal[unocompany]. Note that in the example there is a 50% chance that the decal will be applied or not. If you want to force the decal to always appear if the [unocompany] has been selected, in f_extras_ok and f_extras_dam, let f_extras:1_ok and f_extras:1_dam, so will always select, as explained above.
It's possible to create different versions/models of the car inside the same .dff, like this example:
It's also possible to make a selection of several classes instead of just one.
Note that you can use : and + on f_class.
The _reset do what the name says: clear all old classes to select only new ones.
Would you like to control the chances of each class appearing? You can also use [#] in the category name inside f_class:
In this example, the class with normal name will be the most common, while construct will have half the chances of appearing ([50]) compared to normal ([100]).
Note that the number goes from 1 to 100, but using 100 does not mean that it will appear "100% of the time". It is recommended that you use [100] in the most common class and from this choose the other numbers for the less common ones.
If you don't enter a value the mod will consider it as 100.
And in bigger cases, how about subclasses?
The class selection system is similar to the extras, that is, recursive, if one is selected, will process the children, thus selecting several in sequence, as groups.
You can also place characteristics in the name of the class, so the characteristics will be applied soon if this class is chosen.
However, because of the 23-character limit, using the name in front is not always efficient. So you can create a node with a name that starts with ! (It can be just a ! Or any name, what matters is ! at the beginning) to inform that below is not a class, but nodes with characteristics. All of them will be read and processed.
In the example above, if f_class selects class1 and thus class1a, all those childs characteristics of !characteristics will be read.
Important:
- From v1.9 it's supported more than 1 class per node. For example
part[class1][class2]. - The mod process the nodes from top to bottom, so the class selection should stay on top, preferably at the top of the model hierarchy.
- The mod will consider
_as the end of the class name, ie don't use_for the class name, use only one word. After_normally you will use characteristics. - It's necessary that the node has some name instead of only class name (apparently this is a ZModeler bug and it isn't required in 3DS Max). For example
[example]is wrong;part[example]is correct, even so_[example]and1[example]are correct.
And what happens if we have brothers from the same class?
If there are 2 nodes brothers marked with the same class, the operation of choosing the extras will be exactly the same between them. However, if you have set the suffix":" as a number greater than the total of brothers, will first be selected among the brothers from the same class, and then select the nodes that are left over that there's no category (very convenient, no?).
See a last example similar to what we saw before. Inside ZModeler:
It allows such a class to be selected under different conditions, for example, the region (whether it is LS, SF, LV, countryside or desert), specific zone (some specific location on the map, for example Grove Street, Idlewood), weather (for example if it is raining), type of population (for example if it is a beach), time (if it is night or day) etc.
Only works during class selection (f_class).
You can use multiple conditions at the same time.
It will return true if ANY of the conditions are true. If you want it to return if all are true at the same time, prefer to make a "parent" condition to check something, and a child to check another, so use the class name only on the child (so the mod will select the name of the class only if the child is selected, and for it to be selected, before it needs to select the parent, you understand, right?).
Use ? as trigger. so, use some of these conditions:
Condition: c (city). Check whether it is such a city or region.
Values: 0 = Rural area (and off the map); 1 = Los Santos; 2 = San Fierro; 3 = Las Venturas; 4 = Desert.
Examples: ?c0?c4 returns true if you are in the countryside or desert.
Condition: z (zona). Check if it is such a zone on the map.
Values: After z, enter the name of the zone's GXT. You can find it by searching for websites, or in the data/info.zon file. The short name at the end of the line is the name you need.
Examples: ?zGAN returns true if in Ganton (near Grove Street).
Note: Whenever you can, prefer to use c or p as they are a faster for performance.
Condition: p (population/popcycle). Check if it is such a population.
Values: Population type ID number. You can open the file data/popcycle.dat and count the population types from zero, that is, BUSINESS is 0, DESERT is 1, BEACH is 8 etc.
Examples: ?p1?p3 returns true if it is desert (1) or countryside (3). ?p8 returns true if it is a beach. ?p7 returns true if it is a gangland.
Note: Previously it was wrongly documented, there is no "=".
Condition: rain. Check if it is raining, or about to rain (weather ID 8 or 16).
Examples: ?rain, simply.
Condition: h. Check if it is within an hour range.
Values: Use a number for the minimum hour, a dash, and then the maximum hour number.
Examples: ?h6-18 returns true if it is between 6 and 18 hours.
Condition: d. Check driver pedstat (if it's a cop, old, young, gang etc). nd for negative.
Values: Use the pedstat ID number (starting from 0) defined in data/pedstats.dat.
Examples: ?d5 returns true if the driver is Families gang (pedstat GANG2). ?nd1 returns true if is NOT a cop.
Condition: m. Check if it is script controlled vehicle, while you're in some mission. nm for negative.
Examples: ?m, simply. ?nm returns if is NOT script controlled or you are not in a mission.
In the example above:
If it is Los Santos (?c1, from "city 1"), it will add the class ls and always select the child (:1), which will check if the zone is Ganton (?zGAN) or Idlewood (?zIWD), so it will also add the class grovest. Remembering to avoid using it, ?z is a bit slow for performance.
It will also add the sflv class if it is San Fierro (?c2) or Las Venturas (?c3).
And also the class country if it is countryside (?c0) or desert (?c4). So, it will apply the "dirty" feature (_drt=) with intensity between 7 and 9 (that is, it will make the vehicle very dirty).
There is a second f_class, now to check whether or not it is raining: The roof class will be selected if it is raining or about to rain (?rain). If not, select norain, which will always select 1 child (:1) who will only check if the game time is between 7 and 19 (?h7-19). If true, it will select 1 child (:1), and there, finally, will add the class beach if you are in the population (popcycle) number 8 (?p8), which is the beach population.
If you already understood how the selections of extra variations work (explained here on this page), you will already understand the rest.
Uses the extras system. In the cart is a great example of :1+.
Download