English (United Kingdom) Hebrew

For instructor: creating tutorials

This page contains information on how to build interactive tutorials. Within a tutorial you can determine within each step what the student is required to do, so that moving to the next step depends in completing successfully the current one. During the tutorial play a dark glass screen is displayed which disables access to user interface parts in general, and enables access only to the components defined to be accessed in the current step of the tutorial.

Contents


Building interactive tutorials

To start the tutorial, within Mama select from the menu Tools->Tutorial Editor. The tutorial editor is opened, displaying user interface for building tutorial pages for a given world.
Note: if you want the tutorial to be associated with a certain Mama world from its start, load that world prior to starting the tutorial editor. Otherwise, you will start with en empty world, and you will have to instruct the student to load the required world during the tutorial. (An example for such world loading during the tutorial can be found in the tutorial space).
In building a tutorial we use several concepts:
  • page - the current page in the tutorial. You can create as many pages as you like in the tutorial editor.
  • note - a note which includes instructions or explanations for the user while in the current page. There are several note types:
    • A normal note
    • A normal note with a link next to advance to the next page
    • reference note - A note containing a reference to a certain component on the screen indicated by an arrow from the note to that component.
    • A reference note with next - contains a link Next to the next page
    • A note with a hole - similar to reference note but instead of pointing on a component there exists a "hole" in the dark screen, guiding the user to select or drag that component using the mouse.
As you can see in the picture above, there are two menus: a navigation menu with a pink background displayed to the user during the tutorial play (at the top of the screen), and a tutorial editor displayed in the center of the screen. The tutorial editor menu is displayed only while editing the tutorial, and you can exit editing mode anytime and remain in normal user mode by closing the tutorial editor window (that is a convenient way to check the tutorial you built). From the tutorial editor menu you can make the following actions:
  • Open tutorial... - open an existing tutorial
  • Save tutorial - save the current tutorial
  • New page - create a new page in the tutorial
  • Remove page - remove current page
  • Remove last note - remove last note created in the current page
  • close tutorial window - exit editing mode and remain in a user mode
To create a note select New note..., which will bring up a form for creating a note:

In the new note form you can select the type of the note and its attributes that determine whether is it displayed with a link Next (for hole and reference), and whether it contains auto advance (for hole). Within the form body you can type the note content, and when done drag the form to where you want the note to be located. In case of reference or hole bring the red point in the upper left corner of the form - on which the arrow points - to exactly above the component on the screen which is to be referenced by this note, then approve.
Note: to create a new note you can also right click on the screen where you want to create it. In response to the click, a menu is displayed for selecting the note type. The main difference between the two methods is that in the first one - the tutorial editor menu - you can make text actions such as copy and paste, while the right click menu don't provide these actions.

Example: building a tutorial

To demonstrate working with the tutorial editor, we will create a sample tutorial:
  • Open a new world with a template of type grass. Save the world to a file and remember where you saved it - actually it is preferred to save it to the same folder where you will save the tutorial (starting a tutorial while the current world is saved to a file will save the world file name into the tutorial, and will automatically open it whenever starting the tutorial).
  • Open the tutorial editor by selecting from the menu Tools->Tutorial Editor.
  • Select a note of type note and check has next and approve - a note is created in the form location, and now you can type its content, for example: "First note in first page". At any step you can cancel the creation of the note by selecting Remove last note, which will remove the last note from the current page. Note: the system may change the location of the note in order to avoid hiding it by the 3D window.
  • Click on New page - a new page is created. You can verify in the navigation window that you have 2 pages (and the current page is the second). Also, automatically a new note form is displayed.
  • Create a new note, this time of a type reference and check has next. Drag the form to the Play button - the red button in the upper left corner should be exactly above the Play button. As the note text type "This button is used to run the world", and approve. A new note is created pointing to the Play button.
  • Create a new page, within it create a note of type hole without auto advance, and locate it on the Play button. Inside the note type "Press this button to run the world." and approve. This note instructs the user to run the world.
  • While on the same page create a normal note with has next with the content "When done, click 'next' to continue.".
  • Now you can test what you've created so far: return to the first page and try to use the tutorial in a user mode!
