In this tutorial, we will write a script that executes the process from creating a project to registering a Waveform to a Cue.

Preparing a Script file
Importing Module
Settings of the project name and the project save destination
Creating project and Work Unit
Registering Material
Saving a project

Below is the basic method to create an object:

Preparing a Script file

Select "Script list..." in the Script menu to display the Script list window.
Click the New button in the Script list window to create a Script file with the name below:

Save location of Script	Script file name
tutorials [CRI]	tutorial02-1_new_basic_project.py

Script Description

Double-click the created Script to open by Run the Script from the Script Editor .
In order to get an overview of the Script in the Script list window, write the Script description as follows:

# --Description: [Tutorial] Creating and saving basic playback data from project to Cue

Importing Module

Once you have written the Script description, import the following modules to work with CRI Atom Craft in your Script. Write the Script in Run the Script from the Script Editor to import:

import sys
import os
import cri.atomcraft.debug as acdebug
import cri.atomcraft.project as acproject

Other than Python's standard module "sys" and "os", this time we will import two modules to work with CRI Atom Craft.
In addition to the Debug Module used in the Display "Hello, World" in the Script log tutorial, the Project Module is imported to work with the project data of CRI Atom Craft.

Settings of the project name and the project save destination

Write a Script including the project name to create, the project save destination, and the location of the Waveform file for the tutorial:

Item	Details
Project name	TutorialProject_Robot
Save destination of the project	PC's "Documents/CRIWARE/CriAtomCraft/projects"
Location of the Waveform file for the tutorial	Tutorial folder's "tutorials/robot/local/tutorial_data"

Write a Script of these project information as follows.

# Project name to create
project_name = "TutorialProject_Robot"
 
# Location to create the project
projects_dir = os.path.expanduser('~/Documents/CRIWARE/CriAtomCraft/projects')
if not os.path.isdir(projects_dir):
    os.makedirs(projects_dir)
 
# Location of the Waveform file for the tutorial
data_dir = os.path.dirname(os.path.dirname(__file__)) + '/tutorial_data'

The "os.path.expanduser" function in Python is an "os" module function that expands "~" to user's home directory in a created path.
"~" will be replaced in the above directory.
The "os.path.isdir" function is used to check whether the path is an existing directory. If not, use the "os.makedirs" function to create a directory.

The "os.path.dirname" function is used to get the directory path.
In Python, " __file__ " is used to get the current file path.
The Waveform file used in the tutorial is located in the "tutorial_data" folder above the running Script file.
Execute os.path.dirname twice to get the above directory and specify the 'tutorial_data' to the location of the Waveform file for tutorial use.

Note: About variables
Similar to "<b>project_name = "TutorialProject_Robot"</b>", we call the value on the left side before ”=” (i.e. "project_name") as Variable.
Variable can save the data, such as number or characters, used by the program temporarily.
If you store the data in the variable, you can easily retrieve the variable data in the subsequent process.

Creating Project and Work Unit

We have introduced how to set the import settings of the module to be used, the project name, and the project save destination.
Apply to work with CRI Atom Craft data in the following.
In the Project Module by the importing module, you can use the following function to create a project and Work Unit.

Function name	Description
create_project	Creates a project
create_workunit	Creates a Work Unit

Write a Script to use these functions to create project and Work Unit as follows:

# Creating a project
result = acproject.create_project(projects_dir, project_name, True)
if not result["succeed"]:
    acdebug.warning("Failed Create Project")
    sys.exit()
 
# Creating a Work Unit
result = acproject.create_workunit("WorkUnit_Tutorial", True, None)
if not result["succeed"]:
    acdebug.warning("Failed Create WorkUnit")
    sys.exit()
 
# Get the Work Unit information
workunit = result["data"]

Write and execute the Script.
When the Script is executed, it will create the "TutorialProject_Robot" project including Work Unit "WorkUnit_Tutorial" under "Documents/CRIWARE/CriAtomCraft/projects".

Description of creating project

Specify "Project name", "Project save destination" and "Whether to overwrite the project" in the create_project function that creates projects.
If you specified "Whether to overwrite the project" as True , even if a project with the same name exists in the project save destination, it will overwrite and create a new project.
When executing the function, it will return as a return value.
And store the value in the "result" variable.

In the "result" variable, various information of the executed result is stored and you can use the identification character(key) to retrieve the information.
Use the "succeed" key to get whether the executed function is succeeded.
Get the information result of the "succeed" key that is stored in the "result" variable, and confirm whether creating project is succeed.
If it fails to create project, it will output the log and terminates the Script execution.

Note: About "if" conditional statement in Python
Use the " if ~ " statement of " if not result["succeed"]: " to check whether creating project is succeed.
The mechanism of conditional statement (i.e. if a specified condition is satisfied, it will process something) is written as follows:

"if" conditional expression:

Process

Process

Indentation is used in the if-statement.
In Python, we call this indented range that the control statement processes as the Code Block.
In Python, usually 4 spaces is used to indent.

Description of creating Work Unit

Specify the information of "Work Unit name", "Whether to manage Material in Work Unit" and "Bus Map to set when creating Cue" in the create_workunit function that creates Work Unit.
When executing the create_workunit function, the return value will be stored in the "result" variable like the create_project function.
Information of the "succeed" key is stored in the "result" variable while information that identifies the created Work Unit is stored in the "data" key.

In order to get the information of the Work Unit after determining whether creating Work Unit has succeeded, get the Work Unit information in the "result["data"]" to store in the "workunit" variable.

