INTRODUCTION TO VBSCRIPT (FULL EDITION ONLY,
WINDOWS ONLY)
Introduction
Variables
Making variables
interact with hotspots
Going to
another frame
Available actions
Modifying
hotspot and text attributes
Procedures
INTRODUCTION
Adventure Maker allows advanced
users to execute some VBScript code at several points in the game, for example when the
player clicks on a hotspot or when he drags and drops an item onto an hotspot or onto
another item.
To add VBScript code to your
project, go to the "Hotspot Properties" window, click the "Advanced"
tab, and select the option "Execute VBScript code". A text field will appear and
will allow you to enter VBScript instructions directly without the need of creating any
procedure. You can either put one instruction per line, or put several instructions in a
single line and separate then with the colon ":". Here is an
example of what you can put into the text field:
msgbox
"Hello!" : msgbox "How are you?"
This simple instruction will
cause two message boxes to popup and say "Hello" and then "How are
you?".
VARIABLES
Adventure Maker supports two
types of variables: Integer and Variant. Integer
variables can only hold an integer number between -32768 and 32767. Variant variables can
hold any type of data, including strings, dates and floating-point values. When you create
a Variant variable, you don't need to specify which of the above data types you want to
use. However, after you have assigned a value to a given Variant variable, you cannot
change its type. For instance, if you execute MYVARIABLE="Hello", MYVARIABLE
will become a string and therefore executing MYVARIABLE=5 will generate an error.
Variables can be local
or global. Local variables are deleted as soon as the execution stops,
whereas global variables are saved and can be used to store a value. To create a global
variable, use the "Variables..." button that is under the text
field. To create a local variable, simply use it in the text field without declaring it
with the "Variables..." button.
To change the value of a
variable, simply type myvariable = value where
"myvariable" is the name of the variable and "value" is the new value.
MAKING
VARIABLES INTERACT WITH HOTSPOTS
If you want a hotspot to be
enabled or disabled depending on the value of a variable, then create a new integer
variable and add it to one of the lists that are under the "Variables" tab in
the "Hotspot Properties" window. This feature is extremely useful if you want to
create complex puzzles. Read the following example to better understand the general idea.
EXAMPLE
- How to make an hotspot appear after 5 mouse clicks:
If you want a
hotspot (let's call it hotspot1) to appear after the player has clicked 5 times
on another hotspot (let's call it hotspot2), then follow these steps:
1. Create a new
Integer variable called "myvariable"
2. Go to the properties of hotspot1 and set it to be visible only if the
value of myvariable is 1 (to do so, use the option "the hotspot must be
enabled/visible only if..." that is under the "Variables" tab).
3. Go to the properties of hotspot2 and add the following code to the
VBScript text field:
myvariable
= myvariable - 1
if myvariable = -5 then myvariable = 1
The initial
value of myvariable is 0. The first line of code will decrease the value of myvariable by
1. The second line will check if the value of myvariable is (-5). If that is the case, the
value of myvariable will become 1, which will automatically cause hotspot1 to
appear.
GOING
TO ANOTHER FRAME
To go to another frame, use the
following syntax:
Action.GoToFrame
"FRAME_NAME"
where FRAME_NAME is the name of
the frame where you want to go. For example, if you want to go to the frame named
"Room" if the value of the variable "DoorOpen" is 1, use the following
code:
If DoorOpen
= 1 then Action.GoToFrame "Room"
To go to another frame with a
transition, use the following syntax:
Action.GoToFrame
"FRAME_NAME" , DURATION , NUMBER
where DURATION is the duration
of the transition and NUMBER is the number that identifies the transition. The
possibilities for NUMBER are:
1 |
Alphablending |
2 |
Slide
Left |
3 |
Slide
Right |
4 |
Slide up |
5 |
Slide
Down |
For example, to
go to a frame name "Inside_Castle" with a 5-seconds alphablending transition,
use the following code:
Action.GoToFrame
"Inside_Castle", 5, 1
Available
actions
Below is a list of all the
actions available in this version of Adventure Maker. For details and comments concerning
each of them, go to the VBScript Language Reference
page.
Action.AddComponent
Action.AddItem
Action.CaptureFrame
Action.ChangeDefaultCursor
Action.ChangeDisplayResolution
Action.ChangeDisplayResolutionOnLoadGame
Action.ConvertQuotesIntoDoubleQuotes
Action.ConvertToNumber
Action.CreateTimedEvent
Action.DDir
Action.DoComponentsEvents
Action.DoesComponentExist
Action.GetAMVersion
Action.GetClickPositionX
Action.GetClickPositionY
Action.GetCurrentFrameName
Action.GetDisplayResolutionX
Action.GetDisplayResolutionY
Action.GetEffectsStatus
Action.GetEncryptedFileName
Action.GetHotspotNumber
Action.GetMergedHotspotIndex
Action.GetMergedTextIndex
Action.GetNumberOfFrames
Action.GetPath
Action.GetProjectHeight
Action.GetProjectName
Action.GetProjectTitle
Action.GetProjectWidth
Action.GetTransitionsStatus
Action.GetVariableReferenceFromName
Action.GoToFrame
Action.InvertTransitionsStatus
Action.InvertEffectsStatus
Action.IsComponentInstalled
Action.IsRunningFromEditor
Action.HideInventoryButton
Action.HideMenu
Action.LoadAPicture
Action.LoadControl
Action.LoadGraphicFile
Action.LoadParameter
Action.Message
Action.OpenFile
Action.OpenExeFileAndWait
Action.OpenURL
Action.PopupLoadGame
Action.PopupSaveGame
Action.Quit
Action.QuitDialogue
Action.ReadINI
Action.RefreshWindow
Action.RemoveComponent
Action.RemoveAllItems
Action.RemoveItem
Action.RemoveTimedEvent
Action.ResetRemovedHotspots
Action.SaveAPicture
Action.SaveParameter
Action.SendEmail
Action.ShowInventoryButton
Action.ShowMenu
Action.SimulateHotspotClick
Action.StopEverything
Action.UnloadControl
Action.UpdateHotspotsState
Action.WriteINI
For example, to go to the frame named "Frame1", use the following code:
Action.GoToFrame
"Frame1"
To make the "Load
Game" window popup, use the following code:
Action.PopupLoadGame
To display the message
"The door is closed" at the bottom of the screen, use the following code (the
message will automatically disappear after a few seconds):
Action.Message
"The door is closed."
To add an item to the
inventory, use the following code:
Action.AddItem
"ITEM_NAME"
To change the default mouse
pointer, use the following code:
Action.ChangeDefaultCursor
"FILE_NAME"
To change the value of VAR1
every 10 seconds, use the following code:
Action.CreateTimedEvent
10, VAR1 = 1 - VAR1, True
For more examples, and details
on each of the available actions, go to the VBScript
Language Reference page.
Modifying
hotspot and text attributes
To change the attributes of a
hotspot, use the following syntax:
Hotspot(INDEX).ATTRIBUTE
= VALUE
where INDEX is the number that
identifies the hotspot, ATTRIBUTE is the name of the attribute you want to change and
VALUE is the new value of the attribute.
The syntax for changing the
attributes of a text object is very similar:
Text(INDEX).ATTRIBUTE
= VALUE
For example, if you want all
the text objects to display the current date, use the following code (you can replace
"x" with any variable of your choice, provided that it is not declared
elsewhere):
For each x
in Text
x.Caption = Date
Next
Or if you want to disable all
the hotspots (which is not very clever, because the player will not be able to finish the
game...), use the following code:
For each x
in Hotspot
x.Enabled = False
Next
Some of the available
attributes of the hotspots are: top, left, height, width, mouseicon, mousepointer,
picture, stretch, visible, enabled, tag and ToolTipText.
Some of the available
attributes of the text objects are: top, left, height, width, mouseicon, mousepointer,
visible, enabled, tag, caption, alignment, backcolor, backstyle, borderstyle, fontbold,
fontitalic, fontname, fontunderline, ForeColor and ToolTipText.
The "tag" attribute
is unused by Adventure Maker, and therefore you can use it to temporarily store any extra
data needed for your project. For example, the sample "Othello" game included in
the Adventure Maker package uses of the "tag" attribute to remember whether a
hotspot contains a Black disc, a White disk, or no discs at all.
For multi-line text, use the
VBCRLF constant. For example, to display a two-lines message in the text object #1, use
the following syntax:
Text(1).Caption
= "This is the first line" + VBCRLF + "This is the second line"
Note: To create a text object
during design-time, simply right-click on the frame background in the Frame Editor. To
retrieve the number that identifies a text object, leave the mouse pointer over the text
object for a few seconds until the Tool-Tip text appears.
PROCEDURES
A procedure is a piece of code
that you can call from everywhere in your project.
1. HOW
TO EXECUTE (CALL) A PROCEDURE:
To call a procedure, simply
type its name in the VBScript text field. For instance, if you have created a procedure
called "myprocedure", you can execute it by simply typing myprocedure. If your
procedure has one or more arguments (parameters), let's say 3 arguments, then you must
call it by typing:
myprocedure arg1 , arg2 , arg3
where arg1, arg2 and arg3 are the 3 arguments, separated by
commas. If your procedure is a function (which means that it returns a value), then you
can call it by typing:
return_value = myprocedure (arg1 , arg2 ,
arg3)
where return_value is a variable of your
choice.
For instance, the "msgbox"
procedure (which causes a message box to popup) can be used either as a "sub"
(=procedure with no return value) or a function (=procedure with return value). Here is
how to call it as a sub:
msgbox "Hello!"
and here is how to call it as a function:
return_value = msgbox ("Do you
want to continue?", vbYesNo)
The return value is 6 if the player has clicked
"Yes" and 7 if the player has clicked "No". Go to the "Language Reference" page for details on how to use
the msgbox function.
2. HOW
TO CREATE A PROCEDURE:
To create a procedure, click
the "Procedures..." button that is under the VBScript text field in the
"Hotspot Properties" window. A window will popup and will show you all your
project procedures. To create a new procedure, simply add its code in the text field using
the syntax explained below.
To create a procedure with no
arguments and no return value (called a "sub" procedure), use the following
syntax:
sub
PROCEDURE_NAME
[code]
end sub
where
"PROCEDURE_NAME" is the name of your procedure and [code] is the VBScript code
you want to be executed when the procedure is called. Below is an example of procedure
called "DisplayDate" which will display the current date:
sub
DisplayDate
msgbox "The current date is: " + cstr(date)
end sub
To create a procedure with
arguments (but still without return value), use the following syntax:
sub
PROCEDURE_NAME (arg1,arg2,arg3)
[code]
end sub
Where arg1, arg2 and arg3 are
the variables that will store the parameters passed when the procedure is called. You can
use them in the [code] that is inside the procedure to act in a different way depending on
the parameters. Below is an example of procedure called "Addition" that will
calculate A + B and display the result in a message box:
sub
Addition (A,B)
msgbox "The result is: " + cstr(A+B)
end sub
Last but not least, to create a
procedure with arguments and return value (called a "function"), use the
following syntax:
function
FUNCTION_NAME (arg1,arg2,arg3)
[code]
end sub
Below is an example of function
called "RandomValue" that will return a random value between a minimum and a
maximum (which are the two arguments of the function):
function
RandomValue (MIN,MAX)
randomize
RandomValue = int(rnd*(MAX-MIN+1))+MIN
end sub
If you want to display a random
number between 0 and 100, add the function above to the Project Procedures and then enter
the following code in the VBScript text field:
msgbox
RandomValue(0,100) |