GGame plugins

By Gary Arndt


********************************************************************************
Introduction
********************************************************************************

There are 3 purposes for this install:
1: To provide this core plugins manual for a player to reference regarding installing a plugin required for a given GGame scenario
2: To provide this core plugins manual for a scenario designer to reference regarding use of a plugin
3: To provide the ping plugin, which can be useful for testing purposes

As noted, this package provides a home for this core plugins manual.  This may well be referenced by other plugin packages since it provides shared instructions on a variety of topics.

A plugin is, in general terms, a way of adding a new part of a program to do new things that aren't part of the original program.  This can allow doing new things like accessing a 3rd party scripting language to help in implementing some of a scenario or even implementing some of a scenario directly.  If you are not a scenario designer and don't know what that means, don't worry, it isn't something the players need to understand.

A player normally only needs to read only one section, "Finishing the install".

Most of the remaining sections are intended mainly for scenario designers.

A "Credit" section addresses that issue.


********************************************************************************
Finishing the install
********************************************************************************

If a scenario designer includes a plugin with their install package, they may have different, specific install instructions.  If not, use the following instructions to complete the plugin install.

The initial steps are explained in the main install document in order to put the plugin directory in place.  This has likely already been done by the time you have access to this manual.

After the package containing the plugin has been installed, copy the contents of the plugins subdirectory to the main game install's corresponding plugins subdirectory (create this if it does not yet exist).  Note that the plugins subdirectory is just a suggested location; the plugin can actually be located anywhere specified by the scenario in question.

For example, if this install package contains GGame2-plugins\plugins\plugin-ping.dll, then to finish installing it copy plugin-ping.dll to GGame2\plugins.

Or for another example, if some 3rd party install package contains a "3rdPartyGGame2PI\plugins\3rdPartyPI" subdirectory, then copy the entire "3rdPartyPI" subdirectory to GGame2\plugins (that name being a fictional example, of course).

For those that need it, these are specific steps that can be used to accomplish this:
- Open a file explorer if one is not already open
- Navigate to the plugins install directory
- Navigate into the "plugins" subdirectory (of this plugins install directory)
- Select and copy ALL of the contents of THAT directory.  This may be 1 or more files and/or subdirectories.  Be careful to copy only what is in THAT plugins directory; do NOT navigate into any addition subdirectory/subdirectories and copy only the content from it/them; any subdirectories are needed or else the scenario(s) in questions will not point to the proper location.
- Navigate to the main game install directory
- If it does not already exist, create a "plugins" subdirectory (of the main game directory)
- Navigate into this "plugins" subdirectory
- Select to paste all of the content that was previously selected


********************************************************************************
Using an existing plugin
********************************************************************************

A player does not need to read this section; it is intended for those who want to use a plugin in their scenario design.

As noted above, a plugin provides additional functionality for a scenario designer.  To use a given plugin, your scenario will need to load it using a specific setting in the scenario[ID].dat file.

It is very important to remember that this file is plain text and will NOT work properly if you save it with another format or the editor in question modifies the name (for example, some may try to add a ".txt" to the end).  It is probably best to use a text editor (such as Notepad on Windows) and avoid using a word processor program.

The setting is:

PLUGIN: [filename]

The filename may include a path.  This may be a relative path to the main game exe and it is strongly suggested to do so rather than using an absolute path.  It is also strongly suggested that this be a relative path to the plugins subdirectory.

For example, if the game is installed at "C:\Games\GGame2" then and you have a plugin called "SomeScriptingLanguage.dll" (that name being a fictional example, of course) then the setting could be:
PLUGIN: plugins\SomeScriptingLanguage.dll

If you have a plugin that requires more than one file, you may want to nest that into a subdirectory.

For example "plugins\SomeScriptingLanguage\SomeScriptingLanguage.dll" that may also contain a "scripts" subdirectory so you end up with something like:

C:\Games\GGame2\plugins\SomeScriptingLanguage\SomeScriptingLanguage.dll
C:\Games\GGame2\plugins\SomeScriptingLanguage\scripts
C:\Games\GGame2\plugins\SomeScriptingLanguage\scripts\init.abc
C:\Games\GGame2\plugins\SomeScriptingLanguage\scripts\script1.abc
C:\Games\GGame2\plugins\SomeScriptingLanguage\scripts\script2.abc
Etc.

