This is an old revision of the document!
What is MDF?
MDF stands for Mars Data Format. It's a JSON-esque file format that's used to define almost all user-accessible data for the Mars Engine. They are used for .mdf
files, which are normally used to define objects and data found in the Definitions
directory, but are also used by the .m3d
file format, which is used to define 3D models, and the .map
format, which contains levels for the game.
Properties
A property is any string of characters, called the Name, followed by an =
sign, and then an Element. The Name specifies which property is being set, while the value specifies the data for that property. Names generally aren't arbitrary, as the engine will be expecting specific Names in order for the values to be passed into the engine correctly.
Name must be made out of Valid Identifier Characters.
Name = "Value"
Valid Identifier Characters
Property Names can only contain these characters (Excluding spaces):
A-Z a-z 0-9 _!+-.
Optionally, you can also surround the Name with double quotes to include otherwise illegal characters, such as spaces, colons, and so on.
✅ ThisIsAValidIdentifier ❌ This is NOT a valid identifier ❌ This:is, ALSO not a valid * identifier ✅ "This is a valid identifier, now with spaces and commas!"
You can also escape quotes if needed in the identifier.
"This identifier has \"escaped\" double quotes in it!"
Elements
The value of a property is defined using an Element. There are three major types of element; Values, Chunks, and Arrays.
Value
A Value element is just a string of characters that will be assigned to the property. They must start and end with double quotes (“
).
MyValue = "This is MyValue!" IllegalValue = This isn't a valid value, as it's missing the double quotes
Chunk
A Chunk element is a collection of named Properties, defined by a starting curly brace ({
), 0 or more properties, and a closing curly brace (}
). Chunks can also be nested, as a chunk can be defined as a property in another chunk. Arrays can also be used as properties.
Note that a property name can only be used once per chunk, if there are multiple properties with the same name, only the last property will be used.
MyChunk = { SomeValue = "This is a value in the chunk" DuplicateValue = "This value will be overwritten" DuplicateValue = "This value overwrote the value above" SubChunk = { Value = "This chunk is a child of MyChunk" } ArrayProperty = [ "Just an array of values" ] }
Array
Array elements are very similar to Chunk elements, in that they contain multiple other properties, but the specific difference is that properties in an array don't need to define a name. They can define a name, if required, and duplicate names are also allowed.
Like Chunks, Arrays can be nested, and Chunks can be also be used as elements in the array.
MyArray = { "Value without a name" NamedElement = "This is an element with a name" NamedElement = "This element uses the same name, but does not overwrite the previous element" { Value = "This is an unnamed chunk in an array" } [ "And this is an unnamed array in an array!" ] }