Class Inheritance
Inheriting classes within the config is a concept that can easily go wrong. The purpose of this document is to clarify the cause of some common errors and contains instructions on how to resolve these mistakes.
Terms
- A config refers to a config.cpp or config.bin file that is loaded during the game start. It does not refer to a Model Config.
- The bin\config.bin is the father of all other configs. It forms the first state of the master config.bin and consists of the base game's root classes.
- The master config is built from the merging of all configs to the bin\config.bin, and it is what is seen through the Splendid Config Viewer. This includes both the base game addons as well as user-made addons.
- Child configs are the configs that are merged into the master config.bin during game load. The order in which they are added is defined by the requiredAddons array within each CfgPatches (see addon loading order).
- CfgPatches is a necessary prerequisite for all child configs so that its addon name and required addons (if any) are known.
- Missions and campaigns are not configs, as the pbo they are in may or may not contain a config. This makes them mission pbos or mission addons respectively.
Basic Config Concepts
The config is a hierarchical structure based on classes that provide almost all information necessary for the game. Objects, their behavior, user interface elements, and even which functions to run on game start are defined through the config.
Classes can contain either child classes (see below) or properties. Properties work similarly to script variables, they have a name and are assigned a value. However, unlike script variables, properties can only have number values, string values, or (one or multidimensional) arrays that are made up of number or string values.
Parent and Child Classes
Due to the hierarchical nature of the config, classes can have parent, child and sibling classes.
class Isaac
{
class Esau
{
gender = "male";
firstborn = 1;
// ...
};
class Jacob
{
gender = "male";
firstborn = 0;
// ...
};
};
In this example, the classes "Esau" and "Jacob" are child classes of "Isaac". This makes them sibling classes.
In a more practical example, "arifle_MX_F" and "arifle_Katiba_F" are both child classes of CfgWeapons, and as a result, they too are sibling classes.
class CfgWeapons
{
class arifle_MX_F
{
// ...
};
class arifle_Katiba_F
{
// ...
};
};
Basic Inheritance
A class can inherit properties from sibling classes by defining it as a base class. All properties of the inherited base class will also exist within your class and, unless you overwrite them, they will have the same values as the base class. This is extremely useful for quickly writing sibling classes that share properties, or to build a class on top of another class that has the same properties with only minor value changes.
Taking the example from above we can create a common "ChildMaleBase" base class.
class Isaac
{
class ChildMaleBase
{
gender = "male";
};
class Esau: ChildMaleBase
{
firstborn = 1;
// ...
};
class Jacob: ChildMaleBase
{
firstborn = 0;
// ...
};
};
In this example, both "Esau" and "Jacob" will inherit the gender property from "ChildMaleBase".
Alternatively, we can use "Esau" as a base class for "Jacob" and overwrite the "firstborn" property:
class Isaac
{
class Esau
{
gender = "Male";
firstborn = 1;
// ...
};
class Jacob: Esau
{
firstborn = 0;
// ...
};
class Mary: Esau
{
gender = "Female";
// ...
};
};
In the above example, while "Mary" overwrites the gender property, the class would still inherit the firstborn value of 1 from sibling class "Esau".
Either method is stored, as written, in the master config, and either one achieves the same result for any other classes that access "Isaac".
External Base Classes
External base classes are essentially base classes that are first defined outside of your config, either by the base game or another addon. It's a simple concept to understand but not so simple to implement correctly.
When using an external base class the first thing you have to do is declare it in what is termed a "template" or "skeleton". These do NOT affect those classes, they merely tell the compiler how they are constructed. If the classes you declare are not yet discovered by the engine, it will build empty classes waiting to be filled later, based on what inheritance you've written. As a result, it is important to get the inheritance (if any) right!
class externalBaseClass; // Declare an external base class "skeleton"
class myClass: externalBaseClass // Define that your class inherits from it
{
// ... // Start using it
};
An example of both inheritance and the use of external base classes could be the addition of new weapon textures via "hiddenSelections".
class CfgWeapons
{
class arifle_MX_F; // Declare an external base class "skeleton"
class arifle_MX_Black_F: arifle_MX_F // Define that your class inherits from the external base class
{
hiddenSelections[] = {"camo1", "camo2"};
hiddenSelectionsTextures[] = {"\A3\Weapons_F_EPB\Rifles\MX_Black\Data\XMX_Base_Black_co.paa","\A3\Weapons_F_EPB\Rifles\MX_Black\Data\XMX_short_Black_co.paa"};
// ...
};
class arifle_MX_khk_F: arifle_MX_Black_F
{
hiddenSelectionsTextures[] = {"\A3\Weapons_F_Exp\Rifles\MX\Data\XMX_Base_khk_co.paa","\A3\Weapons_F_Exp\Rifles\MX\Data\XMX_Short_khk_co.paa"};
// ...
};
};
"CfgWeapons" serves as the parent class, while "arifle_MX_F", "arifle_MX_Black_F", and "arifle_MX_khk_F" serve as sibling classes. In this instance, the "arifle_MX_Black_F" is inheriting all of its values from the "arifle_MX_F" external base class skeleton, but it changes the value for the "hiddenSelections" and "hiddenSelectionsTextures" arrays. When defining "arifle_MX_khk_F" later, instead of changing the "hiddenSelections" array value again, it inherits the changed value from its sibling class, "arifle_MX_Black_F", and changes the necessary values in the "hiddenSelectionsTextures" array for the new textures to appear.
It is not necessary to declare the base class' inheritance tree (if any) if you have the correct inherited class' addon in the "requiredAddons" array.
External Base Child Classes
In the event that you want to access a child class of a base class, you must declare the child class as a part of the base class. In order to open the base class, however, you must declare what it inherits from as well. Opening the base class to declare the child class without defining what the base class inherits from will declare the base class as if it is the first time it is being defined.
class externalRootClass; // Declare an external base class "skeleton"
class externalBaseClass: externalRootClass // Define that the external parent base class inherits from the external base class
{
class externalChildClass; // Define the external child base class "skeleton"
};
class myClass: externalBaseClass // Define that your class inherits from the external parent base class
{
class myChildClass: externalChildClass // Define that your child class inherits from the external child base class
{
// ... add or make changes
};
// ...
};
Implied Child Classes
Once an external child class is defined somewhere in the inheritance tree, you will not need to redefine it later, as it is implied by the game engine that that child class is the class you are looking for.
class A
{
class B
{
// Whatever
};
};
class C: A
{
class D
{
// Whatever
};
};
class E: C
{
class D: D // Fairly standard
{
// Change things
};
class B: B // Fairly strange!
{
// Change things
};
};
The reason why you can access, and use, "B" (which is not a direct child of "E") is due to inheritance. "B" does indeed become a child of "E"!
Note that "A", "B", "C", and "D" could be more simply shown as a skeleton tree defined as follows:
class A
{
class B;
};
class C: A
{
class D;
};
Addon Loading Order
When you are using external base classes it is extremely important to define what addons your addon depends on, or in other words, which external base classes need to be already loaded when your config gets loaded.
Defining which addons are required by your config is easily done through the "CfgPatches" class:
class CfgPatches
{
class MyAddon
{
// ...
requiredAddons[] = {"ExternalAddonA", "ExternalAddonB", ...};
// ...
};
};
Defining the required addons ensures that whatever changes you made, or whatever classes you defined based on external classes, are defined on top of the external addons' config. Without defining the required addons and load order, there is no guarantee that your config gets applied correctly.
Empty
The class Empty{}; syntax can be easily misunderstood for defining an external base class. Using the empty syntax removes everything inside of the class (including embedded classes within the scope of the parent class it is found in, defining it as if it was being defined for the very first time. It cannot be used for any class that has inheritance, because that is simply seen as a skeleton tree.
class MyAddon; // Defines a skeleton class
class MyAddon{}; // Removes everything inside the class
Delete
Within configs, the delete Classname; keyword is available. It can be used to delete already existing classes.
class Intel
{
class AttributeCategories
{
class Date
{
class Attributes
{
delete Fog; // removes Fog attribute from Eden Editor
};
};
};
};
class Intel
{
class Attributes
{
class Fog;
class TimeMultiplier: Fog
{
displayName = "Time Multiplier";
tooltip = "Set the time multiplier";
// ...
};
delete Fog; // Will not work since a child of Fog still exists.
};
};