How to share parts with the community

Propose a part to the official library

If you have created the image and xml files for a missing part or set and would like it to be included in the official part library, you can send your part files by mail to Alban or to the BlueBrick Part Manager. After review and eventual modifications, he may push it to the part repository on github. The part will then be available to anyone in the next release of BlueBrick or in the next update of the official part packages.

However, if you want to create a whole bunch of parts, for example specific template parts used by your LUG/LTC, then you should consider creating a part package.

Part Package Name

To create a new part package simply create a new folder inside the parts folder of the BlueBrick install folder. The folder name will become the name of your package and it will appear as a separated tab in the BlueBrick part library. Be carefull to choose a quite specific name to avoid package name collision with other part creators from the community, and please do not use a name of the official packages. Which means, please do not redistribute an official package by adding your parts inside. For example you may want to name your package after the name of your LUG/LTC if you create a package that is supposed to be used by the members of your LUG/LTC when you plan your events together.

At the time of the release of BlueBrick 1.9, the reserved package name list is:

You can place any number of parts inside your package folder, as explained in the Part Library folder section, and together they will form your package, but make sure all your part ids are unique accross the whole library, as explained in the Part Image Format section.

The config folder

Inside your package folder, you should create a sub folder named config all in small letters. This config folder should contains at least one file named About.txt, and can also contains a file named ConnectionTypeList.xml in case you need to create new connection types for the parts of your package. For example if your package is named MyPackage then you should have this folder structure:

parts
  ├─ Baseplate
  ├─ Custom
  ├─ Duplo
  ├─ Logo
  ├─ MyPackage
    ├─ config
    │ ├─ About.txt
    │ └─ ConnectionTypeList.xml
    ├─ part.1.gif
    ├─ part.1.xml
    ├─ ...
  ├─ Road
  ├─ Space
  ├─ Track
  ├─ ...

The About.txt file is a plain text file, that must contain the version number of your package on the first line with the following syntax: "version=X" where X is the actual version number of your package. On the following lines, you can add extra information regarding the package such as the author and the redistribution policy. Those lines will be ignored by BlueBrick but may be useful for the members of the community. For example the content of your About.txt file can be:

version=1.3
Made by Banban.
You are free to redistribute it.

Since BlueBrick version 1.9, you can now add a ConnectionTypeList.xml file inside this config folder, in order to declare any type of connection that you may create for the parts of your package. This way the connection type definitions can be distributed with your parts, together in the same package. See the Connection Type Config File section for more details about the syntax of this file.

At startup, BlueBrick will read all the connection type declared in the ConnectionTypeList.xml located in the config folder of the BlueBrick installation folder, then will parse all the part package config folders and read all the ConnectionTypeList.xml that it can find, to finally merged all the connection types together. This is why the connection name must be unique accross the whole part library. Please do not hesitate to give an explicit and long name to your connections to avoid name conflicts.

How to distribute your package

Once you are happy with your package, you should zip the whole package folder (use the ".zip" extension), keeping the package folder as first level inside the zip. Be careful, the name of the zip file must be the same as the package name followed by the version number separated by a dot. For example, with the package example mentionned earlier, the name of the zip file should be: MyPackage.1.3.zip. This is very important for BlueBrick, when it check if some package should be updated. BlueBrick will only rely on the zip file name to both know the name of the package and its version number. It will then compare with the folder names listed in the "parts" folder, and with the version number declared in the About.txt files to check if there is a difference.

BlueBrick will not open the zip file online to read the About.txt file on the server. This is why it is very important to make sure that the version number in the About.txt file is the same as the version number given to the zip file name. If BlueBrick cannot find the version number in the zip file name (for the package online) or in the About.txt file (for the local package), it will consider the concerned package as having a version number equals to 0. Any version number is greater than zero, which means if your zip file name doesn't contains a version number, BlueBrick will always see the local package as newer than the online package, and if there's no About.txt file in your local package folder, BlueBrick will always see the online package as newer as your installed package.

Once you have created your zip file and made sure that you give it the correct name, you can upload this file somewhere online, and then give the URL to your community. Users of BlueBrick will then be able to download your package through the  File > Download Additional Parts...  feature. See the How to download additional parts or update the Part Library section for more details.

When a more recent version of a package is downloaded and installed by a user, BlueBrick will delete the whole previous package folder before unzipping the new downloaded package. So, make sure to redistribute all the parts previously distributed, or if you want to renamed a part in your package, add an Old Name tag in the xml file of the renamed part.