Element tree

MTA uses a so-called element tree to store all the elements that exist on the server. This is directly related to the XML map file's layout, although it can be changed at run-time by scripts.

If you are familiar with the concept of trees in computer-science, this should be easy to understand. If you are not, think of it like a family tree - except everyone only has a single parent. Every element has a parent element.

All Elements that are created within scripts or from .map files, are child elements of the resource they belong to. Thus, most elements (except for players) exist only within resources and are also destroyed as soon as the resource is stopped.

Tree Elements

When this map is loaded, it is placed within the server's element tree. This tree has a number of "special" elements.

• A root element. This is at the very base of the tree - all elements are children (or grand children etc) of this element.
• Resource elements. These are direct children of the root element - with one for each running resource.
• Map elements. Each resource element contains at least one map element, representing either a ".map" file in the resource or containing the elements created by scripts (this is called the "dynamic" map).

Example

This in an example of a tree of a running server. Please note that it is shortened on some places for the sake of overview.

*  root
         o console
         + resourcebrowser: resource
         + ajax: resource
         + resourcemanager: resource
         + spawnmanager: resource
         + echobot: resource
         + mapmanager: resource
         + playerblips: resource
         + runcode: resource
         - fr: resource
               - dynamic: map
                     # vehicle 
         + player {dontRespawn = false, lastSpawnarea = [object Object]}
         + elementbrowser: resource
         o player {dontRespawn = false}
         - assault: resource
               - dynamic: map
                     # team
                     # team
                     # blip
                     # marker
                     # colshape
                     # blip
                     # blip 
         - as-farm: resource
               o dynamic: map
               - as-farm.map: map
                     - meta
                           * author
                           * version
                           * name
                           * description 
                     - spawngroup {req = , type = attacker}
                           * spawnarea {posY = -8.3976354598999, posX = 20.182683944702, skins = 9, ..} 
                     - spawngroup {req = first, type = attacker}
                           * spawnarea {posY = 32.166355133057, posX = -46.90763092041, skins = 9, ..
                     - spawngroup {req = , type = defender}
                           * spawnarea {posY = 35.214984893799, posX = -33.486911773682, skins = 9, ..} 
                     - spawngroup {req = first, type = defender}
                           * spawnarea {posY = 120.22289276123, posX = -37.031703948975, skins = 9, ..} 
                     * first: objective {type = checkpoint, description = Breach into the farm, id = first, ..}
                     * pickup {posY = 37.083660125732, type = weapon, ..}

Explanation

This tree consists of a number of resources and 2 player elements, that are direct child elements of the 'root' element. All these resources have a 'dynamic map' as child element (it is just not shown for most of them). These contain the elements that are created dynamically by this resource using scripts, for example a vehicle. If the resource has a map file, it is also a child element, itself containing all the elements in the .map file.

Let's have a closer look at the 'assault' resource: This contains just one 'dynamic map' that has 2 teams, 3 blips, 1 marker and 1 colshape as child elements. These are the elements that are created by the script, for example the marker, the colshape and one of the blips are probably used for the objective.

The 'as-farm' resource's function on the contrary is to be a map for the 'assault' gamemode. The dynamic map is empty (it could contain elements if there was a script in it though), while there is a map called 'as-farm.map', that contains a number of elements. These are mostly custom elements (like spawngroup, spawnarea, objective) but also a few elements that MTA creates automactically after loading the map (like pickup). In the brackets after the element type, you can see the element data it contains. These are identical with the attributes the .map file contains within these elements, while you can also set and get element data for any other elements (e.g. players) with setElementData and getElementData.

Pratical Application

Elements can have as many children as they like. This does not directly affect the map in any way, but it comes in to its own when combined with the scripting system.

Setting data for elements

If you call a set... function on a node of the element tree, the function will affect every element within it (that it can work on).

So, the following code would set the size of every marker (the only type of element the setMarkerSize function can work on) that is below the root element to 2.5.

setMarkerSize ( getRootElement(), 2.5 )

The same can be done on any element, it is not restricted to the root element.

Map manager

The example above shows the way the mapmanger uses different resources. The 'assault' resource is the gamemode, that manages what happens on the server using scripts and thus by creating elements in the tree dynamically. When a map resource is started, the gamemode receives the id of the started resource - in this case 'as-farm' - from which you can retrieve the root element of the resource and store it in a variable. Using this element in conjunction with functions like getElementsByType, getElementData and various others, you can access any of the information that was loaded into the tree from the 'as-farm.map'-file through scripts in the gamemode resource.

Another thing that has to be considered related to the tree of elements is the fact that when you change the map, you don't have to remove any elements you created within the map resource, while you do have to remove elements that are created within the gamemode resource, if they are specific to the map (which will be probably the case for those items you create based on information read from the map resource's .map files).