Basic Library Version: 16

Library Design


  1. Introduction
  2. Library Design Principles
    1. 2.1 General Requirements
    2. 2.2 Directory Structure
    3. 2.3 Folder and file names
  3. Library Part Design Principles
    1. 3.1 Parameters
    2. 3.2 2D model
    3. 3.3 3D model
    4. 3.4 User Interface
    5. 3.5 Comments
    6. 3.6 Preview Picture
  4. Extra Requirements for Openings

1. Introduction

This document contains some major principles and some useful tips for the design of GDL libraries. These guidelines shall to help you in creating an ArchiCAD conform, user-friendly library.

2. Library Design Principles

2.1 General Requirements

Libraries released by Graphisoft must:

2.2 Directory Structure

The library content has to be kept in a logical and well-arranged directory structure. New ArchiCAD libraries must follow the structure of previous releases, unless Graphisoft advises changes. In other libraries for other products, the directory system has to meet customer's needs and/or national standards (e.g., CIS).

2.3 Folder and file names

3. Library Part Design Principles

3.1 Parameters

The number of additional parameters in the objects must be reduced to the possible minimum. Users are confused by too many parameters.

Parameters have to be arranged in a logical system in all library parts. If you have more than 5-10 parameters, arrange them with title parameters. See ArchiCAD library parts for reference.

The parametrizing logic must be reflected in the arrangement of the parameters: groups of parameters should be created and the connection between them must be defined clearly (later implemented in the Parameter Script). To accomplish this, links between different parameters must be carefully analyzed.

Automatic reset of parameters (using commands like range, parameters) should be used carefully. Keep in mind that:

Identical functionality has to have the same parameters and parameter names in all objects to allow modifications on multiple selected objects. Graphisoft's standard parameter names are used in the international library objects.

Valid parameter values, ranges and parameter combinations have to be well defined in order to avoid error messages caused by invalid parameters.

Lock (gray out) or hide unusable or fixed parameters. Graying out should be used if the parameter value is important even though it cannot be set; use hiding otherwise. Display the real values of locked parameters.

Please note that objects that have array value parameters don't work with the GDL Object Web Plugin.

If you want to use custom materials in more applications (ArchiCAD, Web Plug-in, GDL Explorer), define a text type parameter for the names of them.

3.2 2D model

Plan symbols have to be typical of the elements and have to be in compliance with national and international drawing standards.

Make plan symbols simple and recognizable for faster plan browsing.

Remember that the 2D model can display in the following contexts:

floor plan
the main goal for 2D model
settings dialog
the model works as a preview (128x128 pixel sized view!)
section / elevation
2D object on a section drawing
detail drawing
the model is a part of a detail drawing
feedback mode on floor plan / section drawing
model must be simplyfied for quick generation

Only the necessary hotspots have to be shown on the symbol. The default hotspot has to be the typical point for placing the element (e.g., the center point of a column).

Make elements' hotspots editable on 2D plan and in 3D view when it is reasonable.

From ArchiCAD 9 on you can add status lines to the 2D model of your objects. Use this option for a good reason only since it slows down the work with the library part in 2D (f.ex. place status line on the axis of the handrail of a stair but don't place status lines on the edge of each step).

Create background fills for all the objects to hide fills and zones under their symbol. Make the background fill type, pen and contour pen adjustable. The user can set transparent fill when it is desired (it may be the default, too).

Plan symbols have to be scale-sensitive whenever possible (typically doors and windows). Custom linetypes, fills and texts can be defined scale sensitive or scale independent. Take this into consideration when making plan symbols.

Avoid placing texts in the binary 2D symbol (especially error messages) in order to make localization easier. Use a 2D script for defining texts in order to make them scale sensitive.

Always check whether the plan symbol covers the 3D model.

3.3 3D model

Make 3D models simple and fast. 3D models should not be more detailed then required. Put a 3D on/off switch in all objects to allow users to eliminate unwanted objects from the 3D view.

Keep in mind that the 3D model is used in 6 main contexts, these may require different look:

Note that closed bodies regenerate faster in 3D than open ones (e.g., a cylinder is faster then an open tube).

3.4 User Interface tabpage

The Interface Script allows you to define your custom parameter-setting window. You can also add graphical and text type elements to help users in setting parameters. Use this function of ArchiCAD to make library elements user friendly.

Note that the available dialog size is 444 x 266 pixels. Don't use many (more than 7-9) tab pages - no one will find the one he needs.

The user interface tab pages should cover only the most important part of the whole parameter set since there's not much space there. This could mean some major dimensions or visualization styles which are hard to understand from the text-based parameter values.

Design a standard tabpage look and stick to it at positioning the dialog items - 'Previous' and 'Next' buttons, separators - for the ease of use.
See an example:

sample dialog page sample dialog page

Since the Custom Settings pages of a GDL object cannot handle transparency in pictures or icons, use white background everywhere.

Please note that if an object has an Interface Script, the GDL Object Web Plug-in will display the UI window as the default parameter-setting dialog.


Since ArchiCAD 7.0 you can refer to a URL address from every object. The address of the referenced web page should be written in the first line of the Comment Window. If there's no web page defined there the default address will be displayed ( This a great possibility to provide online documentation for a library.

3.6 Preview Picture

Add preview pictures to all your library elements (including electrical symbols, macro objects) for smart library browsing.

Picture size has to be 128x128 pixels. Any other size will be displayed distorted in the library browser window. Keep in mind that the preview picture displays in 64x64 size in the object browser. It is reasonable to draw/generate the picture into 64x64 and then resize it to 128x128, so it will look fine in both views.

Previews have to show typical views of the elements, preferably from the same viewpoint and with the same neutral background. This helps to emphasize the characteristics of the objects. Axonometric or perspective images with wall or floor make the elements difficult to recognize.

A folder from ArchiCAD Library

4. Extra Requirements for Openings

Windows and doors are the most visualized libarary parts, their correct display is significant in every architectural drawing. That's why they need extra care in the design phase, too.
Let's list some relevant issues in connection with windows and doors.

2D and 3D representations of doors and windows have to be based on national and international standards (opening line, plan symbol in different scales, nominal opening, etc.).

Wall openings appear in section drawings, define the model clear for that case.

Doors and windows have to work in straight, trapeze and curved walls as well.

The result of rotating, mirroring and flipping must be specified for each window/door part distinctly (leaf/sash, frame, sill/treshold, trim, shutter, etc.).

Scale sensitive behaviour must be defined. At least 2-3 detail levels should be specified conforming the local standards, these may be a scale-independent option, too.

Decide whether to shroud the zone/slab fills under the window sill with a fill.