CRIWARE Unity Plugin Manual  Last Updated: 2024-07-12
将数据植入游戏
本章节描述了如何将CRI Atom Craft创建的音频数据植入游戏，并且回放该数据。

它展示了如何新建一个Unity项目，并将在CRI ADX中回放音频的各个项目放入不同的场景。
以下为步骤。

(1) 创建Unity项目

(1-1) 创建Unity项目
启动Unity，创建一个空白项目。
在本教程中，项目文件夹为"TutorialAtom"文件夹。
  • 在Project Wizard（项目向导）窗口中创建新项目
    请点击File目录中的New Project。
    显示Project Wizard窗口。请选择你想用于存储项目的文件夹。
    我们想要创建一个空白项目，因此请勿选择Import the following packages栏目中的任何选项。
    最后，点击Create Project按钮来创建项目。

    adx2u_qstart_game_newproj_mini.png
    [Project Wizard]
(1-2) 保存场景
创建新项目之后会出现一个场景。它仅包含了一个"Main Camera（主摄像机）"。
现在，保存场景。
在该教程中，场景的名字将被命名为"NewScene"。

  • 在Save Scene对话框里保存场景
    点击File目录的Save Scene。
    出现Save Scene对话框。请输入场景名称。


    adx2u_qstart_game_newscene_mini.png
    创建空白场景之后
[注意]
在这里，"Main Camera"的坐标为(0, 1, -10)。

(2) 导入插件安装包

现在，导入"CRIWARE Unity Plugin package"至项目。
插件包文件存储在以下位置：

  * CRIWARE

  \ * SDK

    \ * unity

      \ * plugin

        \ * criware_unity_plugin_smartphone.unitypackage

 

 

 

 

 

 

  • 导入自定义安装包
    从Assets -> Import Package目录，点击Custom Package目录指令。
    出现一个文件对话框。选择上述的插件包文件并将其导入。
    注意
    如果导入失败，请查看 故障排除 。

(3) 复制CueSheet二进制文件

(3-1) 用于进行回放的文件
如需在Unity中播放音频，你必须拥有来自CRI Atom Craft的以下文件：
  • "CueSheet二进制文件"
    • ACB文件 (*.acb): Cue文件信息、回放参数、以及用于记忆回放的音频数据（每个CueSheet需要一个ACB文件）。
    • AWB文件 (*.awb): 用于流媒体回放的音频数据（如果使用了流媒体回放，每个CueSheet需要一个文件）。
    • ACF文件 (*.acf): 配置和CueSheet-独立信息（每个项目需要一个文件）。
该教程使用的是创建于 " 创建数据 "的数据。
以下图片展示了用于本教程的"Tutorial（教程）"项目，其主文件夹的结构。

用于CRI Atom Craft的教程项目 其主文件夹的结构
  * CriAtomCraft

  \ * Tutorial

    \ * TutorialProject

      o * WorkUnits

      o * Materials

      |  

      o * PC

      | \ * Assets

      |   o * Plugins

      |   | \ * CriWare

      |   |   \ * CriAtomProjInfo

      |   |     \ * CriAtomProjInfo_Unity.cs

      |   |  

      |   \ * StreamingAssets

      |     o * TutorialProject.acf

      |     \ * TutorialCueSheet.acb

      |  

      o * TutorialProject.atmcglobal

      o * TutorialProject.atmcproject

      o * TutorialProject.materialinfo

      \ * NewProject_[host

 

项目存储文件夹

项目文件夹

工作单元文件夹

共享素材文件夹

 

 

: * 存储回放所需文件的文件夹

 

 

 

Unity信息文件（仅用于旧版本，新版本无需使用）

 

 

ACF文件

ACB文件

 

全局设置文件

项目文件

素材信息文件

name]_[user name].user_settings 用户设置文件

 

(3-2) 复制文件
找到"Tutorial"项目文件夹下的"PC/Assets"文件夹。这里存储着我们所需的CRI Atom Craft文件。将里面的所有内容复制到Unity项目的Assets（资源）文件夹。
您可以直接复制文件，但使用 Atom Browser窗口 的数据复制功能将更方便。
注意
如果您想将CRI数据作为CRI Asset使用，请参照以下的Asset Support插件页面。
[步骤一]
点击菜单栏[Window]->[CRIWARE]->[Atom Browser]选项。
Atom Browser将会出现。
程序将显示"Atom Browser"。
此刻，ADX数据暂未载入Unity项目中。 在Atom Browser上方将显示一条信息："No cue sheet is found（未找到cue sheet）。"