Note: if you want to test the tutorial without the tutorial editor menu, save the tutorial to a file and exit the editor by closing the window. Later, you can reopen the tutorial file and continue editing.
  • Now we will guide the user to add objects from the object gallery: create a new page with a note of type hole with auto advance, and locate it on the button that opens the object gallery, indicated by "+". Within the note type "Click this button to open the object gallery".
  • Create a new page. Now we want to move the world to the state following a click on the "+" button. For doing that, hide the tutorial dark glass by clicking on the Show/Hide tutorial button, and then click on "+" to open the object gallery. After opening the object gallery, return the dark glass by clicking again the Show/Hide tutorial button.
  • Create a note of type hole and auto advance with the text "Click Sports sub directory". Drag the note to above the subdirectory Sports that in the object gallery and approve.
  • Use again the above technique: create a new page, hide the dark glass, click on Sports and return the dark glass.
  • Create a note of type hole without auto advance above one of the balls with the text "1Drag this ball from here...". Create another note of type reference with has next above the 3D window with the text "2...and drop it here". Notice the numerals at the start of the note content: these will cause the notes to be displayed with and ordinal number in the page - if a number appears at the start of the note text, without a space - it will be taken to be the note ordinal number.
  • Create a new page, hide again the dark glass and drag the ball you selected earlier into the 3D window - that imitates what the user will do. Return the dark glass.
  • Create a new note of type hole with auto advance above the button closing the object gallery, with the content "Click this button to close the object library".
  • Create a new page, hide again the dark glass and close the object gallery. Return the dark glass.
  • Create a note of type note without has next with the text "End of tutorial!".
  • Save the tutorial. Now you can play the whole tutorial in a user mode to test it.
Comments:
  1. It is suggested to save the tutorial into a file, but not to save the world you've changed during the tutorial editing/play, because you would want the student to start the tutorial with the initial world you set prior to creating the tutorial!
  2. Note that in creating a page with a hole note you have 2 options to move to the next page: create the hole with an auto advance or add another note with a has next checked. In a manual editing of the tutorial file (see below) you can actually define the hole to be with has next.
  3. When playing the tutorial in a user mode for doing a test it is normally preferred to start it in the first page, and move from there step by step. That is because the world state might be changed during the pages, and a non sequential play of the tutorial may cause an unexpected error.


Saving the tutorial to file

In saving a tutorial to a file, if the tutorial you built relates to a world file, you will have to verify that the world file will be available to the student as well. The best way to do that is to edit the tutorial file - it is an XML formatted file (see below) - and right at the beginning you'll find the definition of the world file. You can change it to suit your needs: if a path is specified, Mama will search for this path when loading the tutorial. If only file name is given, Mama will search for that file in the folder from which it loads the tutorial itself - and thus it is the preferred option when transferring that tutorial to your students.

Manual editing of the tutorial file

A tutorial file is an XML formatted file which describes the steps of the tutorial, and thus it is possible to edit it manually. That is an advanced option for instructors who want to build tutorials with custom options such as easy duplication of steps, change of page/note order, multi lingual tutorial, etc. This file can be edited with any text editor, and thus all you need is to become familiar with its structure and syntax.

The general format of the file is as follows:
 
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<stencilStack access="read" world="instructor_guide.mam" author="My name">
 <stencil stepsToGoBack="1">
  <stateCapsule>
   <![CDATA[existantElements|?|nonExistantElements|?
			|propertyValues|?|elementPositions|?|]]>
  </stateCapsule>
   <note hasNext="true" type="null" xPos="0.01640625" yPos="0.2746478873239437">
    <id><![CDATA[null]]></id>
	<message><![CDATA[First note in first page]]></message>
  </note>
 </stencil>
 <stencil stepsToGoBack="1">
  <stateCapsule>
    <![CDATA[existantElements|?|nonExistantElements|?
			|propertyValues|?|elementPositions|?|]]>
  </stateCapsule>
     <note hasNext="true" type="frame" xPos="0.0" yPos="0.0">
       <id><![CDATA[MAMA_ID_playButton]]></id>
	   <message><![CDATA[This button is used to run the world]]></message>
    </note>
  </stencil>
	...
