THE PLUGIN PROPERTIES WINDOW
(FULL EDITION ONLY)
Description of each field, with tips and suggestions
Plugin File Name: It is the name of the file that
is used to store the plugin information. The extension of the file is .PL1, .PL2, or .PL3,
depending on the version of the Plugins System. Do NOT enter the extension in the field,
because Adventure Maker will automatically add it at the end of the name that you enter.
Although they are allowed, avoid using spaces or special characters. It is strongly
recommended that you include the version of the plugin in its filename.
Example: my_great_plugin_v1_0
Plugin Name: It is the full title of the plugin. It
will appear in the list of all the available plugins under the "Plugins" tab of
the "Project Properties" window. Make it as clear as possible, without
abbreviations or underscores. Any characters are allowed except the quotes. Make sure to
include the version of the plugin at the end of the name. Example: My Great Plugin v1.0
TIP: How to create a group of plugins: If
two or more plugins have the exact same "Plugin Name" (but a different
"File Name" and "Internal Name"), they will form a group, meaning that under the "Plugins" tab of
the "Project Properties" window the user will see only one entry for the two
plugins. For example, the Flash Plugin that is included in the Adventure Maker package is
a group of 2 plugins (it is made of 2 files, but you will see only one entry in the
Project Properties).
Plugin Internal Name: It is the name that
internally identifies the plugin, meaning that it is used to understand which information
belongs to which plugin when saving and reloading the Hotspot Properties and the Frame
Properties windows. For that reason, it is very important that you change the "Internal
Name" every time that you make changes to the Plugin interface. Note:
When creating a new plugin, a random "Internal Name" is automatically generated.
Feel free to change it, but make sure to make it unique. Example: plugin220402346
Configuration Utility: (optional) It is the
name of the optional executable file (.exe) that allows the user to configure the plugin
by clicking "Configure the selected plugin..." from the "Plugins" tab
of the "Project Properties" window. The file must be located inside the
"Plugins" sub-folder of the Adventure Maker folder (in other words, it must be
located in the same folder as the plugin itself). When the file is launched, the full path
of the project directory is passed as a commandline parameter, allowing the configuration
utility to know where on the hard disk the project files are located, for example to
create a configuration file inside the project directory (the "External"
sub-folder of the project folder is particularly recommended for creating configuration
files). If the Configuration Utility creates an INI configuration file, you can use the
ReadINI function to read it from Adventure Maker (refer to the VBScript Language Reference page for details on the ReadINI
function). Example: MyGreatPluginConfiguration.exe
Plugin Description: (optional) It is the text that appears when the AM user
single-clicks on a plugin under the "Plugins" tab of the "Project
Properties" window. People can also read it when they edit the plugin with the
"Plugin Properties" window. There are no size limitations. Any characters are
allowed. Example: This is my new plugin.
To use it, you must...
The startup tab contains two fields. The first one allows adding some VBScript code to the
code that is executed when the project starts or a savegame is loaded, whereas the second
one allows adding some VBScript code to the code that is executed every time that the
end-user goes from one frame to another during play.
Executing some VBScript code "when the project starts or a savegame is loaded"
allows for example to check whether a given ActiveX component (OCX) is installed on the
computer. Here is a sample code for doing that:
If Action.IsComponentInstalled("COMPONENT_ID") = False Then
MsgBox "Unable to find the component. The component must be installed
in order for the application to work properly.", vbCritical, "Component Not
Installed"
End If
where you must replace COMPONENT_ID with the ProgId of your custom ActiveX
component (read the section "using ActiveX components
(ocx)" for details).
Executing some VBScript code "every time that a frame is loaded"
allows for example to make sure that the custom ActiveX components (OCX) added to the
frame are unloaded when the player quits the frame. For example, if you want to play a
looping Flash movie to animate the background of a frame, you may also want to make the
Flash movie disappear when the player goes to another frame. Here is a sample code for
doing that:
Action.RemoveComponent
"COMPONENT_NAME"
where you must replace COMPONENT_NAME with the name that you gave to the component
instance when you created it with the "Action.AddComponent" function (read the
section "using ActiveX components (ocx)" for
details).
The procedures tab allows adding global VBScript procedures to the projects in which the
plugin is enabled. To declare a procedure, you can use the following code:
Sub MYPROCEDURE(ARGUMENT1, ARG2,
ARG3)
CODE
End Sub
where you must replace MYPROCEDURE with any name of your choice (without spaces or
special characters), CODE with the VBScript code that should be executed when the
procedure is called, and ARGUMENT1, ARG2, ARG3... with any names of your choice (without
spaces or special characters).
ARGUMENT1, ARG2, ARG3... are the local variables that will temporarily store the value of
the arguments passed to the procedure. There are no limitations in the number of arguments
that can be passed to the procedure.
Note: To prevent conflicts in case that the AM user enables two different versions of the
same plugin, it is recommended that you include the version
of your plugin in the name of your procedures. For example, if your plugin
is version 3.1 and you have a procedure named "MyProcedure", it is recommended
that you rename your procedure to "MyProcedureVersion31". Note that the dots
"." are not allowed in the name of the procedures.
The variables tab allows adding global variables to the projects in which the plugin is
enabled. The variables are added when the project starts or a savegame is loaded, and they
hold their value until the end-user quits the game or application. The value of the
variables are also stored in the savegames. There are no limitations in the number of
global variables that you can create. Do NOT use quotation marks for the variable names.
It is also strongly recommended that you do not use spaces or special characters. Note
however that you can use both lowercase and uppercase letters.
There are two kind of variables: "Integer" variables, which can hold any number
between -32768 and 32767, and "Variant" variables, which can hold any type of
data, including strings, dates and floating-point values.
The interface tab allows adding options to the Hotspot Properties and Frame Properties
windows. Those options are associated to VBScript procedures, meaning that when the AM
user selects one of those options, the corresponding VBScript procedure is called. The
arguments (aka "parameters") passed to the VBScript procedure correspond to the
checkboxes, textboxes and fileboxes that you add to the Hotspot Properties or Frame
Properties windows.
For example, if you do the following to create a Flash Plugin:
- check the option "Add a command to the Hotspot properties window",
- type "Play Flash Movie" in the "caption" field,
- type "play_flash_movie" in the "VBScript procedure" field,
- create one FileBox (i.e. a button that allows selecting a file) and give the caption
"Choose the Flash file to play" to it,
the result will be a new option under the "Hotspot Properties" window, which,
when selected, causes the execution of the procedure named "play_flash_movie",
with only one single argument, which is the string contained in the FileBox.
Important note: the checkboxes, textboxes and fileboxes must correspond to the arguments
of the specified VBScript procedure. For example, if you create 3 checkboxes and 2
textboxes, you must make sure that the specified VBScript procedure has 5 arguments. In
other words, you must make sure that the text field that is under the
"Procedures" tab contains something like that:
Sub MYPROCEDURE(ARGUMENT1, ARG2,
ARG3, ARG4, ARG5)
CODE
End Sub
where you must replace MYPROCEDURE with the exact name of the VBScript procedure that you
have specified under the "Interface" tab. You can also replace ARGUMENT1, ARG2,
ARG3, ARG4 and ARG5 with any names of your choice (they are local variables).
You can have a look at the sample plugins included in the Adventure Maker package
to better understand this point.
Note (1): The "item usage caption" is the caption of the option that is
displayed on the Hotspot Properties window when the AM user drags-and-drops an inventory
item onto a hotspot. Here is an example of what has been entered in those fields for the
Flash plugin:
Caption: When the hotspot is clicked, play a Flash
movie.
Item usage caption: On item drag-and-drop, play a Flash movie.
Note (2): The arguments passed to the specified VBScript procedure are always strings.
While it may sound obvious for the textboxes and the fileboxes, it is less obvious for the
checkboxes. When a checkbox is "checked", the value passed to the VBScript
procedure is the string "True", whereas when the checkbox is
"unchecked", the value passed to the VBScript procedure is the string
"False" (mind the case!). When checking whether the value is "True" or
"False", make sure to use the following code:
if myvariable = "True"
then
instead of the following one:
if myvariable = true then
(mind the quotation marks and the letter T that is uppercase).
The OCXs tab allows specifying which ActiveX custom components must be distributed with
the project when the AM user compiles the project into a self-installing executable.
During the installation process of the final product, the OCX files are copied to the
Windows System folder, and they are automatically registered with regsvr32.exe.
During design time, the OCX files must be located inside the "Plugins"
sub-folder of the Adventure Maker folder (and NOT inside the "components"
sub-folder of the project folder, which is meant
for other purposes). In other words, the OCX files must be located in the same folder as
the plugin itself.
|
