Basic Library Version: 11

GDL Technical Standards 2.0


  1. Introduction
    1. 1.1 About this document
  2. Library part format
    1. 2.1 File extension
    2. 2.2 Identificaton
    3. 2.3 Subtype structure
  3. General scripting issues
    1. 3.1 Numeric types - Precision
    2. 3.2 Trigonometry functions
    3. 3.3 Parameter stack
    4. 3.4 GDL warnings
    5. 3.5 Hotspot IDs
    6. 3.6 Editable hotspots
    7. 3.7 GDL execution contexts
    8. 3.8 Communicating values with ArchiCAD
  4. Script type specific issues
    1. 4.1 Master script
    2. 4.2 2D script
    3. 4.3 3D script
    4. 4.4 Parameter script
    5. 4.5 User Interface script
  5. Macros, Master GDL
    1. 5.1 Writing macros
    2. 5.2 Master GDL
  6. Speed issues
  7. Tools for Library developers
    1. 7.1 Special menu commands
    2. 7.2 Drag and Drop technique
    3. 7.3 LP_XMLConverter tool
    4. 7.4 Status Report palette
  8. Windows-Macitosh compatibility
  9. Localization
  10. Libraries outside of ArchiCAD
  11. Specific Topics - External links
  12. Annexles

1. Introduction

1.1 About this document

The release of new ArchiCAD® national versions and the growing Graphisoft® product line have dramatically increased the demand for GDL objects and object libraries. As a result, many independent or third party GDL programmers have begun developing libraries for Graphisoft.

To keep these libraries compatible, and to guarantee the standard of quality people expect from Graphisoft products, we published these guidelines for professional GDL creators. This book also includes tips and tricks, examples, and descriptions of previously undocumented ArchiCAD features. This edition applies to libraries made with ArchiCAD version 10.

You should use the GDL Manual for studying the GDL language, its commands and their parametrization. This document is trying to help you using that raw set of information in your development work.

2. Library part format

2.1 File extension

From ArchiCAD 8 on, all Library Objects have the same extension, *.gsm.

The following extensions are no longer available in version ArchiCAD 8 and later, which means you cannot save in these formats (opening such files created with older version is still possible):

Deprecated ArchiCAD Library Part filename extensions
Object type File extension
ArchiCAD Object *.esm
ArchiCAD Window *.win, *.esm
ArchiCAD Door *.dor, *.esm
ArchiCAD Lamp *.lmp, *.esm
ArchiCAD Zone *.rsm
ArchiCAD Label *.lsm
ArchiCAD Macro Object *.ism
GDL Script *.gdl
General Properties Script *.gps

All these GDL Library Objects are now saved with the *.gsm extension and they are distinguished by their subtype in ArchiCAD.

The handling of GDL files is a bit special case because of the relation of GDL files (*.gdl) and some of ArchiCAD's legacy features. GDL Script Files are simple text files with the *.gdl extensions. These could be called from any script of any Library Object file and used as macro scripts. However, there is a special use of GDL Script Files: The MASTER_GDL files. ArchiCAD handles any GDL Script File starting with the string "MASTER_GDL...." in their file name in a special way. These files can be used to load attribute definitions, define line types, and materials etc. (see more in the GDL Reference Guide and in Section 5.2 of this document).

2.2 Identificaton


With the growing complexity of object libraries, a method of tracking library parts and their revised versions was developed for ArchiCAD 8. In short, two GUIDs - internally coded 16-byte numbers -, in combination with the object (file) name, identify each object. Usually this composition is visualized as a 77-character long special string. This identifier is called the Library Part ID and it helps ArchiCAD track the iterations of an object, as it is revised or improved.

The identifier

Library Part ID format: {2B0688E1-BE95-4F94-AC6A-DD76D21592D3}-{7728A37F-ABD0-43D6-A07D-B4866CB23905}

The ID consists of two parts, each 36 hexadecimal characters long. The first 36 characters represent the "Main ID" and the last 36 characters represent the "Revision ID".

This means that Main ID identifies a library part in its function and the Revision ID helps in distinguishing the revisions of the object. Let's see this in practice.

Library Part Identification

When placing an object in ArchiCAD it refers the GUID before considering the name. When loading a library, ArchiCAD uses the following hierarchical criteria for matching loaded library parts to objects already placed in the project:

  1. It tries to get an exact mach of both parts of the ID
  2. Failing that, it tries to match the first part of the ID, which is the Main ID
  3. If a match cannot be found for the Main ID, then it tries to match by library part name.

In case of Library Parts coming from versions earlier than ArchiCAD 8, there was no such thing as GUID. So when such a Library Part is encountered in the file, ArchiCAD will fill out its GUID with zeros. It also knows that it does not have to deal with the first 2 steps of the identification procedure and tries to match it by name.

How to know what the exact GUID of a Library Object is

For this you have to get to know with the Subtype Hierarchy dialog window. In this dialog you can see the subtype hierarchy of the currently loaded library in a tree view. The main attributes - name, version, ID, file location, flags indicating if the object is template or placeable - of the selected library part are displayed in the bottom of the window.

This dialog appears in 3 contexts:

Naturally, you can read the ID in the XML format of the library part (location: xpointer (/Symbol/@UNID)). To get this, use the LP_XMLConverter tool (see Section 7.3).


The most important thing of all this is that the Main ID represents a constant functionality to the users of the library. This means that if you publish a new library part with the same Main ID, loading an old plan with the new library ArchiCAD will match the old placed elements with the new object. So the user expects that the same parameters are present and they are doing the same thing - which results no change in the placed elements. If you want to change the name or the function of old parameters, generate a new Main ID avoid ambiguity and unexpected data loss.

