Describe the Connection Points

Syntax: <ConnexionList>
    <connexion>
        <type>...</type>
        <position>
            <x>...</x>
            <y>...</y>
        </position>
        <angle>...</angle>
        <angleToPrev>...</angleToPrev>
        <angleToNext>...</angleToNext>
        <nextConnexionPreference>...</nextConnexionPreference>
        <electricPlug>...</electricPlug>
    </connexion>
    ...
</ConnexionList>
Default Value: By default there is no connection at all.
Description: A list of connection point. There is no limit to the list and each connection point has several parameters to tune.

The type field is string id representing the type of the connection. In BlueBrick only connections of the same type can connect to each other. The available types and the color used to represent them in BlueBrick are defined in an XML configuration file named "ConnectionTypeList.xml" and located in the "config" folder of the BlueBrick install folder. Read the "Connection Type" configuration file section for more details.

The position field is the coordinate of the connection in stud units, relative to the center of the part. First you have to determine the distance of your connector to the center of your part, in studs. In the example below the distance is 8 studs to all sides. You don't need to specify the center of the part because BlueBrick does this automatically. When BlueBrick rotates the parts, it is a lot more simple and efficient to rotate it at its center. This is why BlueBrick uses this system to make the coordinates for the connection points:

Note that the Y axis is oriented downward (positive value toward the bottom). Usually it is easy to find the center of your part based on the LEGO© geometry of the part. For example for the 9V track crossing above, it is obvious to see that the 4 connection points are at 8 studs from the center. But if you have a complex part such as the 9V rail point below, you can find the center of the part based on the part picture itself. And then, from this center you can compute the positions of the connection points.


To compute the center of the 9V switch point, we can start from the size of the image 279x166 pixels then divide by the scale (1 stud = 8 pixels), then divide by 2 to get the middle:
centerX = 279 pixels / 8 pixel per stud / 2 = 17.4375 studs
centerY = 166 pixels / 8 pixel per stud / 2 = 10.375 studs

These two values are the distance in stud between the border and the center. From now, you know that the left connection point, is 0.5 stud far from the left border and 4 stud far from the bottom border, so finally the coordinate of the left connection point is:
leftX = 0.5 - centerX = 0.5 - 17.4375 = -16.9375
leftY = centerY - 4 = 10.375 - 4 = 6.375

This is the same to compute the right bottom connection point:
rightBottomX = 32.5 - centerX = 15.0625
rightBottomY = leftY = 6.375

For curve track similar reasonning could be done, but some trigonometric function is usually needed, by taking into consideration the rotation angle of the curve and the radius of the curve. For example a 9V rail curve has a radius of 40 studs (that means if you construct a circle with 9V tracks, the distance between the center of the circle and the middle of the track will be 40 studs).

So to compute the top right connection point, imagine that you add another counter curve, then you reach a point which you know the position exactly, it is (16, -16) away from the right bottom connection point:
counterCurveEndX = rightBottomX + 16 = 15.0625 + 16 = 31.0625
counterCurveEndY = rightBottomY - 16 = 6.375 - 16 = -9.625

And finally the right top connection point is at:
rightTopX = counterCurveEndX - radius * sin(curveAngle) = 31.0625 - 40 * sin(22.5°) = 15.7552
rightTopY = counterCurveEndY + radius * (1 - cos(curveAngle)) = -9.625 + 40 * (1 - cos(22.5°)) = -6.58018

The computation of the position is the most difficult thing when your part does not have a simple geometry, but most of the time it stays quite simple. The next parameter is the angle field. This describe the orientation in degrees of the connection point compare to the direction of the right border. Be careful, since the Y Axis is inverted in the part coordinate system, the sign of the angle is inverted compared to the trigonometric direction.

The Angle to Previous field and Angle to Next field are quite similar to the previous parameter. It indicates the difference in degrees between this connection point and the previous or next one in the list. The previous point of the first point is the last point and the next point of the last point is the first point, such as you obtain a circular list. So be careful if you reorganize the order of the connection point you will have to reset these two parameter.

The order of the connection points is used by BlueBrick when you rotate a part that is connected to another. BlueBrick rotates the part in such a way to connect it to the next connection point in the list. Of course, if one part has a different type of connection point (such as a rail crossing in which you have road and rail connection point), you have a different circular list. There is one list per connection type.

The Next connection preference field is a 0-based index pointing to a connection inside the list. This parameter tells BlueBrick witch connection point should be selected automatically after the user has placed the part and connected it. If you take the straight 9V track as an example, when the user connects this track by its left connection point, you want to have the right connection point selected automatically so that you can add subsequent pieces very easily. The same applies if you connect this part with the right connection point, as then you want to have the left one selected automatically.

Normally a connection should not refer to itself as the preference for the next selected connection point (unless there is only one connection point in this part), else you will see the parts stack to each other in BlueBrick. If you take the example of a 9V switch point, you can see that if you connect this part from the left connecion point, the bottom right will then be selected and if you connect it from any right connection point, the left one will be selected.

<ConnexionList>
┌─► <connexion>
 ┌─── <nextConnexionPreference>1</nextConnexionPreference>
  </connexion>
 └►<connexion>
├──── <nextConnexionPreference>0</nextConnexionPreference>
    </connexion>
    <connexion>
└──── <nextConnexionPreference>0</nextConnexionPreference>
      </connexion>
</ConnexionList>

Finally the Electric Plug field is used for track with electric circuits (9V and 12V) so you can omit this field for most parts. The field contains an integer that can be positive or negative. Different values indicates different independant circuits which are not connected electrically on the part. For example if you take the rail-cross part 32087, or a level crossing with two parallel railways, one line will be identified with the numbers +1/-1, and the other line with the numbers +2/-2.

The connections with the positive values are electricaly connected to the connections with the same negative values. That means a connection with an electric plug +1 is connected to all the connections with an electric plug -1 and vice and versa. But of cource +1 is not connected to -2, neither to another +1. See the image below for some example: