====== 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 [[#Elements|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]].

<code>
	Name = "Value"
</code>

====== Valid Identifier Characters ======

Property Names can only contain these characters (Excluding spaces):
<code>
 A-Z a-z 0-9 _!+-.
</code>

Optionally, you can also surround the Name with double quotes to include otherwise illegal characters, such as spaces, colons, and so on.
<code>
	✅ ThisIsAValidIdentifier
	❌ This is NOT a valid identifier
	❌ This:is, ALSO not a valid * identifier
	✅ "This is a valid identifier, now with spaces and commas!"
</code>

You can also escape quotes if needed in the identifier.
<code>
	"This identifier has \"escaped\" double quotes in it!"
</code>

====== Elements ======

The value of a property is defined using an **Element**. There are three major types of element; [[#Value]]s, [[#Chunk]]s, and [[#Array]]s.

===== 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 (''"'').

<code>
	MyValue = "This is MyValue!"
	IllegalValue = This isn't a valid value, as it's missing the double quotes
</code>

===== 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. [[#Array|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.

<code>
	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"
		]
	}
</code>

===== 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. Arrays are defined by using a starting square bracket (''[''), followed by 0 or more values, followed by a closing square bracket ('']'').

Like [[#Chunk|Chunks]], Arrays can be nested, and [[#Chunk|Chunks]] can be also be used as elements in the array.

<code>
	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!"
		]
	]
</code>