|
What it does
The "Interface Controller Package" [ICP] is a package that allows GM's
to keep a structured overview of all their installed packages, assuming they
register with, and conform to the
requirements of, this package.
How it works
ICP is installed, just like any other package, by being placed into
the '/pkg' directory. Unlike most optional packages, however, it is not
installed into the '/pkg/opt' directory! It's a control-package and, as such,
defaults to the root '/pkg' folder. If you extract this archive, as-is, into
your '/pkg' directory, it should have created the /pkg/control
folder, automatically.
As can be seen in the requirements section of this help-file,
this package requires the Gumps package (at least revision v2.1) and
Sigismund's 'string.inc' file (at least revision v1.2). These should both be found
on the ONElist,
in the files section, under the '/OptionalPackages' and '/Includes' folders, respectively.
* NOTE: This is not a set of control scripts and
should not be extracted into the
/scripts/control directory! *
Once installed, ICP initialises, automatically, when the server first
starts up, recurses through the entire list of loaded packages and calls a
predefined script (ctrl_reg.src) which is,
optionally, defined by each package. This script should then return a
structure, containing specific information, which is
used by ICP to append it to the end of the list of registered packages.
This list is then stored, globally, and used, at a later time, by the
Control Gump which is called up using the
.control dot-command.
Once the server is running, the list of registered packages can be refreshed
by issuing one of two commands:
.control -r
.control -refresh
Please refer to the "Control Gump" section for what
the .control command does with no parameters.
CTRL_REG.SRC
The information within the structure, returned by the ctrl_reg.src script,
is quite specific. The definition is as follows:
- User-friendly name
(string)
This is the name shown on the ICP control gump.
It's a "friendly name" so as to be easily identifiable to the user.
|
- Version number
(string)
This is a string form of the version number of the package (which should,
really, be the same as the version number given in the package's pkg.cfg
file)
|
- Whether it has a "user interface" or not
(integer)
Any package that has a "user interface" [UI]
(whether it be an informational gump, a gump for altering the package's
settings or a system-message spam of commands) would pass an integer value
of 1 (one) for this parameter. The lack of a UI would define the package as
"listed only for the convenience of the user" and would require an integer
value of 0 (zero) to be passed as the parameter.
|
- If it has an interface, which script do we call?
(string)
If a UI exists for a package then this parameter holds the name of the
script (excluding the .src extension)
to be initiated when a package is selected from the
control gump. Please note that the ICP script
will auto-prepend the script name with the package name (eg. with
:control: in the case of the ICP) and, as such, expects only
the unqualified script name, itself. It can, however, specify a path
to follow from the package's root folder; thus, making it possible to specify
a dot-command script as the interface script! (See the
'textcmd.src' file in the '/examples' directory within this package for
a pre-written example of how this is implimented)
|
The structure should have the following member variables (examples are given based
on the structure returned by ICP's own ctrl_reg.src script):
| Member Variable |
Example Value |
.sName |
"Interface Controller" |
.sVer |
"0.5a" |
.bCtrl |
0 |
.sScript |
"" |
The Control Gump
The Control Gump is ICP's main display, accessed by the
.control command (without any parameters), which shows the
list of installed packages that have registered with
ICP via the ctrl_reg.src script-mechanism.
In the list, each package is shown by its "friendly name" and its version
number. If the package has been registered as having an
interface, then there is a small blue button to the
left of the name; press this button to close the Control Gump and bring up
that package's interface (what this
interface looks like, is entirely dependant on the
package in question... although, a document detailing a "standard look" will
be available, soon)
You can close the Control Gump, without choosing a package, by either
right-clicking it or clicking the <Cancel> button at the bottom right.
Interface Script
There are at least two things an interface script MUST cater for when
it is called:
- An ICP test-call
When a package is registered as having an
interface script, ICP tests to see whether the specified
script is valid before it adds it to it's internal list...
if your script can't pass back the correct value (a simple non-zero
integer), then it will be assumed to be invalid. (See
the 'textcmd.src' and 'normal.src' scripts in the
'/examples' directory within this package to see how interface scripts
should interpret their parameters)
|
- An ICP start-call
This call is made when a user presses the blue interface button to the
left of a package-name on the Control Gump.
Since the script must recognise when it's the ICP is calling it
and when it's not, you can do initialisation, here, that you may not
do normally (I'm not sure if, or where, this would be
useful, but the functionality is there for you to use as you will :-)
)
|
NOTE: An interface script cannot do anything other
than return the non-zero value during the test-call, as this is done during the
server's initial start-up phase! There is no user attached to the call
so creating gumps, or calling user-interactive functions, will
cause your script to fail the ICP's test-call and may even print
erroneous error messages to the console! You have been warned!
Overview of Package Requirements
Firstly, to use ICP you must be running version 088 of the POL core. This is
not an option; you must be running that core version, at least!
You must also have, at least, v2.1 of the 'gumps' package installed, and enabled, and
Sigismund's 'string.inc' file, of at least v1.2 (if you need to recompile the ICP
package, for some reason, then the 'gumps' package must be in the root '/pkg' directory
alongside ICP, otherwise you'll need to amend the "include" path in the
'check_packages.src' script!)
Then, to become properly registered, a package must adhere to,
and fulfil, the following requirements:
- The package must be enabled.
- The package must contain a compiled
'ctrl_reg.src' script.
- If the package has an
interface:
|
Example scripts
Within this package you'll find a .ZIP file called examples.zip. If
you extract this archive into ICP's directory it should automatically create an
'/examples' folder with three sub-directories. These sub-directories contain the
example package configurations as detailed in the following table:
Package Directory
(and description) |
Filename |
Description |
|
| /examples/normal |
mainscript.src |
A dummy file that represents the "main script" for this package. :-)
|
|
Type: Normal
Interface: No
|
ctrl_reg.src |
The registration script for this example package. |
| pkg.cfg |
The package-config file for this example package. |
|
|
| /examples/interface |
interface.src |
The script that holds the "interface code" for this package. This is
the script that needs to deal with the "test-call" mechanism.
|
|
Type: Normal
Interface: Yes
|
ctrl_reg.src |
The registration script for this example package. |
| pkg.cfg |
The package-config file for this example package. |
|
|
| /examples/textcommand |
/textcmd/gm/textcmd.src |
An example script that shows how to double a GM's text-command script
as an interface script.
|
|
Type: Advanced
Interface: TextCmd
|
ctrl_reg.src |
The registration script for this example package. |
| pkg.cfg |
The package-config file for this example package. |
Please note, if you compile up these examples, they will show up in ICP's
Control Gump, when you restart the server, as the POL core
sees them as nested packages. This cannot be helped, nor altered, by ICP. Sorry.
Credits :-)
Credits, thanks and kudos to the following people (in no particular order other than
an alphabetical one :) for all the moral support and bug-testing and, in particular,
Syzygy for tweaking the POL-core to allow the core of this package to work! :-)
| AlleyCat |
Cassandra |
Louds |
Madman |
Mieow |
| Moravi |
Seilar |
Syzygy |
ToriOtoko |
Ynara |
|
|