</stencilStack>
 
Explanation:
  • The tutorial file is an XML file with UTF-8 character set, enabling multi lingual content
  • The tag StencilStack declares start of the tutorial. This tag may contain the attributes:
    • access - open the file in read or write mode - normally not relevant, since you can always edit the file from the application
    • world - the world file to open, which will automatically be opened when opening the tutorial. If a full path is specified, it is taken from there. Otherwise, if only file name is specified, it is searched in the folder from which the tutorial is loaded.
    • author - name of the tutorial author
  • The tag Stencil declares a page in the tutorial. It contains the attribute stepsToGoBack which determines the number of steps to go back in case of an error, and its value is normally 1. This tag may contain the following tags:
    • stateCapsule - defines the required world state as a preliminary condition for the current page. This tag contains a string describing the world state using 4 parameters: existantElements, nonExistantElements, propertyValues and elementPositions. A neutral world state - that is, with no special state definition - is set as follows:
 
<stateCapsule>
   <![CDATA[
    existantElements|?|nonExistantElements|?|propertyValues|?|elementPositions|?|
   ]]>
</stateCapsule>
 
  The parameters and the values are separated by '|', and the parameter values are indicated by the sign '?' at the beginning and at the end, where a single '?' indicates an empty parameter value. For example, in the tutorial we built above, in the page following the insertion of the ball object into the 3D window, the world state is set as follows:
 
<stateCapsule>
  <![CDATA[
	  existantElements|?toyBall1?|
	  nonExistantElements|?|
	  propertyValues|?toyBall1.vehicle:World?toyBall1.localTransformation:
		position: -0.99, 0.15, -0.69;	orientation: (0, 0, -0) 1?|
	  elementPositions|?toyBall1:3?|
  ]]>
</stateCapsule>
 
  As you can see, the first parameter requires existence of the ball object in the world, the second is empty, the third defines the property values of the ball object (location, direction) and the last parameter defines the ordinal number of the ball object in the world (3).
  • The note tag indicates a note in the current page. Notice the Stencil tag which represents a page may contain several note tags. Examples:
 
<!-- frame note -->
<note hasNext="true" type="frame" xPos="0.0" yPos="0.0">
   <id><![CDATA[MAMA_ID_playButton]]></id>
   <message><![CDATA[This button is used to run the world]]></message>
</note>
<!-- hole note -->
<note advanceEvent="mousePress" autoAdvance="true"
	hasNext="false" type="hole" xPos="30.0" yPos="30.0">
	<id><![CDATA[MAMA_ID_sceneEditor<MAMA_ID_small>:
		MAMA_ID_singleView:makeSceneEditorBigButton]]></id>
		<message><![CDATA[Click this button to open the object gallery]]></message>
</note>
<!-- 2 numbered hole notes -->
<note advanceEvent="mousePress" autoAdvance="false"
		hasNext="false" type="hole" xPos="0.0" yPos="0.0">
	<id><![CDATA[MAMA_ID_sceneEditor<MAMA_ID_large>:MAMA_ID_singleView:
	  MAMA_ID_galleryViewer<Home\Local Gallery\Sports>:
	  MAMA_ID_galleryObject<Local Gallery\Sports\ToyBall1.a2c>]]></id>
	  <message><![CDATA[1Drag this ball from here...]]></message>