Note that this issue effects the localization of libraries, too. If you have string type controlling parameters, the relevant values will differ between national verions. For example: if you are unaware of the problem, loading a German plan file with the Danish sibling library will change the generated elements since some control parameters have meaningless values. There are two solutions. The easy way is to declare that the German and Danish libraries have nothing to do with each other and to change the Main IDs in localization consequently. The second - and more user friendy - solution is to create hidden integer type control parameters. These integer parameters are determinant, the visible string parameters are just an input method for them.

The following example code solves this problem for the topTreadLevel string parameter using the hidden iTopTreadLevel. The additional benefit of this solution is that it suggests integer comparisons for such switches in the actual model scripting.

! Master script DIM strTopTreadLevels[] strTopTreadLevels[1] = `At Floor Level` strTopTreadLevels[2] = `Below Floor Level` ! Parameter script values "topTreadLevel" strTopTreadLevels values "iTopTreadLevel" 1, 2 if GLOB_MODPAR_NAME = "topTreadLevel" then if topTreadLevel = strTopTreadLevels[2] then PARAMETERS iTopTreadLevel = 2 else PARAMETERS iTopTreadLevel = 1 endif else if GLOB_MODPAR_NAME <> "" then PARAMETERS topTreadLevel = strTopTreadLevels[iTopTreadLevel] endif endif ! 2D script if iTopTreadLevel = 2 then ! Below Floor Level ... endif

2.3 Subtype structure