Normally, a given plugin command is referenced via the PICMD standard scripting command (which stands for "plugin command").  While the standard scripting mechanism is outside the scope of this document, the details of this particular command are as follows:

PICMD [command] [[arg1] [... [argN]]]

For example "PICMD ppiPing" will issue the "ppiPing" command to the ping plugin (which will only work if the ping plugin is properly installed).

Note that the PLUGIN configuration setting may be used more than once in order to load multiple plugins.

The order in which these plugins are loaded also determines a hierarchy of which one processes the given command.  The order can be important for efficiency and also for if a command name happens to overlap.  It is therefore suggested that you add a short prefix to command names such as how the commands in the ping plugin typically use "ppi".  That said, note that in some cases it is actually better not to do so (such as the commands for a scripting language).

There is another scenario[ID].dat setting that can be very important for some plugins:

PLUGINCMD: [command] [[arg1] [... [argN]]]

This allows running a plugin command AFTER the plugin has been loaded.  Note that this is intended for purposes of initializations, NOT as the primary means of using the plugin such as provided by the PICMD standard scripting command.

For example, if you have already loaded "SomeScriptingLanguage.dll", then you may want to use the following command to initialize it such as "plugins\SomeScriptingLanguage\scripts\init.abc".


********************************************************************************
Using the plugin console
********************************************************************************

A player does not normally need to read this section; it is really intended for those who want to use a plugin in their scenario design.

As noted in the standard game manual, the game contains a set of development/cheat commands.  One of these is a console (an interactive prompt) to issue commands to plugins.  The purpose of this is for testing.

Note that the first few steps listed below are to install the plugin in question.  Without any plugin, an attempt to start the console will result in an error.  With only plugins other than the one in question, the results will not match what is expected.

