A DI-Guy plugin is a dynamic library that adds additional functionality to DI-Guy Scenario or to an application using the standard DI-Guy SDK libraries.

Plugins can be loaded in three ways:

specified on DI-Guy Scenario command line using "+plugin xyz" argument
added to a scenario in DI-Guy Scenario via the Scenario Objects/Specialized Objects/Plugins page
by calling diguyApp::load_plugin()

Once a plugin has successfully been loaded, functions from the plugin will be called at specific times during scenario execution.

Plugins can be unloaded in four ways:

DI-Guy Scenario is shut down
if part of a scenario, and the plugin is removed from the scenario by pressing Unload on the Plugins page
if part of a scenario, "Unload on Scenario Close" on the Plugins page is checked, and a new scenario is loaded
by calling diguyApp::unload_plugin()

Once a plugin has successfully been loaded, functions from the plugin will be called at specific times during scenario execution.

Following is a list of the functions that DI-Guy will look for in the library. Note that a plugin does not need to implement all of these functions; if a function is missing the plugin will quietly skip it. Only the diguy_version() function must be implemented.

Note that new functions may be added to plugins in the future.

void diguy_version(int* version_major, int* version_minor, int* version_point)

This function is called once, when the plugin is being loaded. The function should return, via the passed int pointers, the DI-Guy version number as defined in diguy_constants.h. DI-Guy will compare these numbers against the current version number to make sure the plugin is compatible with the current version.

C++ Example:

__declspec(dllexport) void
diguy_version(int* version_major, int* version_minor, int* version_point)
{
    *version_major = DIGUY_VERSION_MAJOR;
    *version_minor = DIGUY_VERSION_MINOR;
    *version_point = DIGUY_VERSION_POINT;
}

void initialize_plugin(diguyApp* app)

This function is called once, when the plugin is being loaded.

If the plugin is being loaded because it was specified on the DI-Guy Scenario command line, this function is called as DI-Guy Scenario is initializing, before the first scenario is created.

If the plugin is part of a scenario (is shown in the DI-Guy Scenario Scenario Objects/Specialized Objects/Plugins page), the call will happen when the scenario is loaded.

If the plugin is being loaded because of a load_plugin() call, this function is called during the load_plugin() call.

void deinitialize_plugin(diguyApp* app)

This function is called once, when the plugin is being unloaded. The call will happen while DI-Guy Scenario is shutting down, or during the unload_plugin() call if the plugin is being explicitly unloaded by function call.

void initialize(diguyScenario* s)

This function is called when the passed scenario first becomes aware of the plugin. This will be when the scenario is created if the plugin has already been loaded, or during the load_plugin() call if the plugin is loaded after the scenario was created.

void deinitialize(diguyScenario* s)

This function is called when the scenario is deleted, or when unload_plugin() is called.

void pre_update(diguyScenario* s)

This function is called during the diguyScenario::update() call, before anything else is changed due to the update. (i.e., characters will not have moved yet, etc.)

void post_update(diguyScenario* s)

This function is called during the diguyScenario::update() call, after everything else is changed due to the update. (i.e., characters will have moved, etc.)

void pre_draw(diguyScenario* s)

This function is called during the diguyScenario::draw() call, before anything else is drawn.

void post_draw(diguyScenario* s)

This function is called during the diguyScenario::draw() call, after everything else is drawn.

void reset(diguyScenario* s)

This function is called when the scenario is reset, either due to pressing the Reset button in DI-Guy Scenario, or calling the diguyScenario::reset() function. The scenario is also implicitly reset when a .dss file is loaded.

diguyPluginMouseCursor get_mouse_cursor(diguyScenario* s)

This function should return which type of cursor should be used when the mouse is in a 3D view. See the documentation for diguyPluginMouseCursor for which values are available. If this function is not exported from the plugin, the default cursor DIGUY_PLUGIN_MOUSE_CURSOR_LEFT_ARROW will be used.

void mouse_press(diguyScenario* s, diguyPluginMouseEvent* mouse_event)

This function is called on an initial press of any mouse button in a 3D view. Use the query functions of the diguyPluginMouseEvent object to retrieve which view the press occurred in and the x and y screen coordinates of the press.

void mouse_drag(diguyScenario* s, diguyPluginMouseEvent* mouse_event)

This function is called when the mouse is moved in a 3D while one or more buttons are pressed.

void mouse_release(diguyScenario* s, diguyPluginMouseEvent* mouse_event)

This function is called when any mouse button is released in a 3D view.

void mouse_move(diguyScenario* s, diguyPluginMouseEvent* mouse_event)

This function is called when the mouse is moved in a 3D while no buttons are pressed.

int key_press(diguyScenario* s, diguyPluginKeyboardEvent* keyboard_event)

This function is called on an initial press of any key in a 3D view. Use the query functions of the diguyPluginKeyboardEvent object to retrieve which view the press occurred in and the code of the key. The code can be a standard ASCII value, or one of the DIGUY_SPECIAL_KEY_* values defined in diguy_constants.h. Return 1 to indicate that the key was handled and that the default key handler should not be called. Return 0 for the default key handler to be called.

int key_release(diguyScenario* s, diguyPluginKeyboardEvent* keyboard_event)

The same as key_press(), but called when the key is released.

void save_review_data(diguyScenario* s, const char* filename)

This function is called when after-action review data for the scenario is saved by a call to diguyScenario::save_review_data().

void load_review_data(diguyScenario* s, const char* filename)

This function is called when after-action review data for the scenario is loaded by a call to diguyScenario::load().

Windows Specific:

Plugin functions should be declared with __declspec(dllexport) to make sure that the symbols are properly exported from the DLL.

The LIBC version that the plugin uses (MD, MDd, MT, or MTd) must be the same as that of DI-Guy Scenario or the DI-Guy libraries used. If this does not happen conflicting versions of the DI-Guy DLLs will be loaded and the program will be unstable.