GDL Technical Standards 2.0

Index

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 9.

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):

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

Introduction

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

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".

• The Main ID is created when the library part is saved for the first time. It is also modified if the library part is resaved using the "Save as" command.
• The Revision ID is also created when the library part is saved for the first time but it is modified if the library part is resaved using the "Save" command. Using the LP_XMLConverter tool a compilation will change the Revision ID and leave the Main ID untouched, of course (for further information on LP_XMLConverter refer Section 7.3 of this document).

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:

• Open Object by Subtype... (in File menu)
• Select Subtype... (in the Library Part Editor window)
• Place All Objects (in the Special menu)

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).

Conclusions

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
EPS = 0.0001
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 abs(iTopTreadLevel - 2) < EPS 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:

• Ability to build up a sophisticated hierarchy according to the real logic of the system to model.
  For example, the International ArchiCAD Library follows the IFC standard in its subtype hierarchy.
• Possibility to define functional classes of objects cooperating ArchiCAD.
  Defining an object as a descendant of the Window (Wall) subtype - shipped with ArchiCAD - causes that it appears everywhere where windows do and ensures that it has the necessary parameters for this functionality.
• Possibility to define functional classes of objects for add-ons.
  An add-on can deal only with a given class of objects. It can decide easily if an object is in this group and if so the add-on can trust in the presense of the parameters of the defining subtype.
• Higher reliability in object substitution.

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).

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

Note:

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.

Example

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.

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 you 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).

2D 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.

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.

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.

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:

• Placing parameter definitions and calculations used by multiple scripts in the master script is a good idea, it reduces file size and makes elements easily modifiable.
• Be sure to put only common calculations here because they will slow down the evaluation of all scripts which don't need these calculations.
• Avoid using the parameter buffer in the master script for effectivity reasons.
• Do not put end commands in the master script; otherwise, ArchiCAD will not run the rest of the scripts.

4.2 2D script

Execution context

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

• 2D plan
• 2D editing feedback
• 2D preview in the Object Settings dialog window

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:

• 3D window (wire, hidden line, solid model)
• 2D plan when project2 is used to project the 3D model to 2D
• 2D section - mind the details
• 3D edititing feedback - optimize for speed
• Operator for solid operations in 3D - ask the designer for the desired funtionality
• Surface and volume calculation for Listing
• 3D preview in the Object Settings dialog window

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).

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

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.

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

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.

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:

• Opening the Object Settings dialog window
• Changing a parameter's value in the Object Settings dialog window
• Changing a parameter's value using editable hotspots (even while generating the feedback)
• Stretching the object using conventional hotspots

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

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 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	Output

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.

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.

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:

• The 'master_gdl.gdl' of ArchiCAD is different from the 'master.gdl' of GDL Web Plug-in, GDL Adapter and GDL Explorer.
• Custom materials, line types and fills defined in the master_gdl will not be downloaded from GDL Web Plug-in and GDL Explorer. In the 'master.gdl' - which these applications use - you can only define the default attributes. If you want to use custom attributes you have to define them one by one in the master script of the objects. A workaround can be to call the master_gdl.gdl from master.gdl at the very end of the script.

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.

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.

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.

GDL 3D

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

Rebuild

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?

• Draw the desired elements on the plan file.
• Open the GDL object's 2D or 3D script. Arrange the windows on your monitor to see both the script window and the plan view.
• Select the objects you want to drag.
• Drag the selected elements on top of the script window.
• The GDL description of the selected elements appears in the script window.

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:

• Platform independent, text based storage of libraries in development time
• Integrating the library development into a versioning system
• Making text-based operations in a natural way
• Easy parameter block movement operations
• Localization support

Using the tool you can convert single files and whole libraries, too. For all kinds of conversion you can specify the character code page of the library parts.

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:

• Folder and file names shouldn't exceed 31 characters
• Folder and file names shouldn't contain illegal characters
• The scripts shouldn't conatain illegal local characters
• All used picture formats should be supported in ArchiCAD
• There shouldn't be any unused macros
• There shouldn't be any objects with missing ancestors

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.

• Items listed under 'Missing Library Parts' are the Library parts, which are placed on the plan but they are not present in the loaded Library.
• Items listed under 'Duplicate Library Parts' are having the same inner ID, these Library parts cause a conflict.
  For library developers it shows a serious problem, you have to change the main ID of one of the conflicting objects or remove the unnecessary one from the library.
