22. 参数引用

参数是一个事件属性，可用于触发和控制事件的发声器、逻辑标记和可自动控制属性，其值可由游戏代码设置。本章详细描述了每种类型参数的属性、设置和行为。

有关向事件添加参数以及参数在游戏中的可能用途的信息，请参阅创作事件一章的参数一节和参数一章。

预设参数的设置可在编辑参数对话框中更改。

编辑参数对话框

以下设置是大多数预置参数的通用设置。

参数类型(下拉菜单): 参数的类型有多种。每种类型都有不同的行为、设置和潜在的应用。有关特定参数类型的信息，请参阅本章的时间轴参数、用户参数和内置参数部分。
参数名称(文本字段): 预置参数的名称出现在参数浏览器和引用该预置参数的所有参数上。只有当多个预设参数位于不同的文件夹中时，才可以具有相同的名称。游戏可使用局部参数实例或全局预设参数的名称来获取和设置其值。有关获取和设置全局预置参数值的信息，请参见FMOD API 手册中studio::System::getparameterbyname和studio::System::setparameterbyname。有关获取和设置局部参数实例值的信息，请参见studio::eventinstance::getparameterbyname
范围(数字字段): 每个预设参数都有特定范围的可能值。如果参数设置为超出其范围的值，则改为设置为该范围内最接近的值。有关如何为特定类型的参数定义范围的信息，请参阅本章的时间轴参数、用户参数和内置参数部分。
参数范围(单选按钮): 预设参数的范围可以是局部的或全局的。全局参数的值由包含基于该预设的参数的每个事件实例共享。在包含基于该预设的参数的每个事件实例中，局部参数的值可以不同。
回放期间保持值(复选框): 参数的值可以在回放期间被保持。仅当事件实例未播放或暂停时，保留的本地参数的值才能设置为新值。这意味着可在事件实例开始之前设置该实例中的保持局部参数，但不能在它播放时设置。在任何情况下，游戏都不能将全局参数设置为新值。

出现在“编辑参数”对话框中的其他属性特定于某些类型的参数。

可在参数操作台中查看某些附加参数属性。

参数操作台

参数操作台可用于设定参数的当前值，以及预设参数的速度和寻道速度设置。

速度(表盘): 速度使参数的当前值以固定的速率不断上升或下降，直到达到参数的最小值或最大值。这允许参数随时间改变值，即使没有被设置为新值，也是如此。只有用户参数可以有速度。
单位: 单位每秒。
不对称(切换按钮): 将寻道速度设置为不对称可用于为预设参数指定单独的“上升”和“下降”寻道速度。当参数设置为较高值时，适用递增寻道速度，当参数设置为较低值时，适用递减寻道速度。
寻道速度(表盘): 当设置为新值时，寻道速度会使参数的当前值以固定速率上升或下降，而不是瞬间变化。这允许参数从一个值平滑地过渡到另一个值，而不是突然改变。将寻道速度设置为即时会导致参数值即时发生变化。仅当寻道速度不对称时，寻道速度转盘才会出现在操作台上。
单位: 单位每秒。
升序(数字框): 当设置为较高值时，增加寻道速度会导致参数的当前值以固定的速率上升，而不是瞬间变化。这允许参数从一个值平滑地过渡到另一个值，而不是突然改变。将升序寻道速度设置为即时会导致参数值立即增加。仅当寻道速度不对称时，升序数字框才会出现在操作台中。
单位: 单位每秒。
降序(数字框): 当设置为较低值时，降序寻道速度会导致参数的当前值以固定速率下降，而不是瞬间变化。这允许参数从一个值平滑地过渡到另一个值，而不是突然改变。将降序寻道速度设置为即时会导致参数值立即减少。如果寻道速度不对称，降序数字框仅出现在甲板上。
单位: 单位每秒。

当参数同时受寻道速度和速率影响时，将参数设置为新值会导致参数以其寻道速度指定的速率渐变到该值，然后以其速率指定的速率继续移动。

预设参数的每个属性和设置在基于该预设参数的所有参数之间共享。

