Map files

 Map files

Table of contents:

• Introduction
• How to read a map file?
• Broken map file, what to do?
• Editor bugged, what to do?
• Modify your maps outside of MTA
• Extra links

Introduction

A map-file! What is that? The name already gives away the definition. It is a file which contains a MTA map. The format makes maps portable, so that you can send them over to your friends. You can recognize map-files by the extension: .map

Here is an example of a map:

<map>
    <object id="object (bevgrnd03b_law) (1)" interior="0" collisions="true" alpha="255" doublesided="false" model="6094" scale="1" dimension="0" posX="635.234375" posY="-3827.2275390625" posZ="5" rotX="0" rotY="0" rotZ="0"></object>
    <object id="object (gaz9_law) (1)" interior="0" collisions="true" alpha="255" doublesided="false" model="6133" scale="1" dimension="0" posX="625.49114990234" posY="-3771.6955566406" posZ="11.479743003845" rotX="0" rotY="0" rotZ="0"></object>
    <object id="object (CE_grndPALCST03) (1)" interior="0" collisions="true" alpha="255" doublesided="false" model="13120" scale="1" dimension="0" posX="573.09802246094" posY="-3847.013671875" posZ="3.6442375183105" rotX="0" rotY="22" rotZ="352"></object>
    <object id="object (CE_grndPALCST03) (2)" interior="0" collisions="true" alpha="255" doublesided="false" model="13120" scale="1" dimension="0" posX="572.64624023438" posY="-3769.0698242188" posZ="4.9519920349121" rotX="0" rotY="21.99462890625" rotZ="343.24649047852"></object>
    <object id="object (CE_grndPALCST03) (3)" interior="0" collisions="true" alpha="255" doublesided="false" model="13120" scale="1" dimension="0" posX="669.66534423828" posY="-3856.0627441406" posZ="3.6442375183105" rotX="0" rotY="63.99462890625" rotZ="175.99389648438"></object>
</map>

Syntax highlight

When you open a map file in your text editor. The syntax highlight you should use is XML (HTML will work as well, but the semantic is different and could cause issues with auto complete features, that is if you have enabled those).

Changing syntax highlight in for example Visual Studio Code.

How to read a map file?

Before we start, this is what we call a node:

<tagName></tagName>

If we take a closer look to the following map file:

<map>
    <object id="object (bevgrnd03b_law) (1)" interior="0" collisions="true" alpha="255" doublesided="false" model="6094" scale="1" dimension="0" posX="635.234375" posY="-3827.2275390625" posZ="5" rotX="0" rotY="0" rotZ="0"></object>
    <object id="object (gaz9_law) (1)" interior="0" collisions="true" alpha="255" doublesided="false" model="6133" scale="1" dimension="0" posX="625.49114990234" posY="-3771.6955566406" posZ="11.479743003845" rotX="0" rotY="0" rotZ="0"></object>
    <object id="object (CE_grndPALCST03) (1)" interior="0" collisions="true" alpha="255" doublesided="false" model="13120" scale="1" dimension="0" posX="573.09802246094" posY="-3847.013671875" posZ="3.6442375183105" rotX="0" rotY="22" rotZ="352"></object>
    <object id="object (CE_grndPALCST03) (2)" interior="0" collisions="true" alpha="255" doublesided="false" model="13120" scale="1" dimension="0" posX="572.64624023438" posY="-3769.0698242188" posZ="4.9519920349121" rotX="0" rotY="21.99462890625" rotZ="343.24649047852"></object>
    <object id="object (CE_grndPALCST03) (3)" interior="0" collisions="true" alpha="255" doublesided="false" model="13120" scale="1" dimension="0" posX="669.66534423828" posY="-3856.0627441406" posZ="3.6442375183105" rotX="0" rotY="63.99462890625" rotZ="175.99389648438"></object>
</map>

> we see in there the map node:

<map></map>

When the map is loaded <map></map> will become our map element.

And inside of the map node we see more nodes:

<object id="object (bevgrnd03b_law) (1)" interior="0" collisions="true" alpha="255" doublesided="false" model="6094" scale="1" dimension="0" posX="635.234375" posY="-3827.2275390625" posZ="5" rotX="0" rotY="0" rotZ="0"></object>

<object id="object (gaz9_law) (1)" interior="0" collisions="true" alpha="255" doublesided="false" model="6133" scale="1" dimension="0" posX="625.49114990234" posY="-3771.6955566406" posZ="11.479743003845" rotX="0" rotY="0" rotZ="0"></object>

In this case these two nodes will become two in-game objects.

Tagname

<tagName></tagName>

Each node in the map file will become an element in game. !important

A node has a tag name. In this case I gave it the name: "tagName"

This tag name specifies in MTA the element type.

For example:

• If it has the name <object></object>, the element-type is an object.
• If it has the name <ped></ped>, the element-type is a ped.

What if the tag name is not matching with one of these entities? (The list is not complete, the rest can be found in this class list, only if the XML syntax is implemented) Then the elements are considered custom elements. They are not visible in game.

Custom elements

Custom elements have their own purposes. You often see those custom elements used in game modes, for example stealth:

<mercenaryspawn id="mercenaryspawn (1)" posX="635.58117675781" posY="-3770.458984375" posZ="18.97974395752" rotX="0" rotY="0" rotZ="0"></mercenaryspawn>

