GDL Technical Standards

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

You should use the GDL Manual for studying the GDL language, its commands and their parameterization. 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 Identification

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, the program stores the reference by the ID and considers the name only for objects without an ID (library parts saved before ArchiCAD 8 and .gdl files). In case of Library Parts coming from versions earlier than ArchiCAD 8, there was no such thing as a GUID. So when such a Library Part is encountered in the file, ArchiCAD will fill out its ID with zeros.

When loading a library, ArchiCAD uses the following hierarchical criteria for matching loaded library parts to objects already placed in the project:

1. In case the stored ID is valid:
   1. ArchiCAD tries to get an exact mach of both parts of the ID
   2. Failing that, ArchiCAD tries to match the first part of the ID, which is the Main ID
   3. Finally, when loading files saved before ArchiCAD 12, ArchiCAD tries to match by library part name.
2. In case the stored ID is zero, the identification procedure tries to match by name only.

The same process is executed when looking for macros in a placed element as every library part contains a lookup table for its called macros' GUIDs. Naturally, when saving an object containing macro calls, this table is collected using a name-based search in the currently loaded library.

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

For this you have to get to know 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 renaming an object won't make it incompatible with its past self for ArchiCAD. Similarly, naming a new element (with a new ID) the same as a previous one won't make them compatible.

This issue effects the localization of libraries, too. If you have string type controlling parameters, the relevant values will differ between national versions. 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 friendly - 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 hierarchical 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 presence 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 behavior or attribute of the object or ArchiCAD will assign a value to it to inform the object of an external parameter (e.g. a parameter of an element linked a label object). For some legacy ArchiCAD features the ac_ prefix is omitted (e.g. 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 various 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 === ! statements 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 grayed endif and stops there; though the problem is obviously 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 parameterization 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.

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 lets 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 - that 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 - the 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 details 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 - that information can be derived from the script type. The object 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 other views consequently. The 2D and 3D models are not distinguished - that 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 - that 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 subtract 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 subtract 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 method 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.

3.9 Model View Options, Library Global

The display of library parts in the plan may depend on the current view.

Internal Model View Options

The view's internal settings are available via GDL global variables (e.g. GLOB_SCALE, GLOB_STRUCTURE_DISPLAY) and request options (e.g. "window_show_dim", "door_show_dim", "floor_plan_option", "view_rotangle").

Library Global View Options

From ArchiCAD 13 on, you can define view options from your library. These option are stored into each view and they are returned accordingly.

Things which should be stored in view dependent library globals:

• showing/hiding opening lines
• showing/hiding minimal spaces
• pen and other view attributes which shouldn't be changed individually for the sake of uniformity (e.g. minimal spaces)
• showing/hiding specific accessory elements (e.g. knobs, handles)

Things which should NOT be stored in view dependent library globals: general values for the whole project, general values for the whole country, values which may be required to be set individually for objects.

To insert a tab page into the MVO dialog, you have to make a library part which is derived from the Library Global Settings (GUID: {709CC5CC-6817-4C56-A74B-BED99DDB5FFA}) subtype. This object must contain the desired global options as parameters and it must have a user interface definition for the tab page. It may have a parameter script for connecting parameters or user interface elements.

The new LIBRARYGLOBAL command can be used in your placeable elements to query values of your own library global settings object depending on the current view settings.

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 effectiveness 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
• layout drawing
• layout drawing feedback

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

1. Execution context
2. General recommendation
3. Modeling transparent bodies
4. Texture mapping
5. Picture elements
6. Group operations

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 editing feedback - optimize for speed
• Operator for solid operations in 3D - ask the designer for the desired functionality
• Surface and volume calculation for Listing
• 3D preview in the Object Settings dialog window
• layout drawing when project2 is used to project the 3D model to 2D
• layout drawing feedback

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.

Modeling 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

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

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

When using different texture mapping modes, you should take care of correct axis definitions with the vert or teve commands. The node order is shown below.

You can distort the textures by setting different distances between the nodes defined by the vert or teve commands.

Take care that working with different rendering engines can produce slightly different results, see the examples. (Click on the images to enlarge them.)

Correct texture mapping on complicated surfaces or distorted textures can be modeled with coor and teve commands. In this way you can make surface models only.

See the following example.

base teve 0, 0, 0, 0, 0 teve 1, 0, 0, 1, 0 teve 1, 1, 0, 1, 1 teve 0, 1, 0, 0, 0.5 teve 0, 0, 1, 0, 0 edge 1, 2, 1, 0, 0 edge 2, 3, 1, 0, 0 edge 3, 4, 1, 0, 0 edge 4, 1, 1, 0, 0 pgon 4, 0, -1, 1, 2, 3, 4 coor 1024 + 1, 1, 2, 3, 5 body -1

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

Group operations

Group operations bring the power of solid operations into GDL. On the other hand they present a risk factor when misused.

An important point is that you mustn't place a group inside another one. In such situations you should define a new group like in the source snipplet below:

subtractionResult = subgroup ("sub_operand_1", "sub_operand_2")

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 parameter script MAY be run on:

• Dragging the object, in case the object refers to SYMB_POS_X/SYMB_POS_Y
• Update Zones runs the parameter script of the affected zones if necessary

The parameter script is NOT run on:

• Rebuild
• Changing scale
• Changing storey

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

Setting limits for array parameters

Array parameters should be used for homogeneous data; i.e. all array elements should have a similar meaning. We get into trouble when we want to set limits to array elements and when putting them on the UI.

On one hand, array parameters should not be displayed in the graphical UI directly. Preferably you should expand the array to one or more scalar parameters of the same type.

On the other hand, the VALUES command does not work for array type parameters. It must be emulated for hotspot editing and for the user interface.

for hotspot editing

set the limits manually for the array elements and use the PARAMETERS command

on user interface

you should add a scalar parameter of the same type which represents only one element of the array and an integer or other chooser by which the user can control which array element to manipulate through that one parameter; naturally, the non-array parameter can have a range defined

Example code snipplet for limiting all components of parameter gridXPosition to the range [1, 5] - when nGridLines controls the size of the array and uiGridXPosition is used on the UI:

! parameter script for i = 1 to nGridLines if gridXPosition[i] < 1 then gridXPosition[i] = 1 endif if gridXPosition[i] > 5 then gridXPosition[i] = 5 endif next i parameters gridXPosition = gridXPosition values "uiGridXPosition" range[1, 5] if GLOB_MODPAR_NAME = "uiGridXPosition" then parameters gridXPosition[iGridPosXOnUi] = uiGridXPosition else parameters uiGridXPosition = gridXPosition[iGridPosXOnUi] endif

4.5 User Interface script

Execution context

The User Interface script's result displays in one context only, the user interface tab page 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 tab page 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.

Note that ArchiCAD uses tries to match the fonts used in dialogs with the operating systems. When scripting graphical user interfaces on Windows, leave more space around texts otherwise Mac users will see truncated texts.

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

Output - the control on the UI page

Tab page handling

In ArchiCAD 10, a new dynamic paging technique was 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 parameter 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)

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)