</note>
<note advanceEvent="mousePress" autoAdvance="false" hasNext="true" 
		type="frame" xPos="392.0" yPos="-177.0">
	<id><![CDATA[MAMA_ID_sceneEditor<MAMA_ID_large>:
			MAMA_ID_singleView:renderPanel]]></id>
			<message><![CDATA[2...and drop it here]]></message>
</note>
 
Attributes of this tag are:
    • has next - indicates whether the note includes has next
    • type - can have the values null=normal note, frame=a reference note, and hole=a hole note.
    • auto advance - indicates whether the note includes auto advance
    • advance event - in case of auto advance, what is the event type - the relevant option is mousePress.
    • xPos,yPos - location of the note on the x and y axes in the 3D window. In case of a normal note, the coordinate values are between 0 and 1, and they relate to the upper left corner as the origin (x grows to the right and y downward), where value 0 indicates the beginning of the axis and value 1 indicates the end of the axis on the window. In case of notes of types reference or hole the coordinates are defined as the distance in pixels from the point of the referenced component. Note: the system may change the location of the note in order to avoid hiding it by the 3D window.
Inside the note tag the following tags may be defined:
    • message - the textual content of the note, normally displayed within a CDATA tag which enables writing text in any language and including any signs freely. If the text starts with a number, this number will be displayed as the ordinal number of the note when the tutorial is played.
    • id - (relevant for notes of type reference and hole) the identifier of the user reference component. The identifier name always starts with a standard prefix, 'MAMA_ID_'. Possible values for this id are:
Identifier name Component
MAMA_ID_fileMenu file menu
MAMA_ID_editMenu edit menu
MAMA_ID_toolsMenu tools menu
MAMA_ID_helpMenu help menu
MAMA_ID_playButton play button
MAMA_ID_addObjectButton add object button
MAMA_ID_undoButton undo button
MAMA_ID_redoButton redo button
MAMA_ID_exporFilmButton export movie button
MAMA_ID_createExeButton create executable button
MAMA_ID_addCharacterButton add character button
MAMA_ID_importImageButton import image button
MAMA_ID_create3DButton create 3D objects
MAMA_ID_helpButton open help
MAMA_ID_objectTree object tree
MAMA_ID_sceneEditor scene editor - state is attached as a parameter (MAMA_ID_large / MAMA_ID_small)
MAMA_ID_details details area
MAMA_ID_behaviors events area
MAMA_ID_createNewEventButton create new event button
MAMA_ID_editors program editor area
MAMA_ID_galleryViewer gallery view window
MAMA_ID_galleryObject object in the gallery
MAMA_ID_userDefinedResponse user defined method - it's name is attached as a parameter
MAMA_ID_singleView not int use
MAMA_ID_quadView not in use
  The above identifiers may appear with triangular parentheses. Examples:
 
MAMA_ID_sceneEditor<MAMA_ID_large>
 
  - references the scene editor when in stage setting mode
 
MAMA_ID_sceneEditor<MAMA_ID_small>
 
  - references the scene editor when in program editing mode
 
MAMA_ID_details<ice_skater>
 
  - references the details area where the ice skater was selected in the object tree
  Identifiers may be specified sometimes hierarchically, for example:
 
MAMA_ID_details<ice_skater>:MAMA_ID_userDefinedResponse<ice_skater.skate>
 
  - references a selected object's method in the details area
  There are secondary identifiers which are always specified with triangular parentheses:
MAMA_ID_button any button - its name is a parameter
MAMA_ID_element any component - its name is a parameter
MAMA_ID_elementTile any component's tile - its name is a parameter
MAMA_ID_elementPrototypeTile any prototype's tile - the prototype name is a parameter
MAMA_ID_property an object's property - its name is a parameter
MAMA_ID_viewController view controller of a certain component - component name is a parameter
MAMA_ID_tab details area tab - its name is a parameter
  Examples:
 
MAMA_ID_elementTile<event1>
 
  - references the first tile in the event area
 
MAMA_ID_elementTile<event1>:MAMA_ID_property<triggerMethod>
 
  - references the first tile's property triggerMethod in the event area