Anyway, these are the steps to use this tool:
- First of all, make sure the files are installed for the plugin in question (as per the instructions in an earlier section)
- Secondly, make sure it is referenced by the scenario[ID].dat file, as per the above instructions for whichever scenario you decide to test it with.  It is suggested that you back up this file before modifying it (perhaps copy it to "scenario[ID]-orig.dat".  Do not forget that it MUST be saved as a text file (as mentioned in an earlier section).
- Enable development/cheat mode as per the instructions in the main game manual (basically, add "CHEAT: 1" to the scenario[ID].dat file).
- Next start the game and start the respective scenario
- Go to the the development/cheat menu as per the instructions in the main game manual (basically, the Control-F12 keystroke)
- Select the option for the plugin console (the F1 menu will display the option, but currently it is the '-' key)
- Enter textual commands that are processed by the plugin in question.  These should be detailed for each plugin in question (for example, those for the included ping plugin are detailed in the section named "The ping plugin").
- When you are done, press the enter key to exit the console then you can quit the game normally

Alternatively, you can use the script console (or an actual script) with the PICMD command (this script command is how plugin commands are normally accessed for actual use in a scenario).  The script console is accessed almost the same way as the plugin console (the F1 menu will display the option, but currently it is the '=' key) and behaves somewhat similarly.  Note that other than via the PICMD command, it processes ONLY built-in script commands, NOT plugin commands.


********************************************************************************
The ping plugin
********************************************************************************

A player does not normally need to read this section; it is really intended for those who want to use a plugin in their scenario design.

This package includes the ping plugin.  This is not something that a player will often find useful; it is mainly only useful for plugin-related development.  The only time a player may want to try it is if they are having trouble installing another plugin and want to use this as troubleshooting step (perhaps to make sure they understand how this most simple plugin should be installed as a baseline).

This plugin is intended for two purposes:
1: To test the plugin functionality including that you understand how to install and interact with plugins
2: To serve as an example

To use the ping plugin, follow the steps listed above to use the plugin console.

The available ping plugin commands consist of the following:
ppiPing: This command will return back a string of ID info from the plugin
ppiDPing: This command will display a dialog box of ID info from the plugin
piDPing: This command will do the same as ppiDPing except multiple plugins may respond (note the prefix is "pi" rather than "ppi")

The prefix "ppi" means "ping plugin".  The prefix "pi" means "plugin".


********************************************************************************
GGame API
********************************************************************************

A player does not need to read this section; it is intended for those who want to use a plugin in their scenario design.

Some plugins use the GGame API.  This consists of only several commands, but some offer a vast number of nested commands within them.


API test

This displays a simple message for testing purposes.


API message

This displays the given message.  While this is already possible using a standard API command or script command, this is more direct, therefore more efficient, and therefore potentially faster.  Note that it accepts a parameter for "no new line" (a new line is the default).


Standard API command

This provides access to the standard API commands.  Note that some of these may return a value.

Whlie the details of the specific command are provided here, it may also be helpful to refer to sample files for any plugin that uses them for examples.

These currently include:
Message [message]: Display the given text
Input: Prompt for and return a string
InputKey: Wait for, capture, and return a keystroke
RandomInt [min] [max]: Return an int in the given range
GetTag: Return the most recent standard scripting tag ID
GetScriptState: Return the most recent standard scripting state tag
GetWorkDir: Return the work directory string
GetDataDir: Return the data directory string
GetFlag [ID]: Return the value of the given flag
GetDark: Return the current darkness state
GetItemCount [ID]: Return the quantity of the given item


API script command access

This provides access to the built-in scripting commands.  Refer to the main game manual for details.  Note that these do not return a value, but the results of those commands often include setting a TAG ID or a script state which means that the GetTag or GetScriptState commands could then be used.


********************************************************************************
Further details
********************************************************************************

A player does not need to read this section; it is intended for those who want to use a plugin in their scenario design.


Other plugins

The ping plugin is useful for the purposes mentioned above but does not provide anything that is useful in the game itself.  That said, I have already designed other plugins which are organized into separate packages rather than being included here.  Those other packages should include any additional details specific to the given plugin, but may well make references back to this core plugins manual.


GGame scripting vs. plugins

Almost everything needed for very complex scenarios should be available in the built-in custom scripting language in the main GGame2 program.  However, the plugin system was implemented since it allows for even more flexibility.

For example, the built-in scripting language is intentionally kept simple, such as using line ID's rather than standard conditionals, having no variables nor functions, etc..  While there are usually ways to avoid these limitations, other scripting languages may be better in some cases.

Or another approach is that since the plugin functionality is accessed through the PICMD script command, it can be used to basically add scripting functionality sort of like a new script command, although of course there are limits due to what can be accessed in the GGame API.  Also, the "new command" must still be accessed through the PICMD command.

Further, a plugin could even be used to code the scenario details directly (hardwired them into the compiled plugin binary).


The startup file

There may be a startup exe file included with a given plugin.  The ping plugin is one of these.  This file is not actually needed or used by the game when the plugin is being used.  The purpose is typically only to serve as a very basic test to make sure the plugin is working correctly and also to provide some version information.  For example, if you run "startup-ping.exe" and it is working correctly, it will display a message box with some version information.


Install location

A default install location is suggested for both scenario designers and players because that means multiple scenarios would be consistent in referencing the same location.  If a given shared plugin was expected to be placed in a different location, a player may have to manually change the scenario[ID].dat of the scenario in question to point to that different location or even place a duplicate copy in that different location.

For example, if two different scenarios both use "SomeScriptingLanguage.dll", then expecting it to be in some default location like "plugins\SomeScriptingLanguage\SomeScriptingLanguage.dll" would mean both can set the scenario[ID].dat file to point to that same location and players would not need to alter that file and could follow standard install instructions for the SomeScriptingLanguage plugin.  But if one expected it to be at "DifferentPlugInLocation\SomeScriptingLanguage.dll" and another at "YetAnotherPlugInLocation\SomeScriptingLanguage.dll" then this would an inconsistency that would require either modifying one or the other scenario's scenario[ID].dat file to point to just one of the two locations or else having duplicate copies of the plugin in each of those locations.


Custom plugin design

This is a subject that I may consider addressing in more detail in a future version of this manual.  But basically, this IS possible using the API that the game program provides (as described above).

Briefly:
- The plugin must be a DLL that exports "int APIPlugInMain()" and "char* APIPlugInCommand(char* sCommand)".  The former must deal with any initializations.  The later must accept any commands as strings and return the results as a string.
- The main application (the game) provides the functions "void APIAppTest()", "APIMessage(char* sMessage, BYTE bNewLine)", "APICommand(char* sCommand, int nArgC, char** psArgV)", and "APIScriptCommand(char* sCommand, int nArgC, char** psArgV)"


********************************************************************************
Credit
********************************************************************************

I designed and implemented everything described here myself, including the plugin mechanism itself and the ping plugin.

Other plugins may have additional credit involved.  For example, if another plugin includes a 3rd party scripting languages, then the documentation should include the credit for that language and the associated implementation of that language.
