Since 1.99.25, PCC2 supports plugins. Plugins are a standardized way to get scripts (and resources) into PCC2 without having to manually edit files as if it were 1992.
A plugin is defined by a *.c2p file. This file contains information about the plugin and links to the actual files that make up the plugin. It is a regular ".ini" file that supports the following keywords:
- Name = <short name of plugin>
This is displayed in menus as the plugin title. - Description = <long description>
A longer description. You can use multiple Description lines to produce multiple paragraphs. - Provides = <feature>, <feature>
Requires = <feature>, <feature>
Dependencies, see below. - File = <file name>
A regular file that comes with the plugin. - ScriptFile = <file name>
A script file that comes with the plugin. The file is automatically loaded as if by Load. - ResourceFile = <resource file>
A resource (*.res) file that comes with the plugin. The file is automatically loaded as if it were listed at the end of cc-res.cfg. - HelpFile = <help file>
A help (*.xml) file that comes with the plugin. Help pages from that file are made available to the UI.Help command. - <type>File = <file name>
For upward-compatibility, PCC2 also accepts file types it doesn't understand, and just installs them normally. - Exec = <script command>
A script command that is executed when the plugin is loaded.
Order of Script/Resource/Exec is significant, i.e. an Exec command can rely on a previous Script to be loaded.
For installation, files from File/Script/Resource must reside in the same directory as the *.c2p file. When a file myplugin.c2p file is installed, it is copied into the directory ~/.pcc2/plugins/, and the referenced files are copied to ~/.pcc2/plugins/myplugin/ (different paths on Windows).
The name of the plugin definition file serves as the plugin identifier in technical contexts (scripts, command line) see System.Plugin.
The Script and Exec commands will be executed within the plugin's context, and have access to the plugin properties.
PlayVCR will only load Resource files.
When uninstalling or updating a plugin, PCC2 will unload resource files provided by the plugin, but it will not unload scripts.
Dependencies
PCC2 has a rudimentary dependency management system. Plugins can provide and require features. You cannot install a plugin if a dependency is missing, and you cannot remove a plugin if another one relies on it.
Each feature is a word optionally followed by a version number, for example, "Coyote" or "Acme 1.0". Case is not significant. A plugin that requires a particular version number will also accept higher version numbers.
Default features:
- "PCC 1.99.25" (current PCC2 version, whichever is current)
- each plugin definition file, say, myplugin.c2p, provides the plugin identifier ("MYPLUGIN") as a feature
Zipped Plugins
For simplicity, PCC2 also allows compressing all files of a plugin (including the *.c2p file) into a single zip file. To identify these files as plugins, we use the file extension .c2z (but normal .zip is accepted as well). This is the standard way of distributing plugins over the web.
Unpackaged Plugins
The plugin installer and the c2plugin tool will also accept regular script (*.q) and resource (*.res) files for installation. They will then internally generate a plugin description. This is useful for testing.
When you're giving away a plugin, it is strongly recommended to add a *.c2p file, and ideally package it up as a *.c2z.
