02. Components of a Library Part

The main element of GDL programming is the library part itself. It defines its own structural classification, 2D symbol and 3D model (both can be adjusted according to environmental context), parametric options, parameter connections, listing values and an interface for user input.

The extension of a library part is .gsm, but it can be converted to a text file with .xml extension using the provided converter.
A library part can be linked to different ARCHICAD tools:

  • Object
  • Lamp
  • Door
  • Window
  • Stair
  • Skylight
  • Zone Stamp
  • Section/Elevation/Story/Detail/worksheet Marker
  • Label

The objects are identified in ARCHICAD by a unique chain of 2*32 characters in hexadecimal system, called GUID. This code is used for identification and migration purposes as well.
The first 32 characters define the object itself (Main ID), while the second sequence means different versions of the same element (Reference ID). If the function changes incompatibly, the Main ID must be changed as well, to create a new entity for the object using the developed new function. The name may stay the same, but ARCHICAD will know the difference.
For more, check out the Basic Technical Standard’s Library part format section.


There are some library parts, which do not contain a whole item, but only a well-defined functionality instead. These library parts are not placeable (notice the available checkbox in the GDL editor’s Details window on top), but can be called as a function from other library parts.
For example: a window object is calling the board macro. The latter handles every aspect of the board-entity: parameter connections, 2D symbol, 3D model, section, etc. The window object does not have to take care of any of it, but “call” the board object, and let it do the job. Multiple window objects can use the same board object, so the coherency of the function can remain within a group of windows.
To read more, check out the Subroutines, macros page of this tutorial.

The best way to check out a library parts other components is to look at it in a GDL editor window:


You can add a short description of your object here. This will be available for the user to read in the object’s settings dialog, under the info sign.


Keywords are used for search function. The most important, most relevant words listed here can help the users find your object faster.

Subtype Hierarchy

The physical entity of the library part is stored in a normal folder/file structure according to the operating system. Grouping objects with similar functions and purpose is a usual way of arranging the components of a library (Office Furniture, for example). However, another structure is available as well, representing a deeper logic of the architectural use, defining ancestors for the object: the subtype hierarchy. Any object automatically inherits all predefined necessary parameters and properties of its chosen subtype, so it can be easily identified as a member of a certain group. This information can be used by a user, ARCHICAD or an Add-on as well, granting certain privileges or providing automated functions (an object in the Door subtype will automatically cut a hole in the wall it’s placed in, and so on).
Usually subtype structure defines family trees:

  • Kingdom: General GDL Object
  • Division: Model Element
  • Class: Furnishing
  • Order: Furniture Layout
  • Family: Table Layout
  • Genus: Office Table Layout
  • Species: Office Table Layout 01.gsm

ARCHICAD has some predefined subtypes, but you can also create your own.


Every object has a list of parameters. The parameter list is the key to the user to customize the object instance.
Parameters can either be coming from the subtype (blue ones in the editor’s list), or being custom parameters added by the programmer (use the Add button on the top of the parameter list in the editor, then rename and position in the list as pleased). The parameters define the object, make it flexible. Every parameter has a default value: the object is displayed according to those settings when first placed in the plan.
The actual parameter values are stored in the placed object instance as well, which can differ from the default settings (user interactions).
A parameter is converted to a variable when used in a script (with the same name and type), can be used and modified in scripts, but without using a certain command (PARAMETERS), the variable can not overwrite the parameter’s stored value.
The actual parameter set is valid, if every chosen value is inside the preset value-list limits, every relation between different parameters are set and defined correctly, and the usage of the parameter correlates with the type of the parameter.

GDL has the usual parameter types:

  • integer
  • real
  • string (text)
  • boolean

The type can be choosen from a popup list:

Most GDL and ARCHICAD specific parameter types fit into one of the above groups:

  • real: length, angle, RGB color components (lights only)
  • integer attribute types: surface, pen, fill, line type, intensity (lights only)
  • custom: title, separator. These are not real parameter types, but make the list more structured.

Length type parameters are handled as meter units converted to real numbers in GDL, but appear to the user according to Work Environment settings.
Angle type is always interpreted as degree.
To set up array type parameters, use the array button in the list:

To manipulate a parameter’s stored value, use the Parameter Script.
"A", "B", and "ZZYZYX" are reserved and always present parameters of any library part: they should store the sizes of the objects.
Negative size is not recommended.

About the name of “ZZYZX”, see here.

Image courtesy of Randall Munroe at xkcd.com

Image courtesy of Randall Munroe at xkcd.com

The script windows show the codes written to perform a certain functionality. Every script type has its own editor window, and every script runs in its corresponding ARCHICAD context.
Read more in the GDL Manual – Scripting chapter.

2D Symbol

Static 2D elements can be placed and modified here. Shapes defined here are non-parametric, so it’s recommended to avoid using them.
See the Binary 2D section of the GDL manual.

Preview Picture

The object’s preview picture can be viewed and modified here. The format should be .png, and the minimum size is 128 x 128 pixels.

2D and 3D views

The 2D and 3D view can be checked here according to the current parameter settings.
In the 3D window, the local and global coordinate system positions can be compared (ideal: the local covers the global, meaning there are no transformations left in the stack).