In ArchiCAD 8, the hierarchyical subtype structure of library parts was introduced. It has two simple rules:

  1. Each object has a parent except the root object called General GDL Object, which is contained in ArchiCAD itself.
  2. Each object inherits the parameters of its parent (and the ones of the parent's parent and so on). These parameters cannot be deleted - only hidden if necessary.

These two rules build up a tree hierarchy which can be used for serving many needs and requirements. Let's see some areas covered:

So the subtype system of a library is created by the author of the library and it can use the default subtype hierarchy shipped with ArchiCAD.

The built-in hierarchy tree can be found below. To get this tree in ArchiCAD, unload all libraries in the Library Manager and open the Open Object by Subtype... window.

These built-in types define two logical groups of fix parameters for the descendant library parts. The groups are distinguished by name prefixes.

ac_ prefix
The parameter is used by ArchiCAD for a certain function. This means that ArchiCAD will query it to find out a given bahavior or attribute of the object or ArchiCAD will assign a value to it to inform the object of an external parameter (e.g. a paremeter of an element linked a label object). For some legacy ArchiCAD features the ac_ prefix is omitted (eg. A, B, ZZYZX). Refer Section 3.8 for more information about communication with ArchiCAD.
gs_ prefix
A logically essential parameter for every entity of the subtype. A made up example: by definition every table should have a legHeight parameter. This gives the library developer the benefit, that he won't forget it for a discrete table. Plus it gives the user the benefit to be able to transfer the leg height (and all common parameters!) of a table to an other one in a trivial way when changing library parts in a plan. A real example: every window should have a frame width and a frame thickness, accordingly the Window (Wall) subtype defines a gs_frame_width and a gs_frame_thk parameter for these values.

3. General scripting issues

3.1 Numeric types - Precision

Before ArchiCAD 9 all numeric values were stored internally as floating point values. This meant that integer values were - a little - imprecisely stored. From ArchiCAD 9 integers and hence GDL parameter types that are best described with integers are correctly stored internally as integers.

Parameter types internally stored as an Integer
Integer, Boolean, Material, Line type, Fillpattern, Pencolor, Intensity (Light)
Parameter types internally stored as a Floating-point number
Length, Angle, Real, RGB Color component (Light)

GDL variables still don't require type definition, the type is determined during the interpretation from the value to be loaded into the variable. The output of numeric operators now have a type. You should consult the GDL Manual for this information.

The programmer can safely compare integer types with the equality operator. In fact, from ArchiCAD 9 warnings are now issued, if a programmer tries to directly compare floating point values with integer values using the equality operator. For equality-comparisons of floating-point numbers use a small epsilon value meaning the precision of the comparison. For equality-comparisons of a floating-point number and an integer use the round_int function.

Below some sample methods of testing for equivalence between different numeric types are described:

iDummy = 1 * 2 if iDummy = 2 then ! valid comparison, it is true, these statements will be executed ... endif dDummy = 1.5 + 0.5 if dDummy = 2 then ! you never know if it is true, don't trust such comparisons ... endif dDummy = 1.1 * 2 if dDummy = 2.2 then ! you never know if it is true, don't trust such comparisons ... endif ! EPS = 0.0001 -> in the master script dDummy = 1.1 * 2 if abs (dDummy - 2.2) < EPS then ! valid comparison, it is true, these statements will be executed ... endif dDummy = 1.5 * 2 if round_int (dDummy) = 3 then ! valid comparison, it is true, these statements will be executed ... endif

3.2 Trigonometry functions

While GDL scripting, you may need variuos trigonometry functions. The following functions are directly available from GDL: cos, sin, tan, acs, asn, atn.

All other functions can be easily derived as follows.

Secant Sec(X) = 1 / cos(X)
Cosecant Cosec(X) = 1 / sin(X)
Cotangent Cotan(X) = 1 / tan(X)
Inv. Sine Arcsin(X) = atn(X / Sqr(-X * X + 1))
Inv. Cosine Arccos(X) = atn(-X / sqr(-X * X + 1)) + 2 * atn(1)
Inv. Secant Arcsec(X) = atn(X / sqr(X * X - 1)) + sgn((X) -1) * 2*atn(1)
Inv. Cosecant Arccosec(X) = atn(X / sqr(X*X - 1)) + (sgn(X) - 1) * 2*atn(1)
Inv. Cotangent Arccotan(X) = atn(X) + 2 * atn(1)
Hyp. Sine HSin(X) = (exp(X) - exp(-X)) / 2
Hyp. Cosine HCos(X) = (exp(X) + exp(-X)) / 2
Hyp. Tangent HTan(X) = (exp(X) - exp(-X)) / (exp(X) + exp(-X))
Hyp. Secant HSec(X) = 2 / (exp(X) + exp(-X))
Hyp. Cosecant HCosec(X) = 2 / (exp(X) - exp(-X))
Hyp. Cotangent HCotan(X) = (exp(X) + exp(-X)) / (exp(X) - exp(-X))
Inv. Hyp. Sine HArcsin(X) = log(X + sqr(X * X + 1))
Inv. Hyp. Cosine HArccos(X) = log(X + sqr(X * X - 1))
Inv. Hyp. Tangent HArctan(X) = log((1 + X) / (1 - X)) / 2
Inv. Hyp. Secant HArcsec(X) = log((sqr(-X * X + 1) + 1) / X)
Inv. Hyp. Cosecant HArccosec(X) = log((sgn(X) * sqr(X * X + 1) +1) / X)
Inv. Hyp. Cotangent HArccotan(X) = log((X + 1) / (X - 1)) / 2


Logarithm to base N LogN(X) = log(X) / log(N)

3.3 Parameter stack

Using parameter buffers remember that the buffers of GDL are FIFO buffers. When there's a suspected caller object using the buffer, the following solution guarantees total correctness:

! beginning of the script ! === save the current stack ===[ stackSizeBefore = NSP if stackSizeBefore > 0 then DIM savedStackValues[] savedStackValues[stackSizeBefore] = 0 for i = 1 to stackSizeBefore savedStackValues[i] = get (1) next i endif ! ]=== save the current stack === ! statemtents of the script ... ... ! === restore the saved stack ===[ for i = 1 to stackSizeBefore put savedStackValues[i] next i ! ]=== restore the saved stack === end

Do not redefine global variables in your objects, as it affects all other objects using these variables. If the usage is necessary, restore their values at the end of the script.

3.4 GDL warnings

Note that the line numbers in the GDL warnings refer the script which contains the problem. It may be the generator script of the current model or view (2D / 3D / UI page / parameter change from script) or the master script.

Extra care must be given to the parsing errors. These denote the first line in which the parsing gets impossible but the actual problems may be some lines before.


The interpreter detects the missing statement first at the greyed endif and stops there; though the problem is obviusly around line 4 where an endif is really missing.

Warning! Missing ELSE or ENDIF after IF statement.

if condition1 then if condition2 then ! do something ! do something - BUT WE MISSED AN 'endif' else ! a potentially long code block endif

3.5 Hotspot IDs

Purpose of hotspot identification

In ArchiCAD 6.5 the hotspot identification was introduced to support associative dimensioning in section. Via this feature a dimensioning item can refer any of a GDL object's hotspots. It will become an important issue when the number of hotspots changes between the object's different parametrization states.

Problem of old-school hotspots

If the programmer doesn't specify hotspot IDs - or if he sets them to 0 - ArchiCAD will assign continuously increasing ordinal numbers. This solution is correct for static objects but causes dimensioning problems when some hotspots appear or hide between parameter set-ups. Namely, the IDs will be rearranged so they will change, and the associative dimensioning items - in section - will go astray.

Correct hotspot scripting

For all these reasons you should assign fix IDs to the hotspots in your objects. This can be done by reserving wide intervals for the hotspots of individually controllable features.

Let's take a stair for example. The bounding hotspots may use the [1-100] interval, the handrails may use the [200-299] interval and the risers the [1000- ) one. This guarantees that the dimensioning of the handrails won't be corrupted if the number of risers changes or the even if the bottom connection gets more complex (using more hotspots).

3.6 Editable hotspots

Since ArchiCAD 8 release you can use editable hotspots in your library parts. The feature is described in the GDL Reference Manual except for one possibility.

In some cases you may want to display a different parameter from the edited one. See the example code below:

Editable hotspot example - Shoe / Shoe-rack

We want to have the size of a shoe in meters and in shoe sizes, too. For that we create two parameters and connect them in the parameter script. Naturally, the type of the explaining parameter can be different (e.g. text). We emphasize that the edited parameter is footLength all the way, footSizeEU - the displayed parameter - must be updated via the parameter script.

Parameter list

2D editing

While editing

Parameter script

DIM lengthValues[10] DIM sizeValues[10] for i = 1 to 10 sizeValues[i] = i + 35 lengthValues[i] = (i + 35) * 0.007 next i values "footLength" lengthValues values "footSizeEU" sizeValues if GLOB_MODPAR_NAME = "footLength" then parameters footSizeEU = round_int (footLength / 0.007) else if GLOB_MODPAR_NAME = "footSizeEU" or GLOB_MODPAR_NAME = "" then parameters footLength = footSizeEU * 0.007 endif endif

2D script

rect2 0, 0, footLength * 0.4, footLength ! or a more realistic shoe model hotspot2 0, 0, 1, footLength, 1 + 256, footSizeEU hotspot2 0, footLength, 2, footLength, 2, footSizeEU hotspot2 0, -0.1, 3, footLength, 3

3.7 GDL execution contexts

ArchiCAD let's the GDL object know about the context it is being displayed or used in. The GLOB_CONTEXT global variable is used for this purpose. For the possible values refer the following listing.

1 - library part editor

The model is displayed by the Library Part Editor. This context stands for library part developers for debugging purposes. The 2D and 3D models are not distinguished, this information can be derived from the script type.

2 - floor plan

The model is displayed in the standard 2D floor plan. In a 3D script this means that the model is projected to 2D via the project2D command. This is the main use of an object, this 2D model must be always correct and efficient.

3 - 3D view

The 3D model is displayed in the standard 3D model window or it is the source of photorealistic rendering. This view should omit internal details of the object, since these cannot be seen anyway. This is the second most important use of an object, this 3D model must be always correct and efficient. This target type demands correct outside look.

4 - section/elevation

The 3D model is displayed in a section/elevation window. For this view, the object should generate internal detailes which are unnecessary for every other view type.

5 - settings dialog

The model is displayed in the Object Settings Dialog's preview box. The 2D and 3D models are not distinguished, this information can be derived from the script type. The obejct should provide a fast, rough preview of the model considering the limited size of the preview.

6 - list

The 3D model is used for surface and volume calculation by the listing engine. This context is the proper place to do some model alterations for listing. E.g. you can generate extra bodies to raise the surface to be painted and the amount of required paint.

7 - detail drawing

The model is used in a detailed drawing window. The model can be more detailed than in ohter views consequently. The 2D and 3D models are not distinguished, this information can be derived from the script type.

8 - layout

The model is used in a layout window. The model should show its printing look. The 2D and 3D models are not distinguished, this information can be derived from the script type.

22 - feedback mode from the floor plan

The model is displayed via feedback lines on the 2D floor plan during the hotspot editing of the object. This model is drawn many times in a single second throughout the user interaction. This implies that the model should represent the essential parts of the object only. Note, that texts (generated by text2 command) are not refreshed in feedback mode - since it would slow down the output.

23 - feedback mode from a 3Dview

The 3D model is displayed via feedback lines in the 3D model window during the hotspot editing of the object. This model is drawn many times in a single second throughout the user interaction. This implies that the model should represent the essential and visible parts of the object only.

24 - feedback mode from a section/elevation

The 3D model is displayed via feedback lines in a section/elevation window during the hotspot editing of the object. This model is drawn many times in a single second throughout the user interaction. This implies that the model should represent the essential and visible parts of the object only.

28 - feedback mode from a layout

The model is displayed via feedback lines in a layout window during the hotspot editing of the object. This model is drawn many times in a single second throughout the user interaction. This implies that the model should represent the essential and visible parts of the object only.

43 - generating as an operator from a 3D view

The generated 3D model is used as a parameter for solid (CSG) operations. This can be useful, when the object's space demand is larger than the object itself. E.g. when you substract a stair from a slab, you'd expect that the stair cuts a hole for the walking people, too. To achieve this, in this context the stair should generate a model containing that walking space.

44 - generating as an operator from a section/elevation

The generated 3D model is used as a parameter for solid operations. This can be useful, when the object's space demand is larger than the object itself. E.g. you substract a stair from a slab, you expect that the stair cuts a hole for the walking people, too. To achieve this, in this context the stair should generate a model containing that walking space.

46 - generating as an operator from a list

This context is the section of mode 6 and mode 43.

3.8 Communicating values with ArchiCAD

There are two directions of parameter value flow between ArchiCAD and the library part. The first direction means that the ArchiCAD informs the library part about an attribute of its context (f.ex. the drawing scale of the project or the thickness of the wall a window is placed into). The second direction is when the library part asserts something about itself which instructs ArchiCAD to change the something in the direct context of the object (f.ex. the depth a wall end cuts in the wall).

Information flow from ArchiCAD

There are two channels of information coming from ArchiCAD: global variables and parameters with predefined names.

Global variables

Global variables are filled by ArchiCAD according to the current project settings and to the placement context of the object.

For the complete list of global variables consult the GDL Manual.

Fix named optional parameters

The newer method of ArchiCAD for providing information is the method of optional parameters. If a given library part has a parameter with a name and type matching any optional parameter, ArchiCAD sets its value according to its function.

Refer Section 1 of Appendix A to learn the ArchiCAD defined library part parameters.

Information coming from the library part

ArchiCAD can get values from library parts through optional parameters with predefined name and function. The type of information needed by ArchiCAD mostly depends on the function and context of the object - which is interpreted by its subtype - and is crucial to its usage. Thus parameters of this kind come from built-in ArchiCAD subtypes, which ensures that the necessary parameters are present and that the library developer can spot them in the parameter list.

Consult the fix parameters of built-in subtypes and Section 2 of Appendix A to get a view of the possibilities.

4. Script type specific issues

4.1 Master script

When writing the master script you have to know that it will be evaluated before the run of each script by ArchiCAD. This implies the following things:

4.2 2D script

Execution context

The 2D script is executed when a 2D model is generated:

Mind that most of the architectural design is done in 2D, so usually this model is the most important. This implies requirements of exact look, fast generation time and proper function when editing via hotspots.

General recommendation

2D script is much more customizable than the 2D symbol, prefer this solution. In binary 2D symbol, the curved fills aren't stretched correctly, you don't have to face this problem in 2D scripting, either.

Defining line and fill properties

From ArchiCAD 9 on you have the possibility to choose from several main categories of lines and fills from GDL. Lines and polygon segments can be defined contour, inner or general; fills can be defined cut, cover or drafting. These categories are described in the ArchiCAD user documentation, let's see how we use them in GDL objects.

Setting the correct properties for lines and fills will result that you can eliminate the display-option dependence from your scripts. Formerly, you had to add a condition for drawing of some inner lines according to the set display option. Now you should define an inner line for that purpose and ArchiCAD will display it or not as implied by the display options.

Let's see the extract of the 2D script of a window to summarize the definition cases:

! ===== Sill ===== line_property 0 ! general lines ! the sill is seen from above -> cover fill poly2_b{2} 4, 1 + 2 * (gs_fillSillCover > 0) + 4 + 64, ... ... ! ===== Wall segment / Cavity Closure ===== line_property 1 ! inner lines line2 ... ... line_property 2 ! wall contours line2 ... ... ! wall segment is seen cut -> cut fill poly2_b{2} 4, 2 + 4 + 8 + 16 + 32, ... ! ===== Window Frame ===== line_property 0 ! general lines ! side window frame is seen cut -> cut fill poly2_b{2} 4, 1 + 2 * (gs_fillFrames > 0) + 4 + 32, ... ...

4.3 3D script

Execution context

The 3D script is executed each time a 3D model is generated:

General recommendation

Try to avoid using binary format in order to make objects modifiable.

Use status codes to control the visibility of the objects in hidden line views. Make the contour lines of curved surfaces visible. Hide unnecessary lines when it is possible.

Define editable hotspots instead of fix ones whenever possible.

Don't use del top command to make later modifications easier.

Always restore the global coordinate system at the end of the 3D script and follow it with an end command to make further modifications on the object easier.

Modelling transparent bodies

Use the body -1 command between solid and transparent parts of an object to make correct shadow casting with Internal Rendering Engine (e.g., window sash with grilles).

Examples for transparent bodies
Incorrect Correct

prism_ 10, 0.1, 0, 0, 15, 1, 0, 15, 1, 1, 15, 0, 1, 15, 0, 0, -1, 0.1, 0.1, 15, 0.9, 0.1, 15, 0.9, 0.9, 15, 0.1, 0.9, 15, 0.1, 0.1, -1 material "blueglass" prism_ 5, 0.1, 0.1, 0.1, 15, 0.9, 0.1, 15, 0.9, 0.9, 15, 0.1, 0.9, 15, 0.1, 0.1, -1

prism_ 10, 0.1, 0, 0, 15, 1, 0, 15, 1, 1, 15, 0, 1, 15, 0, 0, -1, 0.1, 0.1, 15, 0.9, 0.1, 15, 0.9, 0.9, 15, 0.1, 0.9, 15, 0.1, 0.1, -1 body -1 material "blueglass" prism_ 5, 0.1, 0.1, 0.1, 15, 0.9, 0.1, 15, 0.9, 0.9, 15, 0.1, 0.9, 15, 0.1, 0.1, -1

the hole casts solid shadow the leaky body casts leaky shadow

Texture mapping

Always check if texture mapping is applied correctly on your objects. If the default ArchiCAD texture mapping process doesn't produce a good result, use the coor command to set the correct method. See the case below for example.

Example code for random and for correctly aligned tiling
Random texture Aligned texture

define texture "owntile" "T.jpg", 1, 1, 128+256, 0 define material "tilemat" 21, 0.7, 0.7, 1, 0.15, 0.95, 0, 0.0, 0, 0, ind (fill, ""), 1, ind (texture, "owntiling") material tilemat block 1, 1, 1

define texture "owntile" "T.jpg", 1, 1, 128+256, 0 define material "tilemat" 21, 0.7, 0.7, 1, 0.15, 0.95, 0, 0.0, 0, 0, ind (fill, ""), 1, ind (texture, "owntiling") material tilemat block 1, 1, 1 base vert 0, 0, 0 vert 1, 0, 0 vert 0, 1, 0 vert 0, 0, 1 coor 2 + 256, -1, -2, -3, -4 body -1

cube with random mapping cube with correctly aligned mapping

In general, separate bodies which require different texture coordinate systems with a body -1 command.

Picture elements

It may be a good idea to replace complicated parts of a model with a single picture. This method can be well used for trees and bushes.

Using an external image referred by its file name, don't omit the file extension.

When you place a picture in a 3D model using the picture command, a polygon will be created using the picture as a face. The material of the polygon affects the result of the rendering. Knowing this you should use a matte surface - the color may be chosen depending on the picture.

define material "pictmat" 2, 1, 1, 1 ! RGB material "pictmat" picture "filename.extension", a, b, mask

The first picture shows a picture on a shiny surface - the undesired side-effect can be observed. In the second picture you can see a texture on a precisely set material - the wanted result.

on glowing surface - light fades the picture to white on matte surface - the result is correct

For transparent images - like the tree above - you should consider a more precise definition of the base material. See the following example.

define material "pictmat" 0, 1, 1, 1, ! RGB 0.5, 0.8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 material "pictmat" picture "filename", a, b, mask

4.4 Parameter script

Execution context

The parameter script is run in the following cases:

The paramter script is NOT run on: drag, rebuild, scale change.
Editing multiple selection may result unintended parameter values.

Note that the parameter script may be run multiple times on a single user interaction. The reason for this is that the parameter script can change the value of parameters and this requires the parameter script to be run again, and so on. Therefore it makes no sense to increase a parameter value by one in the parameter script since you may not be able to predict the cardinality of executions.

General recommendation

When you control parameters in the parameter script, try to follow the order of additional parameters.

You can define relations between parameters using the GLOB_MODPAR_NAME value (containing the name of the last modified parameter). For example you can make a circle object for which both the radius and the diameter can be set (maybe one of them via the parameter list and the other via editable hotspots). Don't use this possibility to define the valid range of parameters - use values command instead.

Define the valid value range for all parameters using the values command.

When resetting the value of a parameter in a certain condition in the Parameter Script using the parameters command, a similar statement must be put into the Master Script. This keeps the object's display correct in cases when the parameter script is not run by the system. E.g.:

! parameter script if bCondition then parameters yy = 1

! master script if bCondition then yy = 1

Font type names

If you want to have a string parameter - named szFont in the sample - for setting the font type for a text, use the following value list definition to get a platform independent sound solution.

DIM fontnames[] request ("FONTNAMES_LIST", "", fontnames) values "szFont" fontnames

4.5 User Interface script

Execution context

The User Interface script's result displays in one context only, the user interface tabpage in the Object Settings dialog window.

The script is run on the initialization of the dialog window and after each user interaction and parameter change.

General recommendation

If you want the user interface script driven tabpage to be visible by default in the object settings dialog, push the 'Set as Default' button in the library part editor.

When styling texts, note that extra small letters cannot get any style but plain. In addition, Outline and Shadow styles have no effect on Windows platform.

Thumbnail control pictures

If you use the ui_infield command to define a thumbnail view field for value lists, be aware of the following. There should be equal sized thumbnails for all parameter values (including empty value). Thumbnails have to be the same size at which they will display otherwise ArchiCAD will distort them. We advise you to use ArchiCAD's figure tool for assembling the thumbnails into one picture file. Keep all pictures used by interface scripts in the Macros folder.

A user interface picture used by only one object should be integrated in the library part file itself. This can be done using the LP_XMLConverter tool (refer Section 7.3).

Using an external image referred by its file name, don't omit the file extension. This way, the system won't be confused by pictures and objects having the same name.

Input picture
raw input bitmap - a table of thumbnails
Output - the control on the UI page
resulting UI page with thumbnail control

Tabpage handling

In ArchiCAD 10, a new dynamic paging technique is introduced. You can simply set the index of the current page to display by the ui_current_page command. Doing so, a cooperation between the classic ui_page definitions and a flexible paramter setting is established. This allows to define a page selector control of any type provided by ui_infield.

If you want to use the Previous and Next buttons, too, you should add a integer parameter to your object, gs_ui_current_page. The execution environment (i.e. ArchiCAD) will set this parameter's value when the classic Previous or Next button is pushed.

Example showing the whole mechanism:

! Parameter script values "gs_ui_current_page" 1, 2, 3, 4

! User Interface script ui_dialog `Custom Settings`, 444, 266 ui_current_page gs_ui_current_page ! ===== Page 1 : General Stair Geometry ===== ! ui_page 1 gosub 1 ! draw the header part of the page ... end ! ======================================================================= ! draw the header part of the page ! ----------------------------------------------------------------------- ! Remark: ! The routine places a page chooser and the Previous and Next buttons ! on the top of the page. ! Other UI items may begin at the Y position of 35. ! ======================================================================= 1: ui_style 2, 1 ui_infield{3} "gs_ui_current_page", 14,3, 210,20, 2, "", 4, 1, 20, 20, 10, 10, "", `General Stair Geometry`, 1, "", `Calculation Methods`, 2, "", `Primary 2D Representation`, 3, "", `2D Representation`, 4 ui_button ui_prev, `<< Previous`, 250, 3, 90, 20 ui_button ui_next, `Next >>`, 350, 3, 90, 20 ui_separator 0, 30, 444, 30 ui_style 2, 0 return

Thumbnail controls with dynamic items

From ArchiCAD 10 on, a new dynamic way of linking of control items and value list items is available. Using this method you can localize the logic of the availability of parameter values to the parameter script - the control will adopt the set of available values. This dynamic linking is done for ui_infield{3} and the old-style static linking is still working for static functions (using ui_infield and ui_infield{2}).

The two components of the dynamic method are:

1. Define the user interface control with an option for every possible value.

The example shows a popup menu control (method = 2) which uses an index image containing 2 rows and 4 columns. The sample control supports 8 possible values.

ui_infield{3} iJunctionType, xColumn1-10, 44, 200, 50, 2, 3, 8, 2, 70, 45, 70, 45, 1, `Junction Type A1`, 2, 2, `Junction Type B1`, 4, 3, `Junction Type C1`, 1, 4, `Junction Type D1`, 3, 5, `Junction Type A2`, 5, 6, `Junction Type B2`, 7, 7, `Junction Type C2`, 6, 8, `Junction Type D2`, 8

2. Set the list of available values for the parameter under the given circumstances.

if iLeftNeighbour = 1 then values "iJunctionType" 1, 3, 4, 6 else if iRightNeighbour = 1 then values "iJunctionType" 2, 5, 7, 8 else values "iJunctionType" 1, 5, 7 endif endif

The resulting control is shown in the image below. (iLeftNeighbour = 0, iRightNeighbour = 1)

ui_infield{3} method 2

Transparent UI pictures

In ArchiCAD 10, alpha-layer based transparent pictures handling on the UI page was introduced. The following controls handle pictures with alpha layers correctly:

  1. ui_pict
  2. ui_infield{3}, method = 1 (thumbnail view control)
  3. ui_infield{3}, method = 2 (popup with icons and texts)
  4. ui_infield{3}, method = 3 (popup with icons only)
  5. ui_infield{3}, method = 4 (icon radio push button)

5. Macros, Master GDL

5.1 Writing macros

Try to collect often used functionalities into macros. Calling a macro object from many objects can reduce library size and increase soundness by reducing redundancy.

However avoid creating macros with small functional addition to the previous abstraction level. For example don't create a block_1x1x1 macro for the generation of a 1m x 1m x 1m block. This increases the levels macro calls needlessly and it may worsen transparency.

Don't ever use .gdl as macros, use macro objects instead.

When you call a macro, always use the call keyword and put the name of the macro between quotation marks (e.g., call "m_rail_wired"). Do not create macro calls where the macro name is a parameter to avoid missing macros from archive files. ArchiCAD saves the default macro only into the archive file. (Workaround: call all parameter values as a macro after the end statement.)

Be careful at using the parameter buffer. Save the content of it at be beginning of the script if you want to use it. Be sure that only the defined (return) values are in the buffer by the end of the script.

Macro return parameters

From ArchiCAD 10 on macros can return parameters to the caller object. At the caller's side, returned values can be collected using the returned_parameters keyword followed by a variable list. The returned values will be stored in these variables in the order they are returned in the called macro. The number and the type of the variables specified in the caller and those returned in the macro must not match. If there are more variables specified in the caller, they will be set to 0 integer. Type compatibility is not checked: the type of the variables specified in the caller will be set to the type of the returned values. If one of the variables in the caller is a dynamic array, all next values will be stored in it.

In the macro object the end and the exit commands define the values that have to be return to the caller object. See the example below.

Advanced parameters all

From ArchiCAD 10 on after parameters all keyword you can specify extra parameters to pass it to the macro. They will override the values coming from the caller or parameters of the called macro left to be default. The macro can return parameters in this case also. See the illustrative picture.

Faster macro call

Speed of parameter value transfering between the caller object and the macro was improved in ArchiCAD 10. Find out tips about utilization of marco call's speed enhancments in the Speed issues topic.

Macro call example

Script in the caller object.

call "myMacro" parameters all extraParam = 1 call "myMacro" parameters returned_parameters realWidth call "myMacro" parameters all extraParam = 1 returned_parameters realWidth call "myMacro" parameters all returned_parameters realWidth

Script in the macro.

realWidth = 2 end realWidth

5.2 Master GDL

Use Master GDL scripts to define custom attributes (materials, fills and line types) for more objects in the library. This can reduce library size and make further modifications easier. Master GDL scripts have to be named like this: Master_GDL name.gdl (e.g., Master_GDL Materials.gdl).

Note: If you want to publish your library on the web or on CD, you have to consider the following:

6. Speed issues

Try to avoid using the project2 command as it slows down plan regeneration.

Reduce the number of surfaces in your model to the minimum in order to make 3D regeneration faster. Use RESOL, TOLER and RADIUS commands to control segmentation of curved surfaces.

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

Scripting the master script consider that the master script is run before each script type, so don't put script-type specific calculations here. This is the place for common calculations needed by multiple scripts.

Scripting doors and windows avoid to make unnecessary cuts (wallhole and wallniche).

Use integer values and operations whenever reasonable, these are much faster than floating point operations.

Try to minimize using string operations.

In case of calling macros use the same parameter order after the call command as it is in the parameter list of the macro. call "myMacro" parameters all is faster when the parameter orders of the macro and the caller object are similar. Try to avoid transfering string type parameters in macro calls. Use numeric types instead.

7. Tools for Library developers

The following tools have been developed by Graphisoft to speed up library development, localization and quality checking. We encourage you to use them.

7.1 Special menu commands

The commands listed below are available from ArchiCAD's Special Menu.

View of the Special menu on Windows

3D model coding support

The first six menu items give you an advanced control over the 3D view of ArchiCAD. This may help you on developing complex models and on validation and optimalization as well.

Interrupt with Library Part error messages

With this option you can enable Library Part validation on the 2D plan. You receive the messages when the GDL interpreting is done for the placed objects - on placing and on rebuild. This may facilitate error checking of libraries via checking reasonable test plans. Note that turning this option on will slow down 2D rebuild time. To always get every error and warning message, enable this and Library Check.

Library Check

With this option you get warning messages during Library Part validation in 3D. If you also enable Interrupt with Library Part error messages, then you get every error and warning message during 2D and 3D generation. To always get every error and warning message, enable this and Interrupt with Library Part error messages.

Save GDL

This feature allows you to save the attributes of an ArchiCAD file or the 3D model in a GDL file. After choosing the command a dialog appears where you can set the type of the generated script and the destination file.

the 3D model is described with GDL primitives
GDL 3D spec#1, GDL 3D spec#2, GDL 3D spec#3
the 3D model is described with GDL primitives
GDL materials
all materials are saved as GDL definitions
GDL Fills, Ltypes
all fills and linetypes are saved as GDL definitions
Master GDL
all settings are saved as GDL definitions

This tool can be very useful for making master GDL scripts and for defining custom attributes.

Place all objects

This command places a piece of each descendant of the selected subtype in the loaded library onto the plan. The elements are set with their default parameter settings. This tool can be used for checking complete libraries for errors in 2D (especially useful with the Interrupt with Library Part error messages option) and in 3D. You can control the placement of built-in elements either.

Test all library parts

This command tests all loaded part in some aspects. These checking steps give you an overall view about the loaded library's quality and speed. Look into the list of them.

Total compile time 2D
Measure total 2D compile time of library
Total compile time 3D
Measure total 3D compile time of library
Total model generation time
Measure total 3D model generation time
Place all library parts
Place all library parts in 2D and measure the elapsed time
Measure 2D rebuild time for the whole library
Slowest 2D compiles
Order library parts by 2D compilation time
Slowest 3D compiles
Order library parts by 3D compilation time
Slowest model generations
Order library parts by 3D model generation time. This is a good way to detect slow objects.
Biggest polygon counts
Order library parts by polygon counts. This is good way to detect overcomplicated objects in 3D.
Symbols with solid operations
Collect objects with solid operations
Possible problematic code
Collect objects with slow operations: STW, PROJECT2, VARMACRONAME, H~

7.2 Drag and Drop technique

This ArchiCAD feature allows you to easily define complex 2D and 3D shapes in GDL by drawing them on the plan and dragging them into the 2D or the 3D script of an object.

How does it work?

Note: Curved polygons (slabs, fills, etc.) will be saved with curved edges (with status codes) in the 2D script while in 3D script curves are replaced with straight segments.

7.3 LP_XMLConverter tool

This commandline tool converts library parts to XML files and vice versa on Windows and Macintosh plaftorms. Usage of the tool faciliates the creation process of ArchiCAD Libraries by the benefit of a cross-platform text-based format for the time of development. With this feature it is the most powerful tool for library developers.

The XML format enables the following:

Using the tool you can convert single files and whole libraries, too.

Converting XML files you can use external picture files to include in the target library part.

Converting whole libraries from XML the converter can be instructed to repair the ancestry information, the version, the macro-call section and the parameter section of each library part file in the library and to perform certain checking steps for the library.

On fail of the following tests warning messages are displayed:

7.4 Status Report palette

The purpose of the Status Report is letting the user know some possible problems with the currently loaded library.

It has three main sections, as follows.

If there are conflicting duplicates or missing objects in the loaded Libraries of a project file, then the 'Status report' window will pop up after opening the file. Library parts with duplicate names will not trigger the 'Status Report' window upon opening the file.

See the example below:

Status Report Window - Missing/Double tabpage

8. Windows-Macitosh compatibility

Compatibility limitations

Though GDL objects and libraries are considered by Graphisoft as platform independent, the following difficulties occur when you manually move Windows objects to a Macintosh:

Changing platform with binary libraries

To avoid these problems, save a multiplatform archive file of your library whenever changing platforms. Be sure to turn on the 'Save in MultiPlatform Format' checkbox in the Options/Preferences/Miscellaneous menu.

After opening the archive file on the other platform, manually change non-system fonts in your objects and list templates to system fonts. This can be simply omitted if all fonts are set to 'Arial' since it exists on both platforms.

Consequently when delivering a binary library the developer has to provide both Windows and Macintosh libraries - tested on the corresponding platform.

Changing platform with XML libraries

The XML format library parts are fully platform independent since XML has this property. So XML files can be simply copied between Windows and Macintosh, but don't forget the issues described above (about font names and listing text files).

This may imply a false confidence in the developer, but don't forget to test the library on both platforms from time to time - with special care for user interface scripting and texts.

9. Localization

The aim of localization is to create a local or national version of the international ArchiCAD library. This became much easier with the release of the LP_XMLConverter tool (refer Section 7.3) and the XML library part format.

9.1 Localization steps

9.2 Place of values to be localized in the XML format

Look into the following examples to get a vision about the location of the above mentioned values in our XML format. Using a text editor tool which takes regular expressions as target for the 'search/find' operation, you can easily find and replace them.

Parameter descriptions
<Description><![CDATA["Fill Pen"]]></Description>
Value lists
<Script_VL SubIdent="0" SectVersion="0" SectionFlags="0">
values "gs_detlevel_3D" `Detailed`,`Simple`,`Off`
String default values
<String Name="gs_detlevel_3D">
Attribute-related parameters defaults
<PenColor Name="gs_cont_pen">
    <Description><![CDATA["Contour Pen"]]></Description>
Texts of the 2D symbol
<Drawing Ordering="..." SubIdent="0" SectVersion="17" SectionFlags="0">
            <L_RET><![CDATA["X short side length"]]></L_RET>
            <L_RET><![CDATA["must be smaller"]]></L_RET>
            <L><![CDATA["than X size !"]]></L>
                        <L><![CDATA["Invalid parameters!"]]></L>
Scripted texts
<Script_2D SubIdent="0" SectVersion="0" SectionFlags="0">

text2 x, y, `Height`

<Script_3D SubIdent="0" SectVersion="0" SectionFlags="0">

text depth, 0, `Hotel`
print `Warning message`

<Script_UI SubIdent="0" SectVersion="0" SectionFlags="0">

ui_dialog `Custom Settings`, 444, 266
ui_button ui_prev, `<< Previous`, 250, 3, 90, 20
ui_button ui_next, `Next >>`, 350, 3, 90, 20
ui_groupbox `Dimensioning`, 3, 70, 438, 100
ui_outfield `Story Height:`, xText, 52, 135, 15
ui_infield "topTreadLevel", xCol1, 90, 444-xCol1, 75, 1, "Image name",
				2, 1, 110, 60,
				65, 37,
				1, `At Floor Level`,
				2, `Below Floor Level`


10 Libraries outside of ArchiCAD

This chapter explains how to create web conform GDL objects for GDL Explorer, GDL Adapter and GDL Web Plug-in.

10.1 General requirements

If you want to publish your library out of ArchiCAD, you must make it compatible with GDL Tools by following these guidelines.

There should be a master GDL file in the library that contains all line types, fills and materials used by the library and all global parameters used by the GDL Web Plug-in. The name of this file has to be 'master.gdl'.

The Object's default material, fill and line type parameters have to be set correctly to work without errors in the tools.

The specified materials have to be in the master script of library part.

The default unit of the length parameters has to be set correctly (meter, inch, etc.) according to the national standards.

To make library downloading faster, all image files without alpha channel should be converted into JPEG format. Files with alpha channel should be saved in TIFF format.

The default settings and attributes of the application are defined in the master.gdl, which is not downloaded with the object. It means that you can't define custom values and custom materials here. If you want to use custom attributes you have to define them one by one in the master script of the objects. Refer these materials by their names.

10.2 Converting libraries

You have to write a correct master.gdl file first. Use the "Save GDL" function from "Special" menu to save ArchiCAD attributes into GDL files. Use the "GDL fills, line types" and then the "GDL materials" option from the "Files of type" pull down menu and save both files.

Create a new GDL file and copy the content of the two files into it. If you have one master GDL file already, you have to rename and redefine it. Please note that ArchiCAD uses the "master_gdl name.gdl" filename, while in the Object Web Plug-In it has to be called "master.gdl".

After creating your master GDL file, you have to add the following global variables, required by the Object Web Plug-In, at the beginning of the script.

! --- Global Parameters --- glob_scale = 100 symb_linetype = 1 symb_fill = 65 symb_fill_pen = 2 symb_view_pen = 1 symb_fbgd_pen = 91 symb_sect_pen = 1 symb_mat = 1 Wall_line_type = 1 Wall_Fill = 65 wall_fill_pen = 2 wall_view_pen = 1 wall_fbgd_pen = 91 wall_mat_a = 1 wall_mat_b = 1 wall_height = 2.7 wall_thickness = 0.25 mglas = 1

Load the library with the new master.gdl file. Open the Option/materials (fills, line types) settings dialog, create a material (fill, line type) and delete all the materials, fills, and line types except the one you created. Reload the library. Now you should only see the materials, fills, and line types defined in the master.gdl and the ones you have just created. Redefine the default parameter values for lines, materials and fills in all objects.

If you have GDL Explorer you can check your library in this application. When your library doesn't give any alerts, you can publish it on the web.

10.3 GDL Tools online documentation

For more information about the GDL Tools refer the online documentation of them.