• Items listed under 'Duplicate Names' are Library parts having identical names, these are not conflicting since ArchiCAD identifies them by an inner ID.
  For library developers it shows a simple problem, let's avoid duplicated names for clarity of the library.

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:

• Armchair 01.gsm is missing:
  it is not found in the loaded libraries
• Duplicate Library Parts:
  Armchair 02.gsm was found twice in the loaded libraries: please remove one of the two to avoid conflicts in the project
• Duplicate Names:
  there are two different objects called Armchair 03.gsm in the loaded libraries, however there's no conflict between them - work with this project can be continued.
  However, to avoid confusion, we suggest not to use different library parts sharing the same name.

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:

• Resource forks will be missing from objects; therefore they loose their icons (type creator).
• Windows fonts will be replaced by the default Macintosh font in objects and list templates and vice-versa.
• Text type listing files (listset.txt, listkey.txt, list templates, etc.) could lose line breaks, therefore listing won't work.

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

• File and folder names have to be translated (except macro and texture files) unless otherwise requested.
• Parameter descriptions have to be translated in all library parts. This can be done simply with advanced text editors using the XML format of the library to localize.
• Value lists and default values of string-type parameters have to be translated.
• Value lists and default values of numerical parameters have to be changed so that they apply the local standards and needs (metric-imperial units, local ArchiCAD attributes, window door opening direction etc.).
• The default values of attribute-related parameters (fill type, pen color, line type, material) have to be changed so that they apply the localized attributes of ArchiCAD and the local standards and needs.
• Displayed texts have to be translated:
  • Texts of the 2D symbol: in XML - Symbol / Drawing / Text / TLines
  • Scripted texts in 2D: text2 GDL command
  • Scripted texts in 3D: text GDL command
  • Scripted warnings: print GDL command
  • Scripted User Interface tabpage texts: ui_dialog, ui_button, ui_groupbox, ui_outfield, ui_infield
• It is suggested to use different quotation marks for localized and the non-localized string values. In this case a simple text parser tool can be made to collect the strings to be localized.
  In ArchiCAD libraries " frames non-localized strings (e.g. macro-calls, parameter names in scripts) and ` frames localized ones (string-type parameter values).
• Font types in objects have to be changed to ones supported by the national Macintosh and Windows operating system.
• The library has to be checked for errors. Use a file comparator tool and load the library into ArchiCAD, too.

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">
<![CDATA[
...
values "gs_detlevel_3D" `Detailed`,`Simple`,`Off`
...
]]>
</Script_VL>

String default values

<String Name="gs_detlevel_3D">
    <Description><![CDATA["3D"]]></Description>
    ...
    <Value><![CDATA["Detailed"]]></Value>
</String>

Attribute-related parameters defaults

<PenColor Name="gs_cont_pen">
    <Description><![CDATA["Contour Pen"]]></Description>
    ...
    <Value>10</Value>
</PenColor>

Texts of the 2D symbol

<Drawing Ordering="..." SubIdent="0" SectVersion="17" SectionFlags="0">
    ...
    <Text>
        ...
        <TLines>
            <L_RET><![CDATA["X short side length"]]></L_RET>
            <L_RET><![CDATA["must be smaller"]]></L_RET>
            <L><![CDATA["than X size !"]]></L>
        </TLines>
    </Text>
    ...
    <RichText>
        ...
        <Content>
            <Paragraph>
                ...
                <TextStyles>
                    <TStyle>
                        <Size>4</Size>
                        <StyleInd>15</StyleInd>
                        <PenInd>10</PenInd>
                        <L><![CDATA["Invalid parameters!"]]></L>
                    </TStyle>
                </TextStyles>
            </Paragraph>
        </Content>
    </RichText>
    ...
</Drawing>

Scripted texts

<Script_2D SubIdent="0" SectVersion="0" SectionFlags="0">
<![CDATA[

text2 x, y, `Height`

]]>
</Script_2D>

<Script_3D SubIdent="0" SectVersion="0" SectionFlags="0">
<![CDATA[

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

]]>
</Script_3D>

<Script_UI SubIdent="0" SectVersion="0" SectionFlags="0">
<![CDATA[

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`

]]>
</Script_UI>

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.