TWiki
> Main
>
IntroductionToTheMscapeScriptingLanguage
Introduction to the Mscape Scripting Language
You can produce some cool mediascapes simply by using the drag-and-drop functionality built into the mscape maker tool. But what about when you want to make something a little more interactive like a game?
Well in order to do this you need to learn a little bit of programming - the mscape scripting language to be exact.
The language we use is very similar to that used by a lot of systems out there on the web - the syntax has a lot of similarities to Javascript, and particularly Java. In fact for the technically-minded the code you write is actually the Microsoft C# language - each event handler (e.g. the code you write for
OnEnter? on a region) is simply converted to a function in C#. This means that anything you can write in a C# function, you can write in an Event Handler. If you have never programmed before it is worth reading up a little on basic programming concepts like variables, control statements before plunging too deep into mscape code. Unfortunately I don't have space to teach all of these concepts here!
Basics
Everything in a mscape is an 'object'. A region is an object, an audio is an object, as is the GPS and any maps you have. Objects in mscape can have three different features which can be used as part of your programming.
| Feature |
Example |
Description |
| Action |
myAudio.Play(); |
An action performs an operation on an object. The example here will start the audio called myAudio playing. To call an action write the name of the action followed by round brackets. |
| Property |
myAudio.IsPlaying |
A property is a piece of information held about an object. This piece of information can be read, and used in an expression (e.g. if the audio myAudio is playing, then show a picture, see later). Some properties can also be changed by your script - for example CirleRegion? objects have X and Y properties - you can move the region by changing these values in your program. |
| Event |
region3 OnEnter |
Events on an object are where you type in your program - you can't actually 'make' an event run yourself, the system will do this for you. In this example, the OnEnter event will be triggered when the user walks into the area covered by region3. |
Running Actions
Most objects in Mscape have several actions that can be performed on the object, such as the Show and Hide actions on Image objects, or the Play action on the audio object.
To find out what actions are available on a particular object, type the name of the object into the event window text editor (or drag-and-drop the object from the left-hand panel to the text editor) and type the . (period) character.
The actions on an object are listed with the blue arrow icon in the list that pops up. The items with the grey box icon are properties (see later).
Actions on the Image object
In general, to run an action on an object use the syntax below, where objectName is the name of the object, and actionName is the name of the action:
objectName.actionName();
For example, to make the audio called myAudio start to play use:
myAudio.Play();
The name of the action goes after the . (period) character. It is then followed by (); if the action has no parameters. If the action does have parameters, the value for each parameter is entered in a list between the brackets, separated with commas.
objectName.actionName( Param1, Param2, ... );
For example, the debug.Log action has a single parameter, which is a string. To call it use the following syntax:
debug.Log("The message to log");
If a parameter is a string (text) then surround the text with double quotes.
Properties
Properties are pieces of data held about a mscape object. Examples are myAudio.Playing (is the audio called myAudio currently playing?), myRegion.X (the X-coordinate of a circular region) and myRegion.EnteredCount. Some properties are
read-only - e.g. you cannot change them in your program, such as myRegion.EnteredCount and others are
read-write like myRegion.X and myRegion.Y.
If you want to find out what properties an object has and what they do then simply click the object in mscape maker and look at the Properties box. Clicking on the property will show a description at the bottom - you may need to expand the window to read the whole thing.
The properties box for a region
Properties shown greyed out are read-only, and those in black are read-write. Notice that
EnteredCount? is grey, and X and Y are black.
Setting a Property
You can set the value of a property (provided it is read-write) using the following syntax:
objectName.propertyName = newValue;
For example, to set the value of a 'Text' object called 'Status' to the string "Winning":
Status.Value = "Winning";
Note that the kind (or type) of data on the right-hand side (e.g. "Winning" above) must match the type that the property expects. E.g. you can't set the value of a 'Number' object to "Winning".
Reading a Property
You can read the value of any property on an object very easily..
objectName.propertyName // example myRegion.EnteredCount
Reading a property is useful in expressions (see later) and also for storing current values of properties for later use.
// remember the original position of myRegion
startPositionX.Value = myRegion.X;
startPositionY.Value = myRegion.Y;
// change it
myRegion.X = 100;
myRegion.Y = 100;
//.. later on we can restore the position
myRegion.X = startPositionX.Value;
myRegion.Y = startPositionY.Value;
if statements
Sometime you may wish to make a choice in your mscape - for example perhaps what you want is to make a region play one sound the first time you enter and a different one the second time.
To do this you will use an 'if' statement. This example should be typed into the OnEnter event for a region.
if (me.EnteredCount == 1)
{
sound1.Play();
}
else if (me.EnteredCount == 2)
{
sound2.Play();
}
Note that you'll need sounds called sound1 and sound2 for this to work.
me refers to the region who has been entered, and
EnteredCount? is a 'Property' (a piece of information about that region) that will give you the number of times the region has been entered. We compare that against 1 using the equals operator (== two equals signs, not one) - and if it is the same we play sound1. If not, it'll then test it against 2, and if that's the same it'll play sound2.
Some more examples..
If the region has been entered more than three times..
if (me.EnteredCount > 3)
{
mysound.Play();
}
If the region has been entered 3 or less times, play a sound. Otherwise, show a picture.
if (me.EnteredCount <= 3)
{
mysound.Play();
} else {
mypicture.Show();
}
Comparison Operators
Here's a list of some of the possible operators you can use. Any C# comparison operators can be used, but these are the most common.
- > - greater than
- >= - greater than or equal to
- < - less than
- <= - less than or equal to
- == - equal to
- = - Not equal to (the opposite to ==)
Combining Expressions
Sometimes you may want to perform an action if two expressions are true.
- Play a sound if the region 'myregion' has been entered between 3 and 7 times.
if (myregion.EnteredCount >= 3 && myregion.EnteredCount <= 7)
{
mysound.Play();
}
'&&' means 'and'. Both myregion.EnteredCount >= 3 and myregion.EnteredCount <= 7 need to be true before the sound will play.
- Play a sound if the GPS has a fix and the background music has finished playing.
if (!GPS.HasFix = true && backgroundMusic.Heard = true)
{
mysound.Play();
}
- Play a sound if the GPS has a fix OR the background music has finished playing.
if (!GPS.HasFix = true || backgroundMusic.Heard = true)
{
mysound.Play();
}
- '||' means 'or'. If either GPS.HasFix = true is true or backgroundMusic.Heard = true, the sound will be played.
You can combine any number of expressions.
