面向指导人员:创建教程
此页包含了关于如何构建交互式教程的信息。 在教程中，您可以决定每个学生在每一步需要做什么，以便可以移动到下一个步骤。 在教程中一个暗色玻璃屏幕将显示，它可禁止访问用户界面的一般部分，只允许访问的当前步骤定义的允许访问的部分。
内容
构建交互式教程
要启动教程，从菜单中选择
工具/
教程编辑器。 打开教程编辑器，显示构建给定world教程的用户界面。
在构建教程时，我们使用几个概念:
- 页 - 教程中的当前页面。你可以在教程中创建你所需的更多的页面。
- 注释 - 注释包括了当前页面中对用户的说明或解释。有几种注释类型:
- 一般注释
- 一般注释带有连接下一个以推进到下一页
- 引用注释 - 包含对画面某个部件引用的注释，有箭头从注释指向部件。
- 带有下一个的引用注释 - 包含到下一页的链接下一个。
- 带有入口的注释 - 类似于引用注释，但是没有箭头而是在暗屏上有一个入口，指导用户使用鼠标选择或拖住部件。
正如在上边的图片所看到的，有两个菜单:粉色背景的导航菜单（教程播放时在画面顶部）和教程编辑器（画面中间）。 教程编辑器菜单只在编辑教程时显示，你可以随时退出编辑模式，并通过关闭教程编辑器窗口停留在一般用户模式（这是检查所构建的教程一种很方便的方法。 在教程编辑器菜单中你可以生成下列动作:
- 打开教程... - 打开一个现有的教程
- 保存教程 - 保存当前教程
- 新的一页 - 创建一个新的页面
- 取消此页 - 移除当前页
- 取消上一次注释 - 移除创建的上一个注释
- 关闭编辑器窗口 - 退出编辑模式停留在用户模式
要创建
注释选择
新的注释...，显示创建注释的表格:
在新的注释表格中你可以选择注释类型和属性，决定注释是否带有链接
下一个（面向
入口和
参考），是否包含
自动推进（面向
入口）。 在表格中你可以输入注释内容，完成后拖住表格放到所需的位置。 在
参考或者
入口的情况下，把表格左上角的红点 - 箭头所指 - 放到注释要引用的部件上边，然后批准。
示例: 构建教程
要说明如何使用教程编辑器，我们将创建一个示例教程:
- 打开带有类型为草的模板的新world程序。 保存world到一个文件并记住你保存的位置 - 事实上，你最好保存在以后保存教程的同名文件夹中。
- 选择菜单工具/教程编辑器打开教程编辑器。
- 选择类型为注释的注释并检查has next批准 - 一个注释在表格处创建了，现在你可以输入内容，例如:“第一页第一个注释”。 在任何一步，你都可以选择取消上一次注释来取消注释的创建。 注意: 为了避免被3D窗口遮盖，系统可能会改变注释的位置。
- 点击新的一页 - 一个新的页面将被创建。 你可以在导航窗口中验证你有两个页面（当前页面和第二个页面）。 而且，新的注释表格会自动显示出来。
- 创建新的注释，这一次类型为参考。 并且检查has next。拖住表格放到播放按键 - 左上角的红色按键应该在播放按键上。 注释文本类型“此按键用来运行程序世界”并且批准。 这样一个新的指向播放按键的注释被创建了。
- 创建新的页面， 在里边创建类型为入口不带自动推进的注释，并且把它放到播放按键。在注释内输入“按此按键运行程序世界”并批准。这个指令将指导用户运行world程序。
- 在同一页创建带有has next内容为“完成后，点击“下一个”。”的注释。
- 现在你可以测试刚刚创建的内容: 返回首页并在用户模式下使用教程！
- 现在我们指导用户从对象图库中添加对象: 创建类型为入口带有自动推进的新的页面，并把它放到打开图库的按键上，用“+”表示。 在注释内输入“点击按钮打开对象库”。
- 创建新的页面。 现在我们想把world程序移到点击“+”按键的后续状态。 为了完成此事，点击显示/隐藏教程按键隐藏教程暗色玻璃，然后点击“+”打开对象图库。 打开对象图库后，再次点击显示/隐藏教程按键返回暗色玻璃。
- 创建类型为入口和自动推进内容为“点击运动子目录”。 拖住注释放到子目录运动上边并批准。
- 再次使用上面的技术: 创建新的页面，隐藏暗色玻璃，点击运动并返回暗色玻璃。
- 创建类型为入口不带自动推进的注释，放在内容为“1从这拖住球体...”的球上。 创建另一个类型为参考带有has next的注释，放到内容为“2...并把它放在这里”的3D窗口上。 注意注释开始处的数字: 他们会和注释一起显示，以及页面的基数 - 如果数字在注释内容的开始处出现，没有空格 - 那么这个数字将作为注释的基数。
- 创建新的页面，再次隐藏暗色玻璃，并拖住之前选定的球放到3D窗口 - 这是现在模拟用户使用。 返回暗色玻璃。
- 创建类型为入口带有自动推进的注释放到关闭对象图库的按键上， 内容为“点击按钮关闭对象库”。
- 创建新的页面，再次隐藏暗色玻璃，并关闭对象图库。 返回暗色玻璃。
- 创建新的类型为注释不带has next内容为“结束教程！”的注释。
- 保存教程。 现在你可以在用户模式下播放整个教程测试它。
评论:
- 建议保存教程到一个文件中，但是不要在教程编辑/播放时保存world，因为你需要学生启动教程，它所带有的初始world程序设置在创建教程之前。
- 注意在创建带有入口注释的页面中你有两种途径移到下一页: 创建带有自动推进的入口或者添加带有has next的注释。 在教程文件手工编辑的过程中（见下）你可以定义带有has next的入口。
- 在用户模式下播放教程测试时，最好从第一页开始，并逐步进行。 这是因为world状态可能在翻页的过程中变化，非顺序的播放会导致意外错误。
保存教程到文件
在保存教程到文件的过程中，如果构建的教程和world文件相关，你就必须验证world文件对学生也是可用的。 最好的办法是编辑教程文件 - 它是一个XML格式的文件（见下）- 并且在开始的时候就可以找到world文件的定义。 你可以按照自己需要改变: 如果指定了路径，Mama 会在加载教程的时候搜索这个路径。 如果只给定了文件名， Mama会在加载教程的文件夹中搜索这个文件 - 因此，建议在把教程给学生时使用这种方式。
教程文件手工编辑
教程文件时一个XML格式的文件吗，它描述了教程的步骤，因此可以手工编辑。 指导人员可能希望构建带有定制选项的教程，例如步骤的简易复制，页面/注释顺序的改变，多语言教程等，而教程文件是一种高级途径。 这种文件可以被任何文本编辑器编辑，因此你需要做的就是熟悉它的结构和语法。
文件的一般格式如下:
<?xml version="1.0" code="UTF-8" standalone="no"?>
<stencilStack access="read" world="指导_引导.mam" author="我的名字">
<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[第一页第一个注释]]></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[此按键用来运行程序世界]]></message>
</note>
</stencil>
...
</stencilStack>
解释:
- 教程文件是一个XML文件，其带有UTF-8字符集，允许多种语言内容
- 标签“StencilStack”说明教程的开始。这个标签会包含属性:
- “访问” - 以读取或写入模式打开文件 - 一般不相关，因为你总是可以在应用中编辑文件
- “world” - 要打开的world文件，会自动在打开教程时打开。如果指定了全路径，那么直接使用指定路径。 否则，如果值指定了文件名，只能在教程加载的文件夹中搜索。
- “author” - 教程作者的名称
- 标签“Stencil”说明教程中的某一个页面。它包括属性“返回步数”（出现错误时返回的步数）。 一般它的值为1。 这个标签会包含下列标签:
- “stateCapsule” - 定义了作为当前页基本条件的所需的world状态。 这个标签包含描述world状态的字符串，其使用2个参数: 存在元素，不存在元素，属性值和元素位置。 一个中立的world状态 -即没有具体的状态定义- 设置如下:
<stateCapsule>
<![CDATA[
existantElements|?|nonExistantElements|?|propertyValues|?|elementPositions|?|
]]>
</stateCapsule>
- 参数和值用“|”分开，参数值用“?”标明。 在开始和结束时，单个“?”表示一个空参数值。 例如在之前的教程中，在插入球体到3D窗口的后续页里，world状态设置如下:
<stateCapsule>
<![CDATA[
存在元素|?玩具球1?|
不存在元素|?|
属性值|?玩具球1.工具:World?玩具球1.本地转换:
位置: -0.99, 0.15, -0.69; 定向: (0, 0, -0) 1?|
元素位置|?玩具球1:3?|
]]>
</stateCapsule>
- 正如所见，第一个参数需要球体存在与world中，第二个参数是空的，第三个定义了球体对象的属性值（位置，方向），最后一个定义了world（3）中球体基数。
- “'注释”标签标明了当前页中的一条注释。注意表示一个页面的“Stencil”标签可能包含几个注释标签。 例如:
<!-- frame note -->
<note hasNext="true" type="frame" xPos="0.0" yPos="0.0">
<id><![CDATA[MAMA_ID_playButton]]></id>
<message><![CDATA[此键用来运行world]]></message>
</note>
<!-- hole note -->
<注释 高级事件="鼠标点击" 自动推进="真"
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[点击按钮打开对象库]]></message>
</note>
<!-- 2 numbered hole notes -->
<注释 高级事件="鼠标点击" 自动推进="假"
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[1从这拖住球体...]]></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...并把它放在这里]]></message>
</note>
- 这个标签的属性有:
- has next - 表明注释是否包含has next。
- 类型 - 有几个值 空=一般注释， 框架=参考注释和入口=入口注释。
- 自动推进 - 说明注释是否包含自动推进
- 高级事件 - 在自动推进情况下，什么是事件类型 - 相关选项是鼠标点击。
- xPos,yPos - 注释在x和y轴的位置。在一般注释下，坐标值在0和1之间，并且和左上角的原点相关（x 向右增长，y向下增长。原点处0值意味着坐标的开始，1意味着坐标的结束。在类型为参考或入口的情况下，坐标定义为引用部件的像素距离。注意:为了避免被3D窗口遮盖，系统可能会改变注释的位置。
- 在注释标签内部，可以定义如下标签:
- 消息 - 注释的文本内容，一般显示在CDATA标签中，可以用任何语言编写文本和随意添加符号。如果文本以一个数字开始，这个数字将作为注释的基数显示。
- id - （和类型为参考和入口的注释相关）用户引用部件的标识符。 标识符名称经常有一个标准的前缀， 'MAMA_ID_'。 id的可能值有:
| 标识符名称 | 部件 | | MAMA_ID_文件目录 | 文件目录 |
| MAMA_ID_编辑目录 | 编辑目录 |
| MAMA_ID_工具目录 | 工具目录 |
| MAMA_ID_帮助目录 | 帮助目录 |
| MAMA_ID_播放按键 | 播放按键 |
| MAMA_ID_添加对象按键 | 添加对象按键 |
| MAMA_ID_撤销按键 | 撤销按键 |
| MAMA_ID_重做按键 | 重做按键 |
| MAMA_ID_输出视频按键 | 输入视频按键 |
| MAMA_ID_创建可执行程序按键 | 创建可执行程序按键 |
| MAMA_ID_添加角色按键 | 添加角色按键 |
| MAMA_ID_输出图像按键 | 添加输出图像按键 |
| MAMA_ID_创建3D对象 | 创建3D对象 |
| MAMA_ID_打开帮助 | 打开帮助 |
| MAMA_ID_对象树 | 对象树 |
| MAMA_ID_场景编辑器 | 场景编辑器 - 状态作为参数 (MAMA_ID_大 / MAMA_ID_小)而依附的 |
| MAMA_ID_细节区域 | 细节区域 |
| MAMA_ID_行为 | 事件区域 |
| MAMA_ID_创建新事件按键 | 创建新事件按键 |
| MAMA_ID_编辑器 | 程序编辑器区域 |
| MAMA_ID_图库查看器 | 图库查看窗口 |
| MAMA_ID_图库对象 | 图库中的对象 |
| MAMA_ID_用户定义的响应 | 用户定义的方法- 它的名称作为 参数依附 |
| MAMA_ID_单一视角 | 没有使用 |
| MAMA_ID_四向视角 | 没有使用 |
- 上边的标识符可能带有尖括号。 例如:
MAMA_ID_场景编辑器<MAMA_ID_large>
- - 舞台设置模式下引用场景编辑器
MAMA_ID_场景编辑器<MAMA_ID_small>
- - 程序编辑模式下引用场景编辑器
MAMA_ID_细节<滑冰者>
引用滑冰者从对象树中选取的细节区域
- 有时标识符被一层层指定。例如:
MAMA_ID_details<滑冰者>:MAMA_ID_用户定义的响应<滑冰者.skate>
- - 引用细节区域中选定对象的方法
- 有第二种标识符，它总是用尖括号指定:
| MAMA_ID_按键 | 任何按键 - 它的名称是一个参数 |
| MAMA_ID_元素 | 任何元素 - 它的名称是一个参数 |
| MAMA_ID_元素程序块 | 任何部件的程序块 - 它的名称是一个参数 |
| MAMA_ID_元素原型 | 任何原型程序块 - 它的名称是一个参数 |
| MAMA_ID_属性 | 一个对象的属性 - 它的名称是一个参数 |
| MAMA_ID_视角控制器 | 某个部件的视角控制器 - 它的名称是一个参数 |
| MAMA_ID_标签 | 细节区域标签 - 它的名字是一个参数 |
- 示例:
MAMA_ID_元素程序块<event1>
- - 引用事件区域的第一个程序块
MAMA_ID_元素程序块<event1>:MAMA_ID_属性<激发方法>
- - 引用事件区域中第一个程序块的属性激发方法