The tagname for this node is "mercenaryspawn". The element that is produced after loading the map, is used as a spawnpoint for in a stealth map.

Attributes

Attributes are properties applied to a node. They are used to attach data to an element.

Example:

<entity name="IIYAMA" age="5" type="device" resolutionX="1920" resolutionY="1080" displaySize="31"></entity>

An attribute exist out of two parts:

<entity name="value"></entity>

• Name
• Value

The name specifies if the node has the attribute.

<entity name></entity>
<entity age></entity>

• If the name is "name", then the node has the attribute "name".
• And if the name is "age", then the node has the attribute "age".

The value will be used for the data for each attribute.

<entity name="IIYAMA" age="5"></entity>

Identifiers (ID)

Every elements can have an identifier attribute, which is used to make it accessible for scripting functions.

<tagName id="identifier"></tagName>

Element specific attributes

There are some attributes that do more than just applying properties. They will change the element appearance and orientation.

For example this object:

<object interior="0" collisions="true" alpha="255" doublesided="false" model="6094" scale="1" dimension="0" posX="635.234375" posY="-3827.2275390625" posZ="5" rotX="0" rotY="0" rotZ="0"></object>

• It will be created in interior 0.
• It will have collisions. (You can walk on it)
• Alpha. It's opacity is 100%.
• It is not doublesided. (When you stand inside of the object you can look through it. If doublesided is enabled the same colors/paint from the other side will be applied.)
• It's model is 6094.
• It is scaled 100%. (0.5 = 50%, 2 = 200%)

Etc.

If you want to know which attributes do have influence on the elements appearance and orientation, you have to look that up on the wiki. Here a small list of some those attributes:

<blip posX="" posY="" posZ="" icon="" color="" dimension="" ordering=""/>

<vehicle model="" posX="" posY="" posZ="" rotX="" rotY="" rotZ="" color="" upgrades="" paintjob="" plate="" turretX="" turretY="" health="" sirens="" landingGearDown="" specialState="" locked="" interior="" dimension="" frozen=""/>

<object model="" posX="" posY="" posZ="" rotX="" rotY="" rotZ="" interior="" dimension="" scale="" collisions="" alpha="" frozen="" />

<pickup posX="" posY="" posZ="" type="" amount="" respawn=""/>

<ped model="" posX="" posY="" posZ="" rotZ="" interior="" frozen="" />

Broken map file, what to do?

If your map file is broken.

Step 1

Make a backup.

+ Always make a backup when re-editing your map. Settings can get lost!

Step 2

The first thing you want to do, is just open it in a text-editor. Just give it a quick look and check for anything strange. The file could be empty or some strange values could be used.

Do you want to know all the syntax rules (XML)? You can find a list right here:

http://www.adobepress.com/articles/article.asp?p=1179145

Step 3

Remove the editor definition. This definition could cause problems in case of invalid characters.

From:

<map edf:definitions="COBDEF,editor_main">
 	<!--
	Map elements
	-->
</map>

To:

<map>
 	<!--
	Map elements
	-->
</map>

Step 4

If you can't find the problem, then you could validate the file. There are services out there that validate XML files. They can help you to find out where your file is broken.

Validation tool by W3C: https://validator.w3.org/#validate_by_input

Note: You need to do step 3 first. Else you can't parse the file.

Step 5

In case of re-opening map files in the editor, but doesn't want to get open.

1. Make a backup.
2. Remove custom elements. See chapter How to read?
3. Retry to open the file.

Editor is bugged, what to do?

Your editor could be bugged and you are not able to save the map or open a new one.

The first thing you want to do is backup the editor_dump folder in your server. This folder is located between all your resources.

server\mods\deathmatch\resources\editor_dump

1. Rename the folder name. editor_dump > my_broken_map
2. Stop the map editor.
3. Check if there is a new editor_dump folder. If there is, rename that one as well.
4. Start the map editor again.

Modify your maps outside of MTA

Sometimes you want to modify your maps without going back in to the editor. Your text-editor is in most cases the way to go.

For example you want to move all objects to a new dimension. In Notepad++:

1. Make a backup! (if you are new to this)
2. Select in your file the part you want to replace: dimension="0"
3. Commando: ctrl + H (replacement overlay)
4. Fill in the replace field: dimension="1"
5. Click on: replace ALL.

Moving your map?

There is a nice online tool that can help you with that:

https://mtaclub.eu/converters

Edit your map with the DOM (Document Object Model)

Knowing JavaScript? Your browser inspector can be used to modify your maps at a higher level. (If you so desire)

let myMap = `
<map>
<object></object>
</map>
`;

let oParser = new DOMParser(); // DOM parser
let oDOM = oParser.parseFromString(myMap, "application/xml");

oDOM.getElementsByTagName("object");

Extra links:

• Parent, child and how this is reflected in MTA
  https://wiki.multitheftauto.com/wiki/XML
  https://wiki.multitheftauto.com/wiki/Element_tree
   
• Elementdata <sync_map_element_data />
  https://wiki.multitheftauto.com/wiki/Meta.xml
   
• Load maps (manually + including in meta.xml)
  https://wiki.multitheftauto.com/wiki/Meta.xml
  https://wiki.multitheftauto.com/wiki/LoadMapData
   
• Save maps
  https://wiki.multitheftauto.com/wiki/SaveMapData