Group XML Description

Overview

Since BlueBrick version 1.7, you can write an XML file that describes several parts or other groups arranged in predefined positions and orientations. Therefore, a group can be also seen as a shortcut to add several parts in one click. For example you can create a standard train module of 3x3 green baseplates with two straight railway lines on the bottom.

A future version of BlueBrick will provide a way to save the current selection as a group, but for now you need to edit the group XML file by hand. A workaround is to save the parts you want to group in a BBM file and then copy/paste the position and orientation code lines into the group XML file.

A group XML file can contain one or several references to other group XML files. However, you cannot create cyclic references, meaning a group XML file cannot make reference to itself, neither makes reference to file that makes reference to a file, etc... that makes reference to itself. BlueBrick detect cyclic references during the loading of the Brick Library and generates an error if one is found.

A group in the Brick Library do not need any associated gif image. BlueBrick recreated the image of the group from the description of the group at loading time to display it in the Brick Library. When adding the group on the map, BlueBrick uses the individual images of each part belonging to the group.

You can duplicate an existing XML file and modify it to work faster. Be careful, the XML tags are case sensitive. Every field except the "SubPartList" is optional, and the order of the fields does not matter. If one field is missing the default behavior is used instead.

Be carefull, in the XML file, the first tag, root of the hierachy, must be "group". This is how BlueBrick makes the difference between a group and a part.

File Encoding

For a good cross platform compatibility, you should clearly indicate in the header of the xml file the encoding in which the file is saved. The prefered encoding is UTF-8, because it can save accentuated character for the part description in different languages. Use a text editor to save your XML file in UTF-8. For example with Windows Notepad, choose the correct encoding in the save dialog:

And make sure the header of your file starts with this line:

<?xml version="1.0" encoding="UTF-8"?>

Structure of the XML file

If you don't know what an XML file is, and if you are not familiar with its syntax, it is strongly recommend to search for some additional help on internet. To summarize it in few words, this format organizes the data in a tree hierarchy by using tags which are identified by being enclosed with the characters < and >. Here is the general structure of an XML group file:

<?xml version="1.0" encoding="UTF-8"?>
<group>
    <Author>...</Author>
    <Description>
        <en>...</en>
        ...
    </Description>
    <SortingKey>...</SortingKey>
    <NotListedInLibrary>...</NotListedInLibrary>
    <OldNameList>
        ...
    </OldNameList>
    <ImageURL>...</ImageURL>
    <CanUngroup>...</CanUngroup>
    <SnapMargin>
        ...
    </SnapMargin>
    <SubPartList>
        <SubPart id="...">
            ...
        </SubPart>
        ...
    </SubPartList>
    <GroupConnectionPreferenceList>
        ...
    </GroupConnectionPreferenceList>
</group>

The different XML tags in details

For a detailed description of each XML tags, read the following sections: