
/--- QRun32 - the ultimate launcher for Quake ---\
|                  Version 1.30                  |
|                                                |
|            Plug-In SDK information             |
\------------------------------------------------/


\--------------\
 > SDK-Contents >
/--------------/

This directory should contain the following files:

  PLUGINS.TXT       - this text
  VERSIONS.TXT      - version-history for the SDKs
  delp_sdk          - DIR: the plug-in SDK for Borland Delphi 2
  ctf4_src          - DIR: the source-code for the Capture the Flag plug-in

The "delp_sdk" directory contains:

  QRUNAPI.PAS       - important unit for communicating with QRun32
  PLUGIN.DPR        - common plug-in project
  PLUGIN.RES        - common plug-in resource file. Includes the Version Info
  PLGINDLG.PAS      - common plug-in dialog-unit
  PLGINDLG.DFM      - common plug-in dialog form-definitions
  VERSION.RES       - common version resource

The "ctf4_src" directory contains:

  QRUNAPI.PAS          - important unit for communicating with QRun32
  CTF4.DPR             - the Delphi project file
  CTF4.RES             - resource containing the VersionInfo
  MAIN.PAS             - main dialog
  MAIN.DFM             - main dialog form-definitions
  CTF4HELPERS.PAS      - some helper-functions and typedefs
  REGISTRYHANDLING.PAS - functions that deal with registry-manipulation
  ICON.RES             - the CTF-icons (created by me !)
  VERSIONS.TXT         - Version-history for the CTF plug-in


\--------------\
 > Requirements >
/--------------/

To develop plug-ins for QRun32 you need:

 - Microsoft Windows95
 - Borland Delphi 2.0 or higher (Delphi 3 recommended)
 - some basic programming knowledge in Delphi
 - some knowledge of how QRun32 works


\----------------\
 > Let's start... >
/----------------/

OK, you're now ready to code plug-ins. The most important thing when you develop 
a QRun32 plug-in is the "QRUNAPI.PAS" unit. It contains necessary constants and 
functions that allow you plug-in to communicate with QRun32. So add it to every 
plug-in project !

OK, what's a plug-in at all ? A QRun32 plug-in is an extension to the options 
that can be modified by QRun32. There are a lot of patches, that provide lots of 
new options, a launcher normally cannot handle. The solution are totally free 
programmable plug-ins.

The final "effect" a plug-in is for, is to provide an extension to the 
commandline you normally start Quake with. So in the end all a plug-in does is 
to return a null-terminated string to some commandline parameters. That's all.


\---------\
 > Exports >
/---------/

As you have noticed (hopefully), a plug-in is nothing more than a Win32-DLL. So 
it has to export several functions to be a working plug-in. These exports are 
the following:

<PI_IsPlugIn>
This function just returns a boolean "TRUE". QRun32 then recognizes the DLL as a 
valid plug-in.

<PI_GetPlugInAPIVersion>
This function returns a DWORD representing the used API-version.

<PI_SetInfoFn>
This function is mainly internal. It sets the "QRUN_GetInfo" function to an 
internal function of QRun32, so your plug-in can talk DIRECTLY to QRun32. You 
may add some initialization in here.

<PI_GetDescription>
This function returns a null-terminated string containing the description of the 
plug-in.

<PI_GetIcon>
This function should return a standard Windows handle to an icon used for 
displaying the plug-in. You get a var called "Size" that tells you, what
type (size) of Icon QRun32 wants to have.

<PI_ExchangeSettings>
When the plug-in is initialized, that means when the user selects your plugin, 
this function is called. This one is called only ONCE to initialize your plugin.

<PI_Execute>
Every time, a user presses F12 or clicks on the plug-in icon at the upper right, 
this function is called. It returns "TRUE" if the user selects OK and "FALSE" if 
the user selects "CANCEL" in your plugin-dialog.

<PI_QueryAllowList>
Internal function, returning a pointer to a "TAllowList"-record.

<PI_GetCommandLineParams>
This function is called, when Quake is executed at last. It should return a 
null-terminated string containing all commandline-parameters your plug-in 
creates.

<PI_SaveSettings>
This function is called, when QRun32 wants your plug-in to save its settings to 
the Windows-registry.

<PI_RestoreSettings>
This function is called, when QRun32 wants your plug-in to restore ist settings 
from the Windows-registry.


\------------------\
 > the QRUNAPI unit >
/------------------/


 Functions:
~~~~~~~~~~~~

function StrNotEmpty (S: string): Boolean;
    This function checks, if a string isn't empty and not "strNone". "strNone"
    is defined as "<none>", which is used by QRun32 quite often.

function QRUN_GetInfo (What: Word): Pointer;
    This function is used to gather information from QRun32. The param "What"
    tells QRun32, which information is wanted or which action should be
    performed. You may specify the following:

    GI_SELECTMAP      - lets the user select a user-created map
    GI_SELECTPATCH    - lets the user select a patch
    GI_SELECTDEMO     - lets the user select a demo
    GI_SELECTPATCHDEMO- lets the user select a demo in the patch-dir
    GI_GETRELPATCHDIR - gets the patch-dir relative to the Quake-dir

    This function returns a pointer to the information you queried. For now this
    will be a PChar, but this may vary in the future, so it's in general a
    pointer.


 Records:
~~~~~~~~~~

TAllowList: This record contains some boolean variables, that make special
            options invisible in QRun32. For example if you don't want the user
            to be able to select maps with your plug-in, set the "alMap" -
            member to "FALSE" (or zero for non-Delphi languages) Please look at
            "QRUNAPI.PAS" for more details.

TSettings: This record contains nearly ALL options, that can be changed by
           QRun32. The record consists of several strings (pointers to null-
           terminated arrays of chars), Booleans, Bytes and Words. Please refer
           to "QRUNAPI.PAS" for more information. You get a pointer to such a
           record, whenever your plug-in is executed (that means PI_Execute is
           called), representing the current QRun32-settings. You may use this
           record to initialize your plug-in and you may modify this record to
           what you want. QRun32 evaluates this record, when your plug-in
           returns to QRun32. The "PI_ExchangeSettings"-function also gets a
           pointer to such a record. "PI_ExchangeSettings" is executed only once
           when a user selects a plug-in from the plug-in listview or the plug-
           in context-menu.


 Constants:
~~~~~~~~~~~~

QRUNAPI.PAS contains a lot of constants for use with the TSettings-record as 
well as for use with the QRUN_GetInfo function. Please look at the unit for a 
complete reference.


\-------------------------------\
 > So what are you waiting for ? >
/-------------------------------/

Just go ahead and take a closer look at the "Capture the Flag" plug-in 
sourcecode in "CTFsrc". I'm sure, you'll find some interesting techniques 
in there. Feel free to copy and/or re-use them for your own purposes.

If you are ready to develop own plug-ins, just use the project "PLUGIN.DPR"
in the "Delp_SDK"-directory for a basic frame of a plug-in. Do your
modifications, compile the whole thing and rename the compiled DLL to another
name than "PLUGIN.DLL". Finished.

NOTE: If you find a way to edit the "VERSION.RES" Win32 version-resource, please 
do so ! Otherwise feel free to remove line 12 ({$R VERSION.RES}) in PLUGIN.DPR, 
so that the silly, empty version-information is not compiled into your plug-in.
Delphi 3 for example allows you to specify your own Version-resource. You MUST
remove the above mentioned line, otherwise Delphi can not compile your plugin.


\---------------------\
 > Pleeeeeeeeeeeeeze ! >
/---------------------/

If you have any problems, try to specify your problem and send me an eMail 
(Oli@slop.prima.ruhr.de). PLEASE do not ask questions like "How do I create a 
plug-in" if you have never ever programmed before. Also browse through the 
"CTFsrc"-dir for hints and clues.

If you develop a plug-in, PLEASE drop me an eMail (Oli@slop.prima.ruhr.de) and 
tell me, where I can download your work.

If you feel safe enough to convert the SDK to a Visual C++ project, PLEASE tell 
me ! It would be a great thing to include a MSVC_SDK.ZIP in the next version of 
QRun32.... :)))

If you like this piece of software, it would be kind to send me some bucks, so 
that I can develop faster and more efficient. :) (see README.TXT for details)


\----------------\
 > Legal stuff.., >
/----------------/

This program, its documentation and the SDK are copyrighted (c)1997 by 
elite!developments. All rights reserved.  QRun32 is offered with no warranty or 
guarantee so use it at your own risk.  By using this software you, the user, 
agree to take full responsibility for anything that happens.  I am in no way 
responsible for anything that may happen. You may redistribute QRun32 freely as 
long as all the files listed above are included and have not been modified and 
no charge or fee is collected (normal BBS/online service fees excluded) for the 
service. You may not charge money for plug-ins you develop. (remember: this is 
FREEWARE!) Anyone wishing to include this program in any type of anthology or 
CD-ROM must get permission from me first.

Quake is a trademark of id Software, inc.
Windows ia a trademark of Microsoft Corporation.
All other trademarks are copyrighted by their respective owners