Font sizes on the UI

If you use static texts (possibly in combination with the ui_style command), be aware of the following.

Because of the differences of the targeted operating systems, font sizes are not the same on Windows and on Mac. As a side effect, the extra small font size is a bit larger than the small one on Windows. As a general rule, always test user interfaces on both platforms to check overlapping and clipping.

Furthermore, special styles like Bold, Italic and Underline are not allowed in combination with extra small size. Outline and Shadow are old Macintosh styles, which are no longer used.

The two pictures show the look of static texts with different sizes and styles. The first was shot on Windows, the second one on Mac.

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 transferring between the caller object and the macro was improved in ArchiCAD 10. Find out tips about utilization of macro call's speed enhancements 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:

• 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 making 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 transferring 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 and Library Developer menu commands

After completing the steps below, the Special menu will appear in the Work Environment, and you can add it to your menu bar. Starting from ArhiCad 15, some commands of the former Special menu are accessible from a new group called Library Developer menu. By invoking the Special menu, you also gain access to this new folder of commands. You can add it to your menu bar the usual way as well.

Invoking the Special Menu on Windows

• Open Windows Registry from Start Menu/Run by typing regedit (or by typing it into the search field of the Start menu, then selecting the program)
• Find registry key: HKEY_CURRENT_USER\Software\Graphisoft\ArchiCAD\ArchiCAD 15.0.0 INT R1 or similar
• Set value of DWORD Special Menu to 1

Invoking the Special Menu on Mac OSX

In order to turn on the special menu you will need to set a key in the preference file for Archicad. Your preference file should have a path and file name similar to the following (this example shows preference file for ArchiCAD 15 INT version:)

/Users/[user name]/Library/Preferences/com.graphisoft.AC 15.0.0 INT V1.plist

You can edit the preference file with third party tools like Pref Setter: http://www.apple.com/downloads/macosx/system_disk_utilities/prefsetter.html