adx2u_atomwnd_first.png
Atom Browser

[步骤二]
在Atom Browser中，点击下方的Import Assets from Atom Craft Project 展开内容。
点击“Import From”栏的“...”按钮打开目录选择对话框。
请选择含有由CRI Atom Craft所创建的文件的资源文件夹。
该文件夹通常为CRI Atom Craft Project文件夹下的PC/Assets子文件夹。
但"在游戏中预览"功能的数据应当存储在PC/inGamePreview/Assets子文件夹。
请设定这两个文件夹其中之一的文件夹。
若用户设定了一个非资源文件夹，那么控制台将会发送以下错误信息。

adx2u_atomwnd_assetroot_error.png
CRI Atom Craft 输出文件夹设定错误

[步骤三]
若用户设定了一个可用文件夹，那么路径将会被更新。

adx2u_atomwnd_assetroot_set.png
[设定输出文件夹后]

将文件夹设定好后，请点击 Atom Browser底端的[Import Assets]按钮。
Unity的项目里将会新增一个名为Assets/StreamingAssets文件夹，所有需要的数据文件将被放入该文件夹中。

TutorialAtom Unity 项目的资源文件夹结构
  * TutorialAtom

  \ * Assets

    o * Editor

    |  

    o * Gizmos

    |  

    o * Plugins

    | o * Android

    | o * cri_ware_unity.bundle

    | o * iOS

    | \ * CriWare

    |   o * CriAtom

    |   o * CriFs

    |   \ * CriMana

    |  

    \ * StreamingAssets

      o * TutorialProject.acf

      \ * TutorialCueSheet.acb

 

资源文件夹

 

 

 

 

CRIWARE Unity 插件

 

 

 

CRIWARE Unity 插件源

 

 

 

 

StreamingAssets 文件夹

ACF文件

ACB文件

 

当数据完成复制，Unity中的"Project view"将被刷新，结果如下图所示：

adx2u_qstart_game_datafiles_mini.png
完成数据复制

(4) 创建CRIWARE文件库初始化器

在应用音频之前，用户需要为整个CRIWARE系统添加初始化模块以及错误处理模块。
它们并非强制添加型模块，但为了之后的精细调音，我们强烈推荐你添加这些模块。
分别执行[GameObject]->[CRIWARE]菜单中的[Create CRIWARE Library Initializer]和[Create CRIWARE Error Handler]选项。
在Unity的层次窗口中，CriWareLibraryInitializer以及CriWareErrorHandler将会出现。
到目前为止，你无需更改它们的设定。

adx2u_qstart_game_initializer_hierarchy.png
创建CRIWARE文件库初始化器后

(5) 在Atom Browser中检查Cue

现在开始检查"Atom Browser"中的CueSheet二进制复制文件。
(5-1) 显示"Atom Browser"
将ADX数据复制至Unity项目文件夹后， 请点击Atom Browser中的[Reload Info]按钮。
[No cue sheet is found]的对话框将会消失，Cue列表将会显示。


adx2u_atomwnd_cue_list.png
Atom Browser


因将频繁使用Atom Browser，请将Atom Browser停靠于Unity的主窗口中。

(5-2) 检查CueSheet信息
"Atom Browser"是使CRI ADX组件能够在Unity中创建的工具。
在这个程序中，你可以选择CueSheet、列出Cue并创建CRI Atom Source。
请在"Atom Browser"中寻找CueSheet标签。CueSheet信息将从即刻起开始显示。
如果它没有显示，请确认[Path to Search]的路径后，
点击"Reload Info（重新载入信息）"按钮，获取Cue List信息。

现在，你可以看到CueSheet的名称以及一个Cue列表。
当你选择Cue列表中的一个Cue，在它下方的[Cue Information]（Cue信息）将被刷新。

(6) 创建CRI Atom Source

在你能够在Unity中播放音频之前，你必须创建一个"CRI Atom Source"。
它将会是播放音频所需的唯一物件。
以下两种方法都能够创建CRI Atom Source。
根据不同情况，你可以选择其中之一。
  • 你可以将其创建为一个单独的game object（游戏对象）.,添加一个CRI Atom Source component（组件）。
  • 你可以以CRI Atom Source component（组件）形式将其添加至另一个游戏对象。
