Back to plugin tutorials

Anatomy of an AC3D plugin

NOTE: If you are using a command line compiler, please see the make files that ship with the AC3D SDK for tips on getting started.

An AC3D plugin is a C/C++ dynamic library with a .p extension.

Aside from the ac_plugin.h file included with the SDK, you only need to add a single source file of your own for a compilable AC3D plugin.

There are four functions that you will create for each plugin

AC3DPluginInit Performs globals initialization, but usually just adds a menu item to acces your plugin to the AC3D menu.
AC3DPluginExit This function seems like it would be called when the plugin is unloaded, but that is not the case. As far as I can see, this function is reserved for future use.
AC3DPluginAbout Returns a text string to be displayed when the user clicks the "Help -> About plugins..." menu item from AC3D.
AC3DPluginInfo Returns a text string to be displayed when the user selects your plugin from the "Help -> About plugins..." dialog box.

Aside from these four functions, in a standard plugin, you will define a static function of your own.

Creating an AC3D plugin template

The following code snippet defines n AC3D plugin template. This plugin was written for C++. Within the code, you will find comments that explain each section of the source code.

NOTE: This tutorial was done on a Windows platform, as the "#define WINDOWS" indicates in the below code snippet. It is worthwhile to note that Mac compilations require that DMAC be defined, and linux requires DLINUX.
// If _WINDOWS is defined, we are probably compiling from a MSVC
// environment.  Define WINDOWS to ensure ac_plugin.h picks up
// the right function prototypes.
#ifdef _WINDOWS
#ifndef WINDOWS
#define WINDOWS

// The SDK header
#include "ac_plugin.h"

// This is our plugin's main function.
// Your custom code will go here.
static void my_plugin()
// The plugin init function
AC3D_PLUGIN_FUNC int AC3DPluginInit( AC3DPluginInitData *d )
   // We only want this code to run once.  I'm not sure that
   // this check is necessary, but it does prevent multiple
   // loads in case AC3D loads/unloads the plugin in future
   // releases.  We only want this snippet to execute once, since
   // it adds items to the AC3D menu.
   static bool firstTime = true;
   if( firstTime )
      // Add a new command that AC3D will use to call our function.
      // "my_command" is the internal name of the command that AC3D
      //    will call from the GUI to call our plugin code.
      //    Put what you want here, but try to be careful what you
      //    name the plugin; i.e., you don't want to give it the
      //    same name as an AC3D internal command.  I normally use
      //    my initials here to prevent overlap (i.e., "ddh_my_command")
      // my_plugin is a pointer to our static void my_plugin()
      //    function defined earlier.
      ac_add_command( "my_command", my_plugin );
      // Add a new menu item for our plugin under the "Tools" menu.
      // "Menu item text" is the text that will appear on the AC3D
      //    menu.  Put whatever you want here.
      // "ac3d my_command" is the menu command that will be invoked.
      //    "ac3d" is an internal AC3D command for invoking another
      //    internal command.  "my_command" is the name of the
      //    command we created in the last step ac_add_command()
      // "Menu item statusbar text" is the text that will appear
      //    in the AC3D statusbar when you mouse-over the menu item.
      ac_add_tools_menu_item( "Menu item text",
                              "ac3d my_command",
                              "Menu item statusbar text" );
      // Prevents this snippet from being run more than once,
      // in the event this function is ever called multiple times.
      firstTime = false;
   // Return 0 on success
   return 0;
// Not sure that this function is ever run, or even needed,
// but is included for future versions at the very least.
AC3D_PLUGIN_FUNC int AC3DPluginExit()
   return 0;
// Return the text to be shown in the Help -> About plugins...
// dialog.  Be sure to put in a version number and your name.
AC3D_PLUGIN_FUNC char *AC3DPluginAbout()
   return( "Name of my plugin - version 1.0 - My Name" );
// Return the text to be shown in the description field when
// a user clicks your plugin text in the Help -> About plugins...
// dialog.
AC3D_PLUGIN_FUNC char *AC3DPluginInfo()
   return( "Detailed description of my plugin." );


Back to plugin tutorials

All content Copyright © 2006 Dennis Hawthorne, except where explicitly noted
supercoldmilk © 2006 Dennis Hawthorne