November 20, 2020
by Viktor Kovacs
modified at December 9, 2020

Getting started with Archicad Add-Ons

The goal of this tutorial is to show you how to write an Archicad Add-On from scratch.

Archicad Add-On Basics

The programming language of Archicad Add-Ons is C++, so you have to be familiar with this language to start. Archicad is extensible in several ways: creating new menu commands and dialogs, import-export functionalities, etc. The API itself is general purpose, so you can write various Add-Ons with the same Development Kit.

What will You Need?

First, you will have to set up your development environment:

  • Archicad – The demo version is perfectly fine for experimenting with the API, but it has some restrictions that you may experience during the development process.
  • API Development Kit – This will allow you to build Archicad Add-Ons on your computer.
  • CMake – To generate IDE projects (3.16 minimum version is needed).
  • Python – For some build tools (version 2.7+ or 3.8+).
  • Depending on your platform you will need a development environment. On Windows this is Microsoft Visual Studio, on MacOS this is Xcode.

For different Archicad versions you will have to use different versions of developer environments. You can see the details in the table below.

WindowsMacOS
Archicad 23Visual Studio 2017 (v141 toolset)Latest Xcode (deployment target macOS 10.12)
Archicad 24Visual Studio 2017 (v141 toolset)Latest Xcode (deployment target macOS 10.13)
Archicad 25Visual Studio 2019 (v142 toolset)Latest Xcode (deployment target macOS 10.15)

Structure of the API Development Kit

After you installed the Development Kit you will find three folders at the install location.

  • Documentation: This is the folder for API documentation. You can find here a reference for all of the API functions. The documentation is available online, too.
  • Examples: Here you can find a lot of example Add-Ons. These can be a good starting point to understand how the API works. Feel free to open the IDE projects, and investigate the possibilities.
  • Support: This is the most important folder. It contains all the header and library files for Add-On development, and the tools for resource compilation. This is the folder you will need to build your Add-On.

Let’s Build Your First Add-On

You can start with one of the example Add-Ons, but it’s much easier to start with the template available on GitHub. Download the Archicad Add-On template from here.

Generate IDE Project for the Add-On

After you downloaded the template Add-On, you have to use CMake to generate the project for your favourite Development Environment. Starting from the root folder you can generate the projects with the commands below. Make sure to replace the value of AC_API_DEVKIT_DIR variable with your DevKit installation folder.

On Windows:

mkdir Build
cd Build
cmake -G "Visual Studio 15 2017" -A "x64" -DAC_API_DEVKIT_DIR="C:\API Development Kit 24.3009" ..
cd ..

On MacOS

mkdir Build
cd Build
cmake -G "Xcode" -DAC_API_DEVKIT_DIR=/Applications/GRAPHISOFT\ ARCHICAD\ API\ DevKit\ 24.3009 ..
cd ..

Please note the “..” at the end of the commands. It means that CMake will search for the CMakeLists.txt file in the parent folder.

Build the Add-On

After you generated the IDE project, open it, and press Build. If everything goes fine, you will see no errors or warnings, and an .apx file (Windows) / .bundle (macOS) is created in your result folder.

Try the Add-On in Archicad

You have several ways to load the Add-On in Archicad. For development purposes the best if you browse it directly from your build folder, so every modification will appear in Archicad immediately.

1. Open the Add-On Manager Dialog by selecting Options / Add-On Manager.

2. Click the Add button under the EDIT LIST OF AVAILABLE ADD-ONS tabpage.

3. Browse your Add-On’s .apx/.bundle file, and if everything went well your Add-On will appear in the list of Add-Ons.

4. After closing the Add-On Manager you will see a new command registered by the Add-On: Options / Example AddOn Command.

5. Click on the command, and you will see a very simple dialog created by the Add-On.

Congratulations! You just built your first Archicad Add-On.

Something doesn’t work?

Sometimes you may meet the error messages below. It means that an error happened during the Add-On loading process. There could be several reasons for this issue, see below.

Invalid Development Kit Version

Archicad can’t load an Add-On if it was created with a different version of the Development Kit. Double check the version of your Archicad and the used Development Kit, they should match.

Invalid MDID

Please note, that the example Add-On works only with the DEMO version of Archicad. To release your Add-On you have to register for an MDID (see the details in the Releasing Add-Ons chapter). To work around this issue you can start Archicad in DEMO mode by passing a command line parameter to the executable.

On Windows

Archicad.exe -DEMO

On Mac