以下文字显示了如何使用以上两种方法创建CRI Atom Source。

(6-1) 将其创建为单独的游戏对象
首先，创建一个播放heli_Loop（直升机旋翼声）的CRI Atom Source。
  1. 请勿选择"Hierarchy view（层次结构视图）"的任何数据。
  2. 在"CRI Browser"中的"Cue Sheet"部分，选择Cue列表中的"heli_loop"。
  3. 在"CRI Browser"中的"Cue Information"部分的下面，请点击Create GameObject按钮。
一个CRI Atom Source已创建于该场景。

创建不久的"heli_Loop(CriAtomSource)"游戏对象将在"Hierarchy view"中显示。
如果你点击该项目，CRI Atom Source的详细信息将在"Inspector"中显示。
请选择CRI Atom Source的Play On Start（在开始时播放）选项。

adx2u_qstart_game_gameobj_le_mini.png
将CRI Atom Source创建为游戏对象

由于Play On Start选项已被选中，因此heli_Loop将在游戏开始的瞬间播放。
请点击Unity的播放按钮进行确认。
[注意] CRI Atom 对象
当一个CRI Atom Source被创建，应用程序将自动创建一个名为"CRIWARE"的"CRI Atom"对象。
CRI Atom是一个用于控制所有音频回放的对象。

(6-2) 以组件形式将其添加至另一个游戏对象
这次，我们会把CRI Atom Source以组件形式添加至另一个游戏对象。
  1. 请从菜单中选择 GameObject -> 3D Object -> Cube 以创建一个正方体。
  2. 请确认该立方体的坐标为 (0, 0, 0)。
  3. 请选择"Hierarchy view（层次结构视图）"中的立方体。
  4. 请从"Atom Browser"的"Cue Sheet"部分中，选择Cue列表中的 "gun1_High"（枪击声）。
  5. 请点击位于"Atom Browser"的"Cue Information"底端的 Add Component 按钮。

CRI Atom Source组件已添加至立方体。

点击该立方体。在"Hierarchy view"中，请为CRI Atom Source选中 Play On Start 选项。

adx2u_qstart_game_gameobj2_le_mini.png
将CRI Atom Source以组件形式创建
由于附着于该立方体的组件的 Play On Start 选项同样被选中，gun1_High 和 heli_Loop 都会在游戏开始时播放。

(7) 运用脚本控制音频回放

到目前为止，应用程序只能简单地回放音频。现在来添加一个能够与游戏进行沟通的脚本。
该脚本将在用户使用鼠标点击立方体时播放声音。
(7-1) 为立方体添加控制音频回放的脚本
请参照以下步骤来为立方体添加脚本。
  1. 选中立方体。在"Inspector"中，请为Cri Atom Source清除 Play On Start 选项。
    （它将取消游戏开始时的自动回放。）
  2. 请选择"Hierarchy view"中的立方体。
  3. 请在"Project view（项目视图）"中点击鼠标右键，以创建一个C::脚本。
    将文件重命名为"CuePlay"。
  4. 在"Hierarchy view"中，请将CuePlay.cs拖拽至立方体上，使文件添加至立方体。

    adx2u_qstart_game_gameobj2_cueplay_mini.png
    将脚本添加至立方体

运行MonoDevelop，并且如下编辑CuePlay.cs。

public class CuePlay : MonoBehaviour {
// 将其用于初始化
void Start () {
}
// 更新为每帧一次
void Update () {
}
void OnMouseDown() {
CriAtomSource audio = (CriAtomSource)GetComponent("CriAtomSource");
audio.Play();
}
}

OnMouseDown句柄
在此脚本中，OnMouseDown句柄用于指令点击鼠标时会触发的事件。
首先，请将CRI Atom Source组件附着于对象。
其次，播放该CRI Atom Source指定的Cue。

(7-2) 启动游戏
请点击Unity中的Play按钮，以启动游戏。
在游戏开始的瞬间，heli_Loop（直升机旋翼声）就会开始播放。
当点击场景中央的立方体时，gun1_High（枪击声）就会开始播放。

adx2u_qstart_game_gameobj3_run_mini.png
启动游戏