FMOD Studio User Manual 2.02
studio.project 模块提供对项目模型中对象的访问。
项目的根工作区ManagedObject。
适用于此版本的项目Model类型表示。
保存项目。如果操作成功，则返回 true ，否则返回 false 。
将所有事件库构建到首选项对话框构建选项卡中列出的所有平台。如果操作成功，则返回 true ，否则返回 false 。
使用选项对象 {banks, platforms} 构建项目。如果操作成功，则返回 true ，否则返回 false 。
构建单个事件库还会构建和更新项目的主事件库和主事件库字符串文件。
例如:
// 单个事件库
studio.project.build({ banks: 'Weapons' }); // 为所有平台建立“武器”事件库
studio.project.build({ banks: 'Music', platforms: ['Desktop', 'PlayStation 4'] }); // 只为“桌面”和“PlayStation 4”平台建立“音乐”事件库
// 多个事件库
studio.project.build({ banks: ['Weapons', 'Characters'], platforms: 'Desktop' }); //只为“桌面”平台建立“武器”和“人物”事件库
studio.project.build({ banks: ['Weapons', 'Music'], platforms: ['Desktop', 'PlayStation 4'] }); // 将“武器”和“音乐”事件库构建到“桌面”和“PlayStation 4”平台上
// 平台
studio.project.build({ platforms: 'Desktop' }); // 为“桌面”平台构建所有事件库
studio.project.build({ platforms: ['Desktop', 'PlayStation 4'] }); // 为“桌面”和“PlayStation 4”平台构建所有事件库
导出项目 guids.txt。如果操作成功，则返回 true ，否则返回 false 。
返回列出所有可用插件的字符串数组。
返回通过 GUID 或路径找到的ManagedObject。传递的 idOrPath 可以是 GUID 或路径字符串。例如:
var item = project.lookup("{3a731ab3-ce6d-453d-862e-32050cecf68a}");
var event = project.lookup("event:/path/to/eventname");
var eventFolder = project.lookup("event:/path/to/foldername");
var bank = project.lookup("bank:/path/to/bank");
var snapshot = project.lookup("snapshot:/snapshotname");
var vca = project.lookup("vca:/vcaname");
路径的格式为 type:/path/to/item ，其中 type 是以下之一:
eventsnapshotbankbusvcaassetparametereffecttagprofilersession路径也可用于查找容器项，例如在事件层次结构中查找文件夹。
返回给定实体名称的ManagedObject的新实例。这将为该对象创建任何所需的子对象（例如，创建一个 Event 将创建并附加其 EventMixer）。
从项目中删除 managedObject 及其引用（若有）。这相当于删除用户界面中的项目。如果操作成功，则返回 true ，否则返回 false 。
项目的 .fspro 文件在磁盘上的绝对路径。
将音频资源导入项目并返回一个 AudioFile ManagedObject，如果导入失败，则返回 null。该文件始终导入到根音频 bin 文件夹中。使用 AudioFile.container 关系将其重新分配给另一个文件夹。
设置导入音频文件时调用的函数，签名为 function(audioFile)。
不再需要 connectFunction 时，则将其断开。当不再需要已连接的信号时，则要将其断开，否则会累积并导致意外的行为。
设置一个函数在构建事件库之前调用，签名为 function()。例如:
studio.project.buildStarted.connect(function() {
alert("Build about to start");
});
不再需要 connectFunction 时，则将其断开。当不再需要已连接的信号时，则要将其断开，否则会累积并导致意外的行为。例如:
function connectToBuildStart() {
alert("Build about to start");
};
studio.project.buildStarted.connect(connectToBuildStart);
studio.project.buildStarted.disconnect(connectToBuildStart);
设置一个在事件库建立后调用的函数，签名为 function(success)。如果发生构建错误或用户取消了构建，则 success 参数将为 false ，否则为 true。例如:
studio.project.buildEnded.connect(function(success) {
alert(success ? "Build has ended well" : "Build has ended badly");
});
不再需要 connectFunction 时，则将其断开。当不再需要已连接的信号时，则要将其断开，否则会累积并导致意外的行为。例如:
function connectToBuildEnd() {
alert("Build about to end");
}
studio.project.buildEnded.connect(connectToBuildEnd);
studio.project.buildEnded.disconnect(connectToBuildEnd);
对应于可用于空间效应不同距离衰减滚降类型的枚举。可能的值是:
LinearSquaredLinearInverseInverseTaperedCustom对应不同游戏参数类型可用的枚举。可能的值是:
UserDistanceDirectionElevationEventConeAngleEventOrientationUserLabeled对应于循环区域的不同循环模式的枚举。可能的值是:
NoneLoopingMagnetStudio.project.model 可提供对可用模型类型信息的访问。模型中的数据表示为ManagedObjects所基于的Entity类型的集合。可按名称查找实体。例如:
studio.project.model.Event.findInstances(); // 查找所有事件实例
返回与 entity_name 关联的studio.project.Entity。
返回描述每个studio.project.Entity的string。
studio.project.Entity 提供有关ManagedObject类型的信息。
可使用ManagedObject.entity检索给定 ManagedObject 的实体。这提供了实体的字符串表示，然后可以在studio.project.model中查找。
表示此实体继承的实体类型的字符串数组。
如果实体可以实例化，或者是其他实体类型的基类，则布尔值设置为 true 。
如果实体属于全局存在，而非在每个项目的基础上存在，则布尔值设置为 true 。
如果在任何给定时间只能存在实体的单个ManagedObject实例，则布尔值设置为 true 。
返回一个包含命名属性的对象，代表可用于此实体的每个ManagedObject属性。该值是一个描述对象，包含:
dataType [string]defaultValue [variant]返回一个包含命名关系的对象，代表可用于此实体的每个ManagedObject关系。该值是一个描述对象，包含:
cardinality [string]destinationType [string]isRequired[bool]返回给定实体类型的ManagedObject实例数组。
可选择传递一个options对象{ searchContext, includeDerivedTypes }。为searchContext字段传递管理对象会将对象搜索绑定到特定文件。为includeDerivedTypes字段传递true将可返回给定实体的派生类型。
例如:
// 找到项目中的所有 SingleSounds
studio.project.model.SingleSound.findInstances();
// 查找当前选定事件中的所有 SingleSounds
studio.project.model.SingleSound.findInstances({ searchContext: studio.window.browserCurrent()});
// 查找当前选定事件中的所有 GroupTracks、ReturnTracks 和 MasterTracks
studio.project.model.AudioTrack.findInstances({ searchContext: studio.window.browserCurrent(), includeDerivedTypes: true });
返回特定实体类型的单例ManagedObject实例。如果实体不是单例类型，则会抛出错误。
返回描述实体的 string ，包括其属性和关系。
Studio 中的项目级数据表示为 ManagedObject 的图表。 ManagedObject 包括:
-id: 唯一标识符 (GUID)。
-entity: 对象类型的描述（例如 Event、 MixerGroup、 Snapshot）。
-properties: 每个属性都是一个带有值的简单数据字段（例如浮点数、布尔值、字符串）。
-relationships: 链接到其他 ManagedObjects，称为 destinations。这些可以是 ToOne 或 ToMany，可以是有序的，也可以是无序的。
除了为每个 ManagedObject 提供的通用接口之外，还有许多扩展函数可用于特定studio.project.Entity类型的 ManagedObject。
可以使用studio.project.workspace检索项目的根ManagedObject。可以使用Entity.findInstances()检索特定studio.project.Entity项目中的对象。
表示对象的studio.project.Entity类型（例如 Event）的字符串。查找studio.project.model以检查有关实体的详细信息。不可变。
对象的唯一 ID。不可变。
返回对象是否处于有效状态。不可变。
扩展 API。返回类型为studio.project.ManagedPropertyMap的对象。提供对对象属性的访问。不可变。
扩展 API。返回类型为studio.project.ManagedRelationshipMap的对象。提供对对象关系的访问。不可变。
如果对象具有与entityName匹配的实体，或者是派生类型，则返回true。
如果对象具有与entityName完全匹配的实体，则返回true。这不包括派生类型。
便利 API。提供对管理对象属性值的访问。设置属性（使用 = 运算符）将设置属性值。
方便 API。提供对管理对象关系目的地的访问。获取ToOne关系将返回单个目标对象（如果未分配则返回 null）。获取ToMany关系会返回一个目的地数组（如果没有目的地，则返回一个空数组）。设置ToOne关系（使用=运算符）将设置替换当前目的地。ToMany 关系不能用 = 运算符修改，必须通过扩展 API 进行编辑。
记录所有成员。
返回描述此 ManagedObject 类型studio.project.Entity的 string。
例如，调用studio.project.workspace.mixer.masterBus.volume = 2，将遍历Workspace与全局Mixer的关系，然后是Mixer与MasterBus的关系 ，最后将MasterBus`上的音量属性设置为 2dB。
请注意，上面的示例使用 便利 API 以更具可读性的方式遍历图形。等效项（使用扩展 API）将是 studio.project.workspace.relationships.mixer.destinations[0].relationships.masterBus.destinations[0].properties.volume.setValue(2)。因此，便利 API 适用于快速遍历图形，而扩展 API 提供对属性和关系的高级属性的访问。
属性映射的所属管理对象。不可变。
返回给定属性名称的 studio.project.ManagedProperty 类型的对象。不可变。
记录所有成员。
关系映射的所属管理对象。不可变。
返回给定关系名称的 studio.project.ManagedRelationship 类型的对象。不可变。
记录所有成员。
属性的所属管理对象。不可变。
属性的名称。不可变。
此属性值存储的数据类型。不可变。
属性存储的值。不可变。
属性在创建时采用的默认值。不可变。
设置属性存储的值。如果操作成功，则返回 true ，否则返回 false 。
记录所有成员。
关系的拥有管理对象。不可变。
关系的名称。不可变。
表示对象基数的字符串。ToOne 或 ToMany。不可变。
"表示对象排序的字符串。如果是无序的，则为None ；如果其排序保存到项目中，则为Ordered ；如果按用户排序，则为Transient。不可变。
一组管理对象目的地。不可变。
将新目的地附加到关系。替换ToOne关系的当前目的地。如果操作成功，则返回 true ，否则返回 false 。
将新目标插入给定索引处的关系。索引必须在[0, destinations.length]范围内。如果操作成功，则返回 true ，否则返回 false 。
从关系中删除目的地。如果操作成功，则返回 true ，否则返回 false 。
记录所有成员。
特定类型的ManagedObject包含基于其studio.project.Entity类型的扩展功能。
返回资源所引用文件的路径，与项目资源目录相对应。
设置资源所引用文件的路径，与项目资源目录相对应。调用此函数会将底层文件资源移动到磁盘上。如果操作成功，则返回 true ，否则返回 false 。
返回资源所引用文件的绝对路径。
为可自动化对象的给定属性创建自动化轨道。返回自动化轨道管理对象。automatableObject 参数可以是轨道的任何可自动化对象，例如发声器、调音器效果或轨道本身的调音器总线。propertyName 参数必须是指定可自动化对象的有效可自动化属性。
例如:
// 为主音轨的音量添加一个自动化音轨
var event = studio.project.workspace.addEvent("New Event", true);
var masterTrack = event.masterTrack;
var automationTrack = masterTrack.addAutomationTrack(masterTrack.mixerGroup, "volume");
// 为增益效果的增益添加自动化轨道
var gainEffect = masterTrack.mixerGroup.effectChain.addEffect("GainEffect");
var automationTrack2 = masterTrack.addAutomationTrack(gainEffect, "gain");
为可自动化对象的给定属性创建一个自动控制器。返回自动控制器管理的对象。
例如:
var automator1 = sound.addAutomator("volume"); // 为声音的音量属性添加一个自动控制器
var automator2 = sound.addAutomator(sound.pitch); // 或者，该属性可以作为一个参数使用
为可自动化对象的给定属性创建调制器。modulatorType 参数确定调制器的实体类型，并且必须是 RandomizerModulator、ADSRModulator 或 SidechainModulator。返回调制器管理的对象。
例如:
var randModulator = sound.addModulator("RandomizerModulator", "volume"); // 为声音的音量属性添加一个随机调制器
var ahdsrModulator = sound.addModulator("ADSRModulator", sound.pitch); // 或者，该属性可以作为一个参数使用
在指定的 parameter 上创建一条自动控制曲线。参数 parameter 可以是一个 GameParameter，也可以是包含自动控制对象事件的 Timeline。返回自动控制曲线管理的对象。
例如:
// 在时间轴上为主轨道的音量添加一条自动控制曲线。
var event = studio.project.workspace.addEvent("New Event", true);
var mixerGroup = event.masterTrack.mixerGroup;
var automator = mixerGroup.addAutomator("volume");
var automationCurve = automator.addAutomationCurve(event.timeline);
// 在参数上为增益效果添加自动控制曲线
var gainEffect = mixerGroup.effectChain.addEffect("GainEffect");
var automator = gainEffect.addAutomator("gain");
var rpmParameter = studio.project.lookup("parameter:/RPM");
var automationCurve = automator.addAutomationCurve(rpmParameter.parameter);
在曲线上给定的 position 和 value 处创建一个自动控制点。position 必须在曲线参数的范围内，value 必须在自动控制属性的取值范围内。返回自动控制点管理的对象。
以字符串形式返回事件库的路径。
设置卷积混响效果的脉冲响应。文件路径必须是引用音频数据文件的绝对路径。
如果事件正在播放，则返回 true 。
如果事件暂停，则返回 true 。
如果事件正在停止，则返回 true 。
为启用录制的分析器会话返回 true 。
如果事件是 3D，则返回 true 。此数执行的计算需要将事件完全加载到内存中，如果在大量的事件上触发，速度可能会很慢。
如果事件是 oneShot，则返回 true 。此数执行的计算需要将事件完全加载到内存中，如果在大量的事件上触发，速度可能会很慢。
播放事件。相当于按下传输控件中的播放按钮。
切换事件的暂停。相当于按下传输控件中的暂停按钮。
立即停止事件，跳过停止状态。
停止事件。事件将进入停止状态。
如果在事件播放时调用，则将回放位置移动到光标位置。在事件停止时将光标位置移回时间轴的开头。
触发延留点的离键行为。
切换性能分析器会话的录制状态。
以字符串形式返回事件的路径。
返回表示当前试听的 3D 属性的对象:
radialDistance [number]azimuth [number]height [number]rotation [number]基于attributes对象设置当前试听的 3D 属性。attributes 对象的属性与Event.get3DAttributes()函数匹配。
以number形式返回光标位置。parameter 参数必须是 Timeline 或 GameParameter。
将光标位置设置为number。parameter 参数必须是 Timeline 或 GameParameter。
以number形式返回参数的回放位置。parameter 参数必须是 Timeline 或 GameParameter。
返回事件引用的所有GameParameter对象的Array。这包括任何隐式引用的参数。Array 的顺序与传输栏中显示的顺序相匹配。
向事件添加游戏参数。返回游戏参数管理的对象。parameterDefinition 参数可以是 ParameterPreset、GameParameter 或定义要创建参数的 Object:
name: 作为 string 的参数名称。type: studio.project.parameterType。min: 参数范围的最小值（number）。max: 参数范围的最大值（number）。将具有给定 name 的组轨道添加到事件中。返回组轨道管理对象。
将具有给定 name 的返回轨道添加到事件中。返回辅助轨道管理对象。
向事件添加标记轨道。返回标记轨迹管理对象。
返回指定的相对path中的项目。如果找不到该项目，则返回 undefined 。例如:
var event = studio.project.workspace.masterEventFolder.getItem("sfx/explosion_event");
以 number 形式返回全局游戏参数的光标位置。如果游戏参数的范围不是全局的，则返回 undefined。例如:
var globalParameterPreset = studio.project.lookup("parameter:/game_state/time_of_day"); // 返回一个 ParameterPreset 对象
var timeOfDay = globalParameterPreset.parameter.getCursorPosition();
将全局游戏参数的光标位置设置为 number。例如:
var globalParameterPreset = studio.project.lookup("parameter:/game_state/time_of_day"); // 返回一个 ParameterPreset 对象
globalParameterPreset.parameter.setCursorPosition(1300);
在指定的相对 path 处返回 MixerBus。如果找不到总线，则返回 undefined。例如:
var bus = studio.project.workspace.mixer.masterBus.getItem("sfx/player");
在指定的 parameter 上向轨道添加声音。soundType 参数确定声音的实体类型，并且必须是 SingleSound、MultiSound 或 ProgrammerSound。start 值必须在参数范围内。返回声音模块管理对象。
在给定的 position 处向轨道添加命名标记。返回命名标记管理对象。
在给定的 position 和给定的 length 处向轨道添加一个区域。可通过传入有效的 name 参数来设置区域的名称。如果 loopMode 为 undefined，则区域的循环模式默认为 project.regionLoopMode.Looping。如project.regionLoopMode枚举所述，可通过传入有效的 loopMode 参数来设置循环模式。返回区域管理对象。
在给定的 position 处向轨道添加过渡标记。可通过传入有效的 destination 参数来设置转换标记的目的地。destination 参数可以是 NamedMarker 或 LoopRegion。返回转换标记管理对象。
在轨道的给定 position 添加一个具有给定 length 的过渡区域。过渡区域的目的地可以通过传入有效的 destination 参数来设置。destination 参数可以是 NamedMarker 或 LoopRegion。返回过渡区域管理对象。
在给定的 position 处向轨道添加延留点。返回延留点管理对象。
返回指定的相对 path 中的 Asset。如果找不到该项目，则返回 undefined 。例如:
studio.project.workspace.masterAssetFolder.getAsset("music/level_01.wav");
以枚举形式返回 MixerBus 对象的有效输入格式。
以枚举形式返回 MixerBus 对象的有效输出格式。
创建效果并将其添加到该链的末尾。返回效果管理对象。effectDefinition 参数可以是 EffectPreset、预设的 MixerEffect 或以下字符串之一:
ThreeEQEffectChannelMixEffectChorusEffectCompressorEffectConvolutionReverbEffectDistortionEffectDelayEffectFlangerEffectGainEffectLimiterEffectMultibandEqEffectPitchShifterEffectSFXReverbEffectTransceiverEffectTremoloEffectHighpassEffectHighpassSimpleEffectLowpassEffectLowpassSimpleEffectParamEqEffectSpatialiserEffectObjectSpatialiserEffectLoudnessMeter以字符串形式返回总线或 VCA 的路径。
返回参数在关联事件上下文中的回放位置。
以字符串形式返回参数的路径。
在关联事件的上下文中以 number 形式返回光标位置。相当于调用 parameterProxy.event.getCursorPosition(parameterProxy.preset)。
在关联事件的上下文中将光标位置设置为 number。相当于调用 parameterProxy.event.setCursorPosition(parameterProxy.preset, position)。
将声音的淡入曲线设置为指定的 length 和 curveShape。如果声音上不存在淡入曲线，则会创建一条。如果 length 接近零，则不添加任何曲线 —— 如果该曲线有现有的淡入曲线，则将其删除。如果未提供 curveShape，则使用默认形状。
将声音的淡出曲线设置为指定的 length 和 curveShape。如果声音上不存在淡出曲线，则会创建一条。如果length 接近零，则不添加任何曲线 —— 如果曲线有现有的淡出曲线，则将其删除。如果未提供 curveShape，则使用默认形状。
在关联事件的上下文中以 number 形式返回光标位置。相当于调用 timeline.event.getCursorPosition(timeline)。
在关联事件的上下文中将光标位置设置为 number。相当于调用 timeline.event.setCursorPosition(timeline, position)。
将给定参数的参数条件添加到可触发对象。返回参数条件管理对象。parameter 参数可以是 ParameterPreset 或 GameParameter。使用 min 和 max 指定参数条件的范围。如果 max 为 undefined，则参数条件的最大值将设置为 min。对于带标签的参数，max 参数将被忽略。
例如:
var continuousCondition = loopRegion.addParameterCondition(studio.project.lookup("parameter:/Distance Parameter"), 0, 1000);
var labeledCondition = singleSound.addParameterCondition(studio.project.lookup("parameter:/Current Country"), "Australia");
labeledCondition = transitionMarker.addParameterCondition(studio.project.lookup("parameter:/Current Country"), "Australia");
labeledCondition = transitionRegion.addParameterCondition(studio.project.lookup("parameter:/Current Country"), "Australia");
将具有给定 name 的事件添加到项目的根文件夹。如果需要主轨道上的空间化效果器，则 withSpatializer 参数应为 true ，否则为 false 。返回事件管理对象。
向项目添加预设参数。parameterDefinition 对象的属性与Event.addGameParameter()函数匹配。返回预设参数管理对象。
将具有给定 name 的标签添加到项目中。如果该标签已存在于项目中，则将返回现有标签。返回标签管理对象。
创建插件效果或插件声音。identifier 参数确定用于创建的插件。这必须与FMOD_DSP_DESCRIPTION的名称匹配。返回插件效果或插件声音管理对象。