"ARCHICAD 24.app/Contents/MacOS/ARCHICAD" -demo

Anatomy of an Add-On

You can find several subfolders in the Sources folder.

Add-On Sources

The source code for the Add-On is in the AddOn folder.

There are four important entry points for Add-Ons.

  • CheckEnvironment: This function is called before any other functions. You can check if your Add-On can or allowed to run in the current environment. You also have to provide the Add-On’s name and description. This information will appear in the Add-On Manager.
  • RegisterInterface: This function is responsible to register interface elements in Archicad (like menu commands, tool box items, etc.).
  • Initialize: This function is called when the Add-On is loaded into the memory, before performing any of the Add-On’s functions.
  • FreeData: This function is called when the Add-On is unloaded from the memory.

You can find a more detailed explanation of these functions here.

API_AddonType __ACDLL_CALL CheckEnvironment (API_EnvirParams* envir)
{
    RSGetIndString (&envir->addOnInfo.name, ID_ADDON_INFO, 1, ACAPI_GetOwnResModule ());
    RSGetIndString (&envir->addOnInfo.description, ID_ADDON_INFO, 2, ACAPI_GetOwnResModule ());
 
    return APIAddon_Normal;
}
 
GSErrCode __ACDLL_CALL RegisterInterface (void)
{
    return ACAPI_Register_Menu (ID_ADDON_MENU, 0, MenuCode_Tools, MenuFlag_Default);
}
 
GSErrCode __ACENV_CALL Initialize (void)
{
    return ACAPI_Install_MenuHandler (ID_ADDON_MENU, MenuCommandHandler);
}
 
GSErrCode __ACENV_CALL FreeData (void)
{
    return NoError;
}

Add-On Resources

The source code for resources is in the AddOnResources folder.

  • RFIX: Fix, non-localized resources, like images.
  • RFIX.mac, RFIX.win: Platform dependent utility codes.
  • RINT: Resources to be localized.
  • Tools: Resource builder tool.

Archicad Add-Ons can work on both Windows and macOS platforms, so you can’t use native resource files for localized strings and dialogs. This is why we invented the .grc format, which is a platform independent resource description format working on both platforms. It means that you have to define your resources only once, and then the code will work on both platforms without any modifications.

Debugging

Debugging is pretty straightforward. You just have to attach your debugger to the running Archicad process, and then you can debug your Add-On like any other applications. To make the process more smooth, you can set Archicad as the executable for the Add-On project, and just hit debug to start Archicad.

Visual Studio Tips

Make sure that when you attach to the Archicad process, “Native code” is selected in the “Attach to” item in the dialog. Also note, that the breakpoints doesn’t seem to be active until your Add-On is loaded into the memory. Just place your breakpoints, call one of the Add-On’s functionalities, and it should work.

Call an API Function

Let’s write an example Add-On that counts the number of walls in the current plan.

First of all, you have to include a new header file, because some of it’s functionalities will be needed.

#include "StringConversion.hpp"

As you see in the example Add-On you can register a menu command, and then handle it like in the example below. When the user clicks on the command, the code will call the CountNumberOfWalls function to do the job for us.

static GSErrCode MenuCommandHandler (const API_MenuParams *menuParams)
{
    switch (menuParams->menuItemRef.menuResID) {
        case ID_ADDON_MENU:
            switch (menuParams->menuItemRef.itemIndex) {
                case 1:
                    CountNumberOfWalls ();
                    break;
            }
            break;
    }
    return NoError;
}

The CountNumberOfWalls function can be implemented like in the example below.

static void CountNumberOfWalls ()
{
    GS::Array<API_Guid> wallGuids;
    GSErrCode err = ACAPI_Element_GetElemList (API_WallID, &wallGuids);
    if (err != NoError) {
        return;
    }
 
    USize wallCount = wallGuids.GetSize ();
    DG::InformationAlert (GS::ValueToUniString (wallCount), "", "OK");
}

It accesses the list of walls from the current plan, and shows the length of the array in a dialog.

If everything is ok, you should see something like this:

Releasing Add-Ons 

To release your Add-On and make it work with all Archicad versions, you have to register as an Archicad developer, and get an MDID for your Add-On. MDID is a unique identifier which identifies the Add-On. Please note that Archicad can’t load two different Add-Ons with the same MDID, so you have to set up different MDIDs for each of your Add-Ons.

Here you can find detailed instructions on registering an MDID.

Resources

This tutorial covered only the basics, but there are much more.