Note: The result of executing the create_project function and create_workunit function is stored in the "result" variable.
The value returned by this function is called "Return value".
This return value stores various information of the result by executing the function.
Use the information in the return value to get CRI Atom Craft information, and work with CRI Atom Craft.
For details about the return value of each function, refer to Module reference .

Registering Material

This section has introduced how to create the project and Work Unit.
Register the Waveform file to the Material information of the created Work Unit, and create a Material.
Use the following function to register the Waveform file in the Material root folder.

Function name	Description
get_material_rootfolder	Gets a Work Unit's Material root folder
register_material	Registers a Waveform file to create Material

Write a Script to use these functions to register the Materials as follows:

# Gets a Material root folder
material_rootfolder = acproject.get_material_rootfolder(workunit)["data"]
 
# Register a Waveform file in a Material root folder
material = acproject.register_material(material_rootfolder, data_dir+"/tutorial_data01/gun1_High.wav")["data"]

Description of registering Material

Specify "Folder of the register destination" and "Waveform file to register" in the register_material function to register Material.
First, use the get_material_rootfolder function to get the Material root folder of the Work Unit.
Next, use the register_material function to register the Waveform file in the Material root folder and create a Material.

By running the Script, you can check that the "gun1_High.wav" Material has been created in the Material root folder of the Work Unit.

Note: About using only partial of the return value
In the get_material_rootfolder function and the register_material function, write a script to get only partial the return value ["data"] as below:

material_rootfolder = acproject.get_material_rootfolder(workunit)["data"]

If you do not need all the information of the return value and only some of it, get by adding " ["key to get"]" at the end of the function.
Then the Script will first get the entire return value and extract to get the necessary information.

Creating Cue Sheet, Cue and Waveform region

This tutorial introduced how to register the Waveform file in the Material information of the Work Unit.
Use the following function to create a Cue Sheet and a Cue under it, register the Material in the Cue to create the Waveform region.

Function name	Item
get_cuesheet_rootfolder	Gets the Cue Sheet root folder of Work Unit
get_child_object	Gets the child object by specifying the parent object
create_object	Creates object by specifying type
create_waveform_region	Creates the Waveform region

Write a Script to use these functions to create Cue Sheet and Cue and Material settings as follows:

# ----- Creating Cue Sheet/Cue -----
# Get a Cue Sheet folder
cuesheet_rootfolder = acproject.get_cuesheet_rootfolder(workunit)["data"]
 
# Get a Cue Sheet folder "WorkUnit_Tutorial"
cuesheet_folder = acproject.get_child_object(cuesheet_rootfolder, "CueSheetFolder", "WorkUnit_Tutorial")["data"]
 
# Create a Cue Sheet in the Cue Sheet folder
cuesheet = acproject.create_object(cuesheet_folder, "CueSheet", "Tutorial")["data"]
 
# ----- Create Cue/Track/Waveform region -----
# Create a Cue
cue = acproject.create_object(cuesheet, "Cue", "gun1_High")["data"]
# Create a Track
track = acproject.create_object(cue, "Track", "Track")["data"]
# Create a waveform region by specifying Material
waveform_region = acproject.create_waveform_region(track, material)["data"]

Description of creating Cue Sheet

Use the get_cuesheet_rootfolder function to get the folder of the destination of creating Cue Sheet, and get the Cue Sheet root folder of the Work Unit。
Next, use the get_child_object function to get the "WorkUnit_Tutorial" folder directly under the Cue Sheet root folder.
Specify the "Object information of the obtained source", "Object type to get" and "Object name to get" in the get_child_object function.

The WorkUnit_Tutorial folder is a folder with the same name as the Work Unit, which is automatically created when creating Work Unit.
By creating a Cue Sheet in this folder, the output destination of ACB(game data)can be separated for each Work Unit.

Specify the Cue Sheet folder of the above created destination, Cue Sheet object type "CueSheet" and the Cue Sheet name "Tutorial" to create a Cue Sheet in the create_object function, which is a general-purpose object creation function.
Specify the "Object information of the created source", "Object type to create" and "Object name to create" in the create_object function.

Description of creating Cue, Track, Waveform region

Create Cue, Track and then Waveform region in the created Cue Sheet.
Refer to the object structure described in Object structure of CRI Atom Craft if you want to understand why Cue and Track are needed before creating waveform region.
Cue, Track and Waveform region are hierarchically related.
Use the same create_object function for creating Cue Sheet to create Cue and Track.
Waveform region is created by specifying "Track information of the created destination" and "Material to reference" in the dedicated create_waveform_region function.

Note: For the object type name specified by the get_child_object function and the create_object function, refer to Object reference .

Note: This section has introduced how to use the create_object function to understand the hierarchy structure of the object and the create_waveform_region function to create Cue, Track and Waveform region in sequence.
The Project Module also has a function called create_simple_cue that creates Cues, Tracks and Waveform files in one function by using the Material name without the extension as the Cue name.
If you write a Script with create_simple_cue to create "Cue, Track and Waveform region" of the created Script, you can use less code to create Cue.

cue = acproject.create_simple_cue(cuesheet, material)["data"]

Saving the project

This tutorial introduced how to create a project and create Cue with a registered Waveform file.
At the end of this tutorial, below will show how to save the created the project.

Use the following function to save the project.

Function name	Item
save_project_all	Saves the project

Write a Script to use these functions to save the project as follows:

# Saving the project
result = acproject.save_project_all()
 
# Check the result in case of failure in saving. Output a message if fails.
if not result["succeed"]:
    acdebug.warning("Failed to save the project file.")