• Download and install Pref Setter
• Open the .plist file with Pref Setter, and find the key Special Menu
• Set value to "true"

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

3D model coding support

The first six menu items give you advanced control over the 3D view of ArchiCAD. This may help you to develop complex models and with validation and optimization as well.

The commands listed below are available from ArchiCAD's Library Developer Menu

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 as well.

Test all library parts

This command tests all loaded parts 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~

Run parameter script on placed Library Parts

This command runs the parameter script on all placed parts.

Library Check

With this option you get warning messages during Library Part validation in 3D. This option changes the content of the Library Loading Report Palette (and the equivalent part in the Library Manager Dialog) to detailed. To always get every error and warning message, enable this and Interrupt with Library Part error messages.

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

Dump library parts of selected element

This command lists all the parameters with their actual values of the selected library part in the Report Window.

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.

Search callers

It makes a list of the callers of a library part in the Report window by name. All you have to do is highlight the library part name in the text or script (a macro name for example), then hit this command.

Other platform symbols

Lists library part symbols on an Intel machine saved from a PowerPC or vice versa.

Update library parts

Updates version, ancestry and macro call infos in all items in the active libraries (by changing revision ID-s).

Update library parts advanced

Acts like the previous command, with one additon: you can choose to hide all scripts.

Ignore built-in libraries

By activating this command, ArchiCAD will load the corresponding editable libraries instead of the read-only built-in ones at next start-up.

Create new GUID for migration and save

This command creates a new library part with a new GUID, automatically placing the GUID of the original element into the Migration table of the new library part in the meantime.

Export all placed objects to XML

This command exports all placed objects to an XML file.

Import and place objects from XML

This command imports and places the objects in the given XML file.

Export library to XML

This command exports the list of linked libraries to an XML file.

Copy with Backward Migration

This command copies the selected placed objects to the clipboard, but runs backward migration on them.

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 command line tool converts library parts to XML files and vice versa on Windows and Macintosh platforms. Usage of the tool facilitates 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.

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 contain illegal characters
• The scripts lines shouldn't be more than 255 characters long
• 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 Library Loading Report

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

The report can come in two levels of detail. If you indicate that you are a library developer via the Library Check option, you get a more detailed report.

The report has five main sections, as follows.

• Items listed under Missing Objects are the Library parts, which are placedon the plan - or referenced by a placed library part - but they are not present in the loaded Library.
• Items listed under Duplicates (same revision ids) are having the same inner ID. This means that exactly the same library part is loaded more than once. For end users it usually isn't a problem. Library developers should eliminate duplicates from their libraries.
• Items listed under Duplicates (different revision ids) are having the same function/main ID. This means that more revisions of the same object are present. 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. For end users, these are not conflicting since ArchiCAD identifies them by an inner ID. They are not even reported for them. For library developers (having Library Check switched on) it shows a simple problem, duplicate names. Avoid duplicate names for clarity of the library and for correct finalization.
• Items listed under Substituted Objects come from placed object instances, which have more possible matches from the library but none of them is an exact match. In such situations, ArchiCAD will make the connection randomly. All these problems are caused by a Duplicates (different revision ids) situation in the first place.

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

Example with Library Check switched on:

Example with Library Check off:

7.5 GDL Debugger

The GDL Debugger is a hidden tool in ArchiCAD which can facilitate bug tracing in GDL. It allows you to run a GDL script line by line. You can check the result of the model generation and the value of each variable after each step. You can even stop at breakpoints you defined in your script via the BREAKPOINTS command.

This tool can be found in the Edit menu as Open Debugger....

The main window shows the list of watched variables. You can add any variable in the script to it and you can see the value of each variable at any time of the running. Under the list of variables, you can read the name of the original object and script under debugging (Main script) and the name of the currently debugged object/macro. These two values are different only when you are debugging a called macro.

Debugger buttons

Run

Start to execute the current script if it is not running or run it to the end or the next breakpoint otherwise.

Step Over

Execute the next command in the script. If the next command is a macro call, it will be executed in one step.

Step In

Execute the next command in the script. If the next command is a macro call, the debugging will go into the macro.

Step Out

Execute all commands left in the macro and step back to the caller script.

Kill

Stop debugging.

Enable Breakpoints

When enabled, the GDL debugger will stop at BREAKPOINT commands even in run mode. When disabled, BREAKPOINT commands are ignored.

Add...

Add a variable to the list of watched variables.

Add all

Add all variables available in the current script to the watched variables.

Remove

Remove the selected item from the list of watched variables.

8. Windows-Macintosh 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 tab page 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 to the online documentation.