Build your first plugin.

Start with Hello

Plugins are separate AmigaOS programs. They send text, values and events through Exec message ports; NovaDock draws the tile.

Download Plugin SDK SDK checksum Browse SDK on GitHub →

The SDK is also part of the repository under plugin-sdk/README.md. These tagged links become available when the 0.2 release is published.

1. Build the Hello example

The SDK includes a complete example, protocol headers, client helpers and a Makefile. Set up vbcc with an AmigaOS m68k target and compatible NDK, unpack the SDK, then run make. Or compile directly:

vc -O -Iinclude -o Hello examples/hello.c src/nd_client.c src/nd_option_runtime.c

2. Describe your plugin

Keep the program and its matching .ndplugin manifest together. Choose your own unique ID and program name. This is the SDK example:

NOVADOCK_ID=HELLO
NOVADOCK_NAME=Hello
NOVADOCK_VERSION=1.0
NOVADOCK_AUTHOR=Your Name
NOVADOCK_DESCRIPTION=Shows a greeting and reacts to clicks.
NOVADOCK_LICENSE=MIT
NOVADOCK_FEATURES=meter,click,badge
NOVADOCK_PROGRAM=Hello
NOVADOCK_VIEW=METER
NOVADOCK_ABI=1
NOVADOCK_OPTION=GREETING|Greeting|TEXT||HELLO AMIGA
NOVADOCK_OPTION=POLL_TICKS|Refresh ticks|UINT|10,500|50

3. Update the tile safely

Use the supplied client helper, honour ND_EVENT_QUIT, and wait between updates with nd_client_delay_ticks(). Exchanges have a fifteen-second deadline. ABI 1 covers basic tiles; later versions add graphs, media controls and badges. The current host supports ABI 5.

Give your plugin a settings window

Right-click the dock tile and choose Edit settings.... NovaDockPrefs creates that window from the manifest's NOVADOCK_OPTION fields, so ordinary options need no separate settings application.

NOVADOCK_OPTION=GREETING|Greeting|TEXT||HELLO AMIGA
NOVADOCK_OPTION=POLL_TICKS|Refresh ticks|UINT|10,500|50
NOVADOCK_OPTION=SHOW_LABEL|Show label|BOOL||YES
NOVADOCK_OPTION=STYLE|Style|CHOICE|COMPACT,FULL|COMPACT
NOVADOCK_OPTION=PROGRAM|Program|FILE||SYS:Utilities/MultiView

The five fields are key | label | type | choices or range | default. Use TEXT for text, UINT for bounded numbers, BOOL for toggles, CHOICE for cycles and FILE for a path with a file picker. A manifest supports up to 12 settings.

NovaDock opens NovaDockPrefs PAGE=PLUGIN PLUGIN=<id> FOCUSED=1 for the selected tile. Use the actual ID passed in argv[1], including any instance suffix, when reading options. The editor stores values as OPTION.<ID>.<KEY> in the shared novadock.cfg; plugins should not replace that file themselves.

Read values at startup with nd_plugin_option_strings(). Reread them when an update returns ND_EVENT_SETTINGS; the SDK Hello example already does this:

if (event & ND_EVENT_QUIT) break;
if (event & ND_EVENT_SETTINGS)
    read_settings(argv[1], greeting, sizeof(greeting), &poll);

Use applies settings for the session; Save also keeps them permanently. The shared editor writes the configuration and notifies the plugin. ND_EVENT_SETTINGS is a change notification, not an instruction to open your own window.

After changing a schema, remove its dock tiles and re-import the updated manifest. The SDK includes PLUGIN_SDK_SETTINGS.md with the full reader, testing steps and custom-UI guidance. Read it on GitHub →

A custom window can be opened by the plugin's own actions, but the current SDK cannot replace the right-click settings entry with an external preferences app.

Keep your plugin responsive

Initialise with nd_client_init(), read options, send updates and handle the returned events. Handle quit first, then clicks and changed settings. Use nd_client_wait(&client, nd_client_delay_ticks(&client, poll)) between updates so the process sleeps and wakes for events. Call nd_client_close() before exiting.

If an action opens your own Intuition or GadTools window, keep its event handling responsive while the plugin continues to process dock updates and quit requests. Long-running work belongs outside the dock update path.

4. Package and test

Hello-1.0/
  README.txt
  Plugins/
    Hello
    Hello.ndplugin

Include the author, licence, version, dependencies and install instructions. In Preferences > Plugins, choose Import, review the preview, then Add to dock. Test on the AmigaOS configurations you support.

Full reference: docs/PLUGIN_SDK_QUICKSTART.md, docs/PLUGIN_API.md and docs/PLUGIN_SETTINGS.md in the source download.