Introduction
The game uses Object Definition Files to identify most Entities in the world.
The game uses Object Definition Files (.odf file extension) to identify all the properties of an Entity in the game. Everything from buildings, ships, weapons, explosions, are all defined by ODFs.
The ODFs can be opened in any text editor. Notepad or Notepad++ are recommended.
The ODFs can be placed anywhere within the game/mod's resource directories.
ODF files are lists of Properties, one property per line. You can have gaps, but each property can only exist on one text line. For example:
Splitting lines like the following example will
NOT
work!
Characters on a line after // or ; are ignored, so use // or ; in front of any comments. Block
Comments /* ... */ are also supported.
There are various types of Properties, with examples below:
Invalid ODF Property lines are ignored, and errant characters on the end of ODF lines may cause unexpected results, so it's best not to make typos, and make proper use of // comments.
The game looks for ODF Properties under specific Class based Headers, surrounded by brackets. For example:
The game will only look for specific ODF properties under the correct [Header] name. If an ODF
property is not specified (or specified under the wrong Header), a default value is used instead.
Most ODF properties have set defaults. This guide will display the default values. ODFs can contain
multiple Headers, but only one of each Header/Property. If there are duplicates, only the last
instance of an ODF Header/Property is read.
There are four main types of ODF files:
Each type of object is a specific Class. An Entity's Class determines what kind of object it is, and thus how it behaves and is used by the game.
The game has many individual Classes, some of which are based on other Classes. For instance: All buildings, persons and vehicles are GameObject Class. A Sabre tank is a Wingman Class, which is based upon HoverCraft Class. And HoverCraft Class is based upon GameObject Class. As such, the Class tree is: GameObject->HoverCraft->Wingman.
Because they are based upon these root classes, all the ODF properties of a GameObject, apply to HoverCraft, and all HoverCraft properties apply to Wingman.
Another example: The ISDF Service Bay is a SupplyDepot, The Class tree is: GameObject->Building>SupplyDepot. This means that all the properties of a Building work on a SupplyDepot.
The game uses specific class label strings to identify the Class that an Entity belongs to. These Classes are exclusive and cannot be combined. These class labels are read by the following ODF properties:
ODFs can also contain Particle Renders. These can be located anywhere in any ODF. They still follow the same Header rules listed above. They are referenced by certain ODF properties as a string listing the filename, separated by a period, and then a Header name.
See ODF Render Documentation Guide for more details.
Bit Masks
To use Windows Calculator to get the numeric value of the binary setting you want, open the Calculator, and set mode to Programmer. Then select the BIN for Binary setting. Here, you type in the values you want, 0 for False, 1 for True. When typing in a Bit Mask, you want to start at the highest bit that is set to 1, and work your way down. The right most number is the first Bit. Once we set the Binary options we want, simply click DEC for Decimal mode to get the numeric value to put in the ODF parameter.
So, for instance, setting the 3rd bit in an 8 bit number would be: 00000100. Since we don't need the leading 0's, it can be shortened to 100. The DEC value for this is 4.
If we want the 7th bit, we put 01000000, The DEC value for this is 64.
If we want the 3rd and 7th bit, we put 01000100, or 1000100 for short. The DEC value for this is 68, which is 64 + 4. BZ2's Bit Masks are usually 16 or 32 bits, and often only use the first few bits. Also some may have 1 bit less, technically, reserved.
ODF Inheritance
So, if you have say, ivtank.odf, ivtankA.odf, ivtankB.odf, and ivtankC.odf, you could have ivtankA, ivtankB and ivtankC inherit off of ivtank. That way, if you wanted to adjust the maxHealth of the tank, you only have to modify the value once in ivtank.odf, and ivtank A, B, and C would all also use the new value. It is recommended that you use ODF Inheritance when making variations on Stock ODFs, so that if they are updated in a Patch, your mod(s) will be updated as well. It is also recommended if you are making a Mod that requires someone else's Mod as an Asset Package and make variants of ODFs included in that mod. That way, if they fix bugs or update their ODFs, you would also get the benefit of those updates without having to do anything.
It is possible to inherit an ODF from another inherited ODF, but it is not
recommended. Also note that some ODF Properties do not support ODF Inheritance. This guide
will note which properties are not inherited.
What is an Object Definition File?
The game uses Object Definition Files (.odf file extension) to identify all the properties of an Entity in the game. Everything from buildings, ships, weapons, explosions, are all defined by ODFs.
How do I edit an Object Definition File?
The ODFs can be opened in any text editor. Notepad or Notepad++ are recommended.
Where do Object Definition File(s) go?
The ODFs can be placed anywhere within the game/mod's resource directories.
Object Definition File Format
ODF files are lists of Properties, one property per line. You can have gaps, but each property can only exist on one text line. For example:
unitName = "Tank"unitName =
"Tank"There are various types of Properties, with examples below:
-
Integer/Long = 0
-
Float/Double = 0.0
-
Boolean = true // Anything starting with an 'F', 'N', or '0', is false, everything else is
true.
-
Character = "A" // String can be longer but only the first character is used.
-
String = "Tank"
-
Color = "255 255 255 255" // Red Green Blue Alpha
-
Vector = "0.0 0.0 0.0" // X Y Z
- HexInteger = 0xFF // or without the 0x part.
Invalid ODF Property lines are ignored, and errant characters on the end of ODF lines may cause unexpected results, so it's best not to make typos, and make proper use of // comments.
The game looks for ODF Properties under specific Class based Headers, surrounded by brackets. For example:
[GameObjectClass]
classlabel = "wingman"Basic info about Object Definition Files
There are four main types of ODF files:
-
GameObject
-
Weapon
-
Ordnance
- Explosion
Each type of object is a specific Class. An Entity's Class determines what kind of object it is, and thus how it behaves and is used by the game.
The game has many individual Classes, some of which are based on other Classes. For instance: All buildings, persons and vehicles are GameObject Class. A Sabre tank is a Wingman Class, which is based upon HoverCraft Class. And HoverCraft Class is based upon GameObject Class. As such, the Class tree is: GameObject->HoverCraft->Wingman.
Because they are based upon these root classes, all the ODF properties of a GameObject, apply to HoverCraft, and all HoverCraft properties apply to Wingman.
Another example: The ISDF Service Bay is a SupplyDepot, The Class tree is: GameObject->Building>SupplyDepot. This means that all the properties of a Building work on a SupplyDepot.
The game uses specific class label strings to identify the Class that an Entity belongs to. These Classes are exclusive and cannot be combined. These class labels are read by the following ODF properties:
[GameObjectClass]
classlabel = ""[WeaponClass]
classlabel = ""[OrdnanceClass]
classlabel = ""[ExplosionClass]
classlabel = ""ODFs can also contain Particle Renders. These can be located anywhere in any ODF. They still follow the same Header rules listed above. They are referenced by certain ODF properties as a string listing the filename, separated by a period, and then a Header name.
See ODF Render Documentation Guide for more details.
Advanced Settings
Bit Masks
What is a Bit Mask?
A bit mask is a binary set of numbers, converted into a decimal value. To get values, you can add together the numeric values of the options you want, OR use Windows Calculator.To use Windows Calculator to get the numeric value of the binary setting you want, open the Calculator, and set mode to Programmer. Then select the BIN for Binary setting. Here, you type in the values you want, 0 for False, 1 for True. When typing in a Bit Mask, you want to start at the highest bit that is set to 1, and work your way down. The right most number is the first Bit. Once we set the Binary options we want, simply click DEC for Decimal mode to get the numeric value to put in the ODF parameter.
So, for instance, setting the 3rd bit in an 8 bit number would be: 00000100. Since we don't need the leading 0's, it can be shortened to 100. The DEC value for this is 4.
If we want the 7th bit, we put 01000000, The DEC value for this is 64.
If we want the 3rd and 7th bit, we put 01000100, or 1000100 for short. The DEC value for this is 68, which is 64 + 4. BZ2's Bit Masks are usually 16 or 32 bits, and often only use the first few bits. Also some may have 1 bit less, technically, reserved.
ODF Inheritance
What is ODF Inheritance?
ODF Inheritance is a method of making an Object Definition File that inherits most of the properties of another ODF, allowing you to only specify the settings you want different. ODF Inheritance has many useful applications in modding. It allows multiple variations of objects to exist, and be maintained easily. If you want to change something in the object, you can simply modify the root level ODF, and don't need to update all the variations that use ODF Inheritance.So, if you have say, ivtank.odf, ivtankA.odf, ivtankB.odf, and ivtankC.odf, you could have ivtankA, ivtankB and ivtankC inherit off of ivtank. That way, if you wanted to adjust the maxHealth of the tank, you only have to modify the value once in ivtank.odf, and ivtank A, B, and C would all also use the new value. It is recommended that you use ODF Inheritance when making variations on Stock ODFs, so that if they are updated in a Patch, your mod(s) will be updated as well. It is also recommended if you are making a Mod that requires someone else's Mod as an Asset Package and make variants of ODFs included in that mod. That way, if they fix bugs or update their ODFs, you would also get the benefit of those updates without having to do anything.
How to implement ODF Inheritance:
ODF Inheritance is defined by setting the classlabel string to the file name of the ODF you want to inherit from. So, for the instance above, you would make ivtankA.odf have classlabel = "ivtank". You could then delete all the ODF properties that are the same as ivtank.odf's properties. It is recommended that you keep the Headers for ease of use/adding additional lines to the correct section. So, here is what your ivtankA.odf might look like:[GameObjectClass]
classLabel = "ivtank"
[CraftClass]
[HoverCraftClass]