22.1 时间轴参数

与所有其他参数类型不同，时间轴不引用预设参数，并且无法使用编辑参数对话框创建或更改。时间轴可以包含逻辑标记，但不能用于发声器的参数触发条件或逻辑标记。

逻辑标记

一个事件最多只能包含一个时间轴参数。时间轴不能命名。

时间轴的最小值始终为 0。时间轴的最大值基于该参数上最右边的逻辑标记或工具。时间轴的初始值始终为 0。

时间轴参数总是范围中的局部的，时间轴的值不能是被调制或被自动控制的。

当包含该参数的事件实例正在播放时，时间轴的值会自动前进，除非其当前值达到延音点。时间轴前进的速度由事件的音高属性缩放，该属性位于事件的宏绘制器。

事件宏控件

游戏代码可以使用Studio::EventInstance::getTimelinePosition和 [Studio::EventInstance::setTimelinePosition] 获取和设置时间轴的值 (%api%studio-api-eventinstance.html#studio_eventinstance_settimelineposition)。

如果非持久事件实例的时间轴达到最大值并且该事件实例中没有其他内容正在播放，则该实例自动进入停止[播放状态] (advanced-topics.html#play-state)。

22.2 用户参数

用户参数是可以自定义以表示游戏中任何变量的参数。与内置参数和时间轴参数不同，用户参数不会自动更新，必须由游戏代码设置或通过自动控制或调制器进行调整。

以下设置是预设用户参数的通用设置，可在编辑参数对话框中更改。

初始值（文本字段或下拉菜单）: 每个用户参数都有一个默认设置的初始值。当游戏初始化 FMOD Studio 系统时，每个全局参数都设置为其初始值。本地参数的每个新实例在创建时都设置为参数的初始值。
通过事件工具递归公开（复选框）: 递归公开的参数会隐式添加到存在该参数的任何引用事件的父项事件。如果参数同时存在于引用事件和该事件的父项事件中，则这些参数会自动共享相同的值，除非事件发声器的参数属性是自动控制的。这可用于通过在父项事件中设置参数来设置被引用事件中的参数值。未递归公开的参数不会隐式添加到父项事件，但可以手动添加到父项事件，或者由该父项事件中的自动控制或调制器控制。此属性仅针对局部参数出现，因为无论它们出现在什么事件中，都可以设置全局参数。
只读（复选框）: 只读参数的值不能由游戏代码设置，但仍可由自动控制和调制控制。将参数设置为只读可以更轻松地判断在 FMOD Studio 中试听事件时应该由游戏代码设置哪些参数。

22.2.1 连贯型用户参数

连贯型用户参数使用浮点（十进制）数。

每个连贯参数都有一个定义其范围的最小值和最大值，并且可以设置为该范围内的任何浮点值。

连贯参数的初始值可以是其范围内的任意浮点数。

22.2.2 名称型用户参数

名称型用户参数使用字符串（标签）而不是数值。可在编辑参数对话框中查看和编辑名称型参数的标签。

标签（标签浏览器）: 每个名称型参数都有一个预定义的标签值列表，构成其范围，并且可以设置为该范围内的任何值。

参数标签

名称型参数的范围自动从其标签派生，并且始终为 0 到 n，其中 n 是其最后一个标签的索引。可以在编辑参数对话框中查看与每个标签关联的值。

名称型参数的初始值可以是其范围内的任何标签。

22.2.3 离散型用户参数

离散型用户参数使用整数（整数）。

每个离散参数都有一个定义其范围的最小值和最大值，并且可以设置为该范围内的任何整数值。

名称型参数的初始值可以是其范围内的任何整数。

22.3 内置参数

内置参数是其值会根据游戏引擎中事件实例和听者的3D属性自动更新的参数。

在 FMOD Studio 中试听时，可通过在3D 预览工具中移动事件实例，或在编辑器中改变其内置参数的值来改变试听事件实例的 3D 属性。

内置参数始终是范围的局部。

有关向事件添加参数的信息，请参阅“创作事件”章节的参数部分。

为了在游戏代码中设置事件实例位置和听者位置，FMOD Studio 使用 3D 笛卡尔坐标系，其中 x 和 z 轴用于描述水平面，x 和 y 轴用于描述垂直面。

有关如何在游戏代码中设置 3D 属性的更多信息，请参见FMOD API用户手册中的Studio::EventInstance::set3DAttributes and Studio::System::setListenerAttributes。

XYZ

以下是本节中使用的所有图表的图例。

内置参数图例

22.3.1 距离

距离参数类型表示听者和事件实例之间的距离。该参数使用与游戏引擎相同的距离单位。

每个距离参数都有一个最小值和最大值，并自动设置为事件实例和最近的听者之间的距离。该范围可以定制。值为 0 时，事件实例最接近听者。值越高代表距离越大。

在事件编辑器窗口中试听时，将3D 预览中的事件实例移向或移离听者会更改事件的距离参数值。

请注意，由System::set3DSettings中的 distancefactor 属性设置的游戏的距离系数对距离参数计算的距离没有任何影响。经计算的距离基于设置听者位置和事件实例时使用的单位。

距离参数

22.3.2 距离(标准化)

距离(标准化)参数类型表示听者和事件实例之间的距离。与距离参数类型不同，距离(标准化)参数类型不使用与游戏引擎相同的距离单位，并且没有可设置的最小值和最大值。它的范围是从 0 到 1，其中 0 表示使用该参数的事件的最小距离属性，1 表示该事件的最大距离属性。

每个距离(标准化)参数都自动设置为与事件实例和最近的听者之间的距离相对应的值。如果事件实例和发射器之间的游戏距离单位距离小于或等于事件的最小距离属性，则距离（标准化）参数设置为 0；如果游戏距离单位中的距离大于或等于事件的最大距离属性，则距离（标准化）参数设置为 1；如果游戏距离单位中的距离介于事件的最小距离和最大距离之间，则距离（标准化）参数设置为(d-i)/(a-i)，其中d 是事件实例与以游戏单位表示的最近的听者之间的距离，i是事件的最小距离属性，a 是事件的最大距离属性。

在事件编辑器窗口中试听时，将3D预览中的事件实例移向或移离监听器会更改事件的距离(标准化)参数的值。

22.3.3 方向

方向参数类型是听者所面对的方向与从听者到事件实例的方向之间的角度，并以度为单位。

方向参数的最小值为 -180，最大值为 180。每个都自动设置为听者面对的方向与水平面上从听者到事件实例的方向之间的角度。0° 位于听者正前方，-180°；或 180° 位于正后方，-90°；位于听者的左侧， 90°；位于听者的右侧。方向参数仅考虑听者的水平 (xz)平面。

方向参数与事件锥角参数不同，方向参数是基于从听者到事件实例的方向，而事件锥角参数是基于从事件实例到听者的方向。

在事件编辑器窗口中试听时，在3D 预览中围绕听者移动事件实例会改变方向参数的值。

方向参数

22.3.4 仰角

仰角参数类型是听者所面对的方向与垂直方向 (xy)上从听者到事件实例的方向之间的角度平面，以度为单位。

每个仰角参数的最小值为 -90，最大值为 90，并自动设置为由听者的前向和左向量形成的平面（称为“听者的水平面”）与听者之间的向量之间的角度和事件实例。0°时是指听者的水平面与听者和事件实例之间的向量相匹配。90°是指听者的水平面直接在听者和事件实例之间的向量下方时（即事件实例在听者上方），并且在 -90°；就是听者的水平面直接位于听者的正上方（即事件实例位于听者下方）。仰角不考虑听者是否正在查看事件实例。

仰角参数可用于事件实例在听者上方或下方听起来不同的重要情况，例如当玩家在第一次世界大战时期的双翼飞机上时。

在事件编辑器窗口中试听时，将3D预览中的事件实例移动到听者上方或下方会更改仰角参数的值。可通过按住 Ctrl 键并拖动事件实例来执行此操作。

仰角参数