Wwise SDK 2023.1.6
|
Wwise Authoring Query Language (WAQL) 方便查询 Wwise 工程及其对象。如需进一步了解 WAQL 中的各种概念,请参阅 使用 Wwise Authoring Query Language (WAQL) 章节。 查询具有以下几种形式:
概览 | 说明 |
$ SOURCE |
SOURCE 为对象生成器,其会输出对象序列。有关不同查询源的详细信息,请参阅下表。 TRANSFORM 为序列转换。其会接收输入序列,并输出另一序列。 注意:若未指定源,则将工程中定义的所有对象隐式设为查询源。 |
Specify the starting point of the query.
SOURCE | Query Source | IntegrationDemo 工程中所要执行的 WAQL 查询 |
---|---|---|
from object OBJECT_SPECIFIER |
从指定的对象生成对象序列。 OBJECT_SPECIFIER 具有以下几种形式:
|
$ from object "\Actor-Mixer Hierarchy\Default Work Unit\Hello" |
from type OBJECT_TYPE from type OBJECT_TYPE, OBJECT_TYPE, ... |
从指定的类型生成对象序列。可指定一种或多种对象类型。 OBJECT_TYPE 为 Wwise 对象类型。有关对象类型的完整列表,请参阅 Wwise 对象参考 章节。该类型不区分大小写。
|
$ from type Event |
from query QUERY_SPECIFIER |
从 Query Editor 中所定义 Wwise Query 的执行结果生成对象序列。 QUERY_SPECIFIER 具有以下几种形式:
注意:此生成器要求内存分配大小等于所生成序列的大小。 |
$ from query "\Queries\Factory Queries\Audio Source\Audio Source - Format = Vorbis" |
from search TEXT |
从整个工程的文本搜索结果生成对象序列。 TEXT 为前后加双引号的文本字符串。将搜索文本中指定的每个单词与工程对象内的单词匹配。 注意:结果与 Wwise 工具栏搜索相同。 |
$ from search "gun" |
from project | 生成包含工程中所有对象的对象序列。 | $ from project |
Change a sequence of objects into another one.
TRANSFORM | 可联用的转换 | 示例 |
---|---|---|
where BOOLEAN_EXPRESSION |
对输入序列的对象进行筛选,并滤掉那些与指定表达式不匹配的对象。 BOOLEAN_EXPRESSION 为可返回 true 或 false 的表达式。针对输入队列的每个对象执行该表达式,并滤掉那些表达式返回结果为 false 的对象。 有关详细信息,请参阅表达式部分。 |
$ from type Sound where @Volume < 0 |
skip COUNT |
跳过输入序列中指定数量的对象,然后返回其余对象。 COUNT 为所要跳过的元素数量。 | $ from type Sound skip 10 |
take COUNT |
从输入序列的开头连续返回指定数量的对象。 COUNT 为所要返回的元素数量。 | $ from type Sound take 10 |
select OBJECT_EXPRESSION |
将输入序列的各个对象转换为新的形式。 OBJECT_EXPRESSION 为可返回零到多个对象的表达式。针对输入队列的每个对象执行该表达式,并将表达式的结果转换为新的序列。 有关详细信息,请参阅表达式部分。 |
$ from object "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}" select parent |
orderby VALUE_EXPRESSION orderby VALUE_EXPRESSION reverse |
按升序顺序排列并返回输入序列的对象。若要按降序顺序排列,请在表达式之后添加 reverse。 VALUE_EXPRESSION 为用于结合排序算法对对象进行比较的表达式。该表达式必须返回可比较值,如字符串、数字值或布尔值。 注意:orderby 要求内存分配大小等于输入序列的大小。 | $ from type Sound orderby name $ from type Sound orderby name reverse $ from type Bus orderby @BusVolume $ from type Action orderby @Target.name |
distinct |
仅返回输入序列的独特对象。重复的对象条目将被合并为一个条目,确保序列中的每个对象都是唯一的。 注意:distinct 会改变序列的顺序。为此,最好将 orderby 语句放在 distinct 语句之后。 注意:distinct 要求内存分配大小等于输入序列的大小。 |
$ from object "\Actor-Mixer Hierarchy" select descendants select @OutputBus distinct |
Select other objects, or values associated with the objects, in the sequence.
对象表达式 | 可返回零到多个对象的表达式 | 示例 |
---|---|---|
OBJECT_EXPRESSION OBJECT_EXPRESSION.OBJECT_EXPRESSION... | 可使用零到多个对象表达式来返回 Wwise 对象。使用点号分隔各个表达式。 | $ from object "Event:Play_Hello" select parent.parent |
REFERENCE_NAME @REFERENCE_NAME @@REFERENCE_NAME |
返回被当前对象引用的对象以获取特定引用名称。 若使用 @,则使用对象上直接定义的引用。 若不用 @,则使用 Override 设置查找引用值。该值为播放时所用的实际值。若存在同名的访问器,则优先使用该值;在这种情况下,须在引用名称之前使用 @@。 REFERENCE_NAME 为当前对象的引用名称。有关对象类型及相关引用的完整列表,请参阅 Wwise 对象参考 章节。该名称不区分大小写。 |
$ from type Sound select OutputBus |
children | 返回对象的直接子对象 (children)。 | $ from object "\Actor-Mixer Hierarchy\Default Work Unit" select children |
descendants |
返回单个序列中所含对象的全部下级对象 (descendant)。这些下级对象包括所有以递归方式获取的子对象。 注意:不包含当前对象。若要包含当前对象,请使用 select descendants, this。 |
$ from object "\Actor-Mixer Hierarchy\Default Work Unit" select descendants |
this | 返回当前对象。 | $ from object "\Master-Mixer Hierarchy\Default Work Unit\Master Audio Bus" select this, descendants |
parent | 返回对象的直接父对象 (parent)。若对象没有父对象,则不返回任何对象。 |
$ from type Sound select parent |
ancestors |
返回单个序列中所含对象的全部上级对象 (ancestor)。这些上级对象包括所有以递归方式获取的父对象。 注意:不包含当前对象。若要包含当前对象,请使用 select ancestors, this。 | $ from object "Event:Play_Hello" select ancestors $ from object "Event:Play_Hello" select ancestors, this |
referencesTo | 返回所有引用当前对象的对象。 |
$ from type Effect select referencesTo |
owner |
返回对象的所有者。仅其他对象之内定义的 Custom 对象设有所有者。 Shareset 对象没有所有者。它们有父对象 (parent) 和引用它们的对象 (referencesTo)。 比如,Custom 效果器的所有者为以其作为插入效果器的对象。 | $ from type Effect select owner |
randomizer("<strong>PROPERTY_NAME</strong>") |
Returns the randomizer object associated with the specified property. Use the following properties on the randomizer object: min, max, enabled. PROPERTY_NAME 为当前对象的属性名称。Refer to Wwise 对象参考 for the complete list of object types and their properties. 该名称不区分大小写。 | $ from type sound where randomizer("pitch") != null |
workunit | 返回用于保存当前对象的 Work Unit 对象。 | $ from type Effect select workunit |
musicTransitionRoot |
(DEPRECATED) Returns the Music Transition root object associated with the current object. This is deprecated. The TransitionRoot reference should be used instead. 注意:该表达式仅适用于 MusicSegment、MusicTrack、MusicPlaylistContainer 和 MusicSwitchContainer 类型的对象。 | $ from project select musicTransitionRoot |
musicPlaylistRoot |
(DEPRECATED) Returns the Music Playlist root object associated with the current object. This is deprecated. The PlaylistRoot reference should be used instead. 注意:该表达式仅适用于 MusicPlaylistContainer 类型的对象。 | $ from project select musicPlaylistRoot |
maxDurationSource |
Returns a JSON object containing the id of the Audio Source object that has the maximum playback duration (in seconds) for all descendants of the current object. The JSON object also includes the maximum duration value itself. 注意:该表达式仅适用于 Actor-Mixer Hierarchy、Interactive-Music Hierarchy 和 Event 对象。 | $ from object "\Actor-Mixer Hierarchy" select maxDurationSource |
maxDurationSourceObject |
返回当前对象的所有下级对象中播放时长(秒)最长的 Audio Source 对象。 注意:该表达式仅适用于 Actor-Mixer Hierarchy、Interactive-Music Hierarchy 和 Event 对象。 | $ from object "\Actor-Mixer Hierarchy" select maxDurationSource |
maxRadiusAttenuation |
Returns a JSON object containing the id of the attenuation object that has the maximum radius distance in all descendants of the current objects. The JSON object also contains the maximum radius distance value itself. 注意:该表达式仅适用于 Actor-Mixer Hierarchy、Interactive-Music Hierarchy 和 Event 对象。 | $ from type Sound select maxRadiusAttenuation |
maxRadiusAttenuationObject |
返回当前对象的所有下级对象中半径距离最长的衰减对象。 注意:该表达式仅适用于 Actor-Mixer Hierarchy、Interactive-Music Hierarchy 和 Event 对象。 | $ from type Sound select maxRadiusAttenuation |
audioSourceLanguage |
返回用于当前 Audio Source 的语言对象。 注意:该表达式仅适用于 Audio Source 对象。 | $ from type AudioFileSource select audioSourceLanguage |
switchContainerChildContext |
返回与当前 Switch Container 对象关联的 Switch Container 上下文对象。Switch Container 上下文对象存有有关 Switch Container 关联的设置。 注意:该表达式仅适用于 SwitchContainer 类型的对象。 | $ from project select switchContainerChildContext |
数值表达式 | 可返回数字值、字符串或布尔值的表达式 | 示例 |
OBJECT_EXPRESSION.VALUE_EXPRESSION OBJECT_EXPRESSION.OBJECT_EXPRESSION. VALUE_EXPRESSION | 可使用零到多个对象表达式,并后跟数值表达式,来返回联用对象的值。使用点号分隔各个表达式。 | $ where OutputBus.id = "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}" |
PROPERTY_NAME @PROPERTY_NAME @@PROPERTY_NAME |
返回特定对象的属性值。 Without the @, the override settings are used to find the property value. 该值为播放时所用的实际值(即有效值)。If there is an accessor of the same name, it will take precedence; in those rare cases, @@ must be used before the property name. 若使用 @,则使用对象上直接定义的属性(即便没有覆盖)。 @@ 等同于不用 @。 PROPERTY_NAME 为当前对象的属性名称。Refer to Wwise 对象参考 for the complete list of object types and their properties. 该名称不区分大小写。 |
$ from type Sound where volume < 0 |
id |
以 "{0CB93450-E995-40E5-98A5-239F15B1F1D4}" 形式返回 128 位 GUID。 该 GUID 为工程中对象的唯一标识符。 | $ where id = "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}" |
shortId |
返回对象的 32 位短 ID 数字值。该 ID 将用在声音引擎中。 注意:唯一短 ID 对应的值域取决于对象类型。对于某些对象类型(如 Bus、Events、Effect 和 Game Sync),只有同一类型的所有对象使用唯一的 ID。对于其他对象类型(如 Sound 和 Container),则在整个工程中使用唯一的 ID。 | $ where shortId = 1588715066 |
name | 以字符串形式返回对象的名称。 | $ from type Event where name : "*hello*" $ where name = "Play_Hello" |
notes | 以字符串形式返回对象的注释(也叫备注)。 |
$ where notes : "audiokinetic" |
type |
以字符串形式返回对象的类型。 有关对象类型的完整列表,请参阅 Wwise 对象参考 章节。 | $ where type = "Sound" |
nodeType |
Returns the type of the node as a string. Refer to Wwise Nodes Reference for the complete list of node types. |
$ where nodeType = "Sound SFX" |
classId |
返回对象的 classID。classID 是一个代表对象类型和效果器/源/转码插件类型的数字值。 有关 classID 的完整列表,请参阅 Wwise 对象参考 章节。 | $ where classId = 8847363 |
category |
返回对象的类别。 可将工程根文件夹下的顶层文件夹名称用作类别。 | $ where category = "Actor-Mixer Hierarchy" $ where category = "Interactive Music Hierarchy" $ where category = "Master-Mixer Hierarchy" $ where category = "Events" |
filePath | 返回与 Work Unit 或工程关联的文件路径。该路径为 wwu 或 wproj 文件的绝对路径。 | $ where type = "WorkUnit" and filePath : "*wwu" |
path | 返回 Wwise 工程内的工程路径。该路径包含类别(即顶层文件夹名称)。 | $ where path : "microphone" |
activeSource | 返回与声音对象关联的活跃音频源。 | $ from type Sound select activeSource |
isPlayable | 若对象可在 Transport 中或 Event 内播放,则返回 true。否则,返回 false。 | $ where isPlayable $ where isPlayable = false $ where !isPlayable |
childrenCount | 返回当前对象的子对象数量。 | $ where childrenCount > 10 $ where type = "RandomSequenceContainer" and childrenCount > 5 |
pluginName |
返回插件供应商提供的插件名称。 插件名称适用于效果器插件、源插件、音频设备和元数据对象。 注意,插件名称不同于对象名称。 | $ where pluginName = "" |
convertedFilePath |
返回与当前对象关联的转码后文件的绝对路径。 注意:该表达式仅适用于 Sound 和 AudioSource 类型的对象。 | $ from type Sound where convertedFilePath : "hello" |
originalFilePath |
返回与当前对象关联的原始文件的绝对路径。 Note: This only works with objects of type Sound, AudioSource, Music Clip and Music Clip MIDI. | $ from type Sound where originalFilePath : "hello" |
originalRelativeFilePath |
Returns the path of the original file associated with the current object, relative to the project's Originals folder. Note: This only works with objects of type Sound, AudioSource, Music Clip, and Music Clip MIDI. | $ from type Sound where originalFilePath : "hello" |
soundbankBnkFilePath |
返回与当前对象关联的 BNK 文件的绝对路径。 注意:该表达式仅适用于 SoundBank 类型的对象。 | $ where soundbankBnkFilePath : "car" |
mediaId |
Unique value given to file. Used by the sound engine to identify the file. Note: This only works with objects of type AudioSource, MidiFileSource and PluginMediaSource. | $ where mediaId > 0 |
conversionHash |
The hash of everything in the project that affects a file's conversion (Conversion ShareSet, file modifications in the Source Editor, and so on). Note: This only works with objects of type AudioSource, MidiFileSource and PluginMediaSource. | $ where conversionHash > 0 |
contentHash |
The hash of the conversionHash and the hash of the original file's contents. Note: This only works with objects of type AudioSource, MidiFileSource and PluginMediaSource. | $ where contentHash != "" |
workunitIsDefault |
若 Work Unit 对象为该类别的 Default Work Unit,则返回 true。 注意:该表达式仅适用于 WorkUnit 类型的对象。 | $ where workunitIsDefault |
workunitType |
返回当前 Work Unit 对象的类型。其可为以下数值:
注意:该表达式仅适用于 WorkUnit 类型的对象。 |
$ where workunitType = "folder" |
workunitIsDirty |
若 Work Unit 有未保存的更改,则返回 true。 注意:该表达式仅适用于 WorkUnit 类型的对象。 | $ where workunitIsDirty |
isExplicitMute |
若对象被显式设为了 Mute 状态,则返回 true。 | $ where isExplicitMute |
isExplicitSolo |
若对象被显式设为了 Solo 状态,则返回 true。 | $ where isExplicitSolo |
isImplicitMute |
若对象被隐式设为了 Mute 状态,则返回 true。 | $ where isImplicitMute |
isImplicitSolo |
若对象被隐式设为了 Solo 状态,则返回 true。 | $ where isImplicitSolo |
isIncluded |
Returns true if the object is included. If one or more of the object's ancestors is excluded, the object is excluded as well. | $ where isIncluded |
stateProperties |
Returns which properties are used for the states of the associated object. This represents the visible columns in the States tab. The return is a list of strings. Note: This can only be used in a return expression. | |
stateGroups |
Returns which state groups are used for the states of the associated object. This represents the state groups added in the States tab. The return is a list of objects. Note: This can only be used in a return expression. | |
validity |
Returns a JSON object representing the status of validity. There are 3 fields in the object: isValid (boolean), details (string), severity (string). The details and severity fields are only available when isValid is false. This can be used with Effect Slots, Events and Actions. | $ where validity.isValid |
maxDurationSource.id |
返回时长最长的 Audio Source 对象的 ID (GUID)。 | $ where maxDurationSource.id = "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}" |
maxDurationSource.trimmedDuration |
返回修剪的最长音频源的时长(秒)。 | $ where maxDurationSource.trimmedDuration >= 2 |
duration.min |
返回播放操作可能花费的最小时长。 注意:此项适用于可包含 Audio Source 对象的所有对象(以源的形式直接实现,或通过下级对象间接实现)。 | $ where duration.min = 3 |
duration.max |
返回播放操作可能花费的最大时长。 注意:此项适用于可包含 Audio Source 对象的所有对象(以源的形式直接实现,或通过下级对象间接实现)。 | $ where duration.max = 5 |
duration.type |
返回时长的类型(可为 Infinite、Mixed、OneShot 或 Unknown)。 | $ where duration.type = "oneShot" |
loudness.integrated |
Returns the integrated loudness measurement in LUFS for the entire associated audio file. | $ from type sound where loudness.integrated > -14 |
loudness.momentaryMax |
Returns the momentary max measurement in LUFS for the associated audio file. The value represents the highest loudness value obtained with a very short (100ms) window evaluation. | $ from type sound where loudness.momentaryMax > -14 |
audioSourceTrimValues.trimBegin |
返回修剪的音频源的时间范围的起点。 | $ where audioSourceTrimValues.trimBegin = 2 |
audioSourceTrimValues.trimEnd |
返回修剪的音频源的时间范围的终点。 | $ where audioSourceTrimValues.trimEnd = 5 |
maxRadiusAttenuation.id |
返回半径最长的 Attenuation 对象的 ID (GUID)。 注意:该表达式仅适用于 Actor-Mixer Hierarchy、Interactive-Music Hierarchy 和 Event 对象。 | $ where maxRadiusAttenuation.id = "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}" |
maxRadiusAttenuation.radius |
返回半径最长的 Attenuation 对象的半径。 注意:该表达式仅适用于 Actor-Mixer Hierarchy、Interactive-Music Hierarchy 和 Event 对象。 | $ where maxRadiusAttenuation.radius > 100 |
Perform conditional logic or select specific elements on all items of the list at once. You can use list functions on object lists and other lists provided by WAQL, such as children, descendants, ancestors, and referencesTo.
Refer to Wwise 对象参考 to learn more about the object lists available in the different object types.
List Functions | 说明 | 示例 |
---|---|---|
count | Returns the number of items in the list that match the specified condition, otherwise returns false. The condition statement is optional. | $ where children.count() > 3 $ where effects.count(effect.pluginname:"eq") > 0 |
any | Returns true if any items match the condition, otherwise returns false. Returns false if empty. The condition statement is optional. | $ where rtpc.any() $ where children.any(type = "Sound") |
all | Returns true if all items in the list match the specified condition, otherwise returns false. Returns false if empty. The condition statement is mandatory. | $ where children.all(type = "Sound") |
first | Returns the first item thats matches the specified condition. The condition statement is optional. | $ where effects.first(effect.pluginname :"EQ") != null $ where children.first().type = "Sound" |
last | Returns the last item that matches the specified condition. The condition statement is optional. | $ where effects.last(effect.pluginname :"EQ") != null $ where children.last().type = "Sound" |
take | Takes the specified number of items, and returns them in a new list. | $ select children.take(2) |
skip | Skips the specified number of items, and returns the rest in a new list. | $ select effects.skip(1) |
at | Returns the item at the specified index in the list. | $ select effects.at(0) |
where | Returns the items that match the specified condition in a new list. | $ select effects.where(effect.pluginname :"EQ") |
Evaluate a boolean expression and return true or false.
条件运算符和逻辑运算符 | 说明 | 示例 |
---|---|---|
= | 对两个值进行比较;可为字符串、数字值或布尔值。 |
$ where name = "Hello" |
!= | 对两个值进行比较;可为字符串、数字值或布尔值。 |
$ where name != "Hello" |
< | 对两个数字值进行比较。 |
$ from type sound where volume < 0 |
: |
对两个字符串值进行比较,单词部分匹配即返回 true(以指定文本为开头)。 同时,还可使用通配符来与单词的结尾进行匹配。 |
$ where name : "Hello" |
= /REGEX/ |
若指定的正则表达式与当前字符串匹配,则返回 true。 使用 ECMAScript 正则表达式。 | $ where name = /Hello/ $ where name = /llo$/ $ where name = /[a-z][0-9]/ |
! | Negates an expression. |
$ where !(name = "Hello") |
以及 | 将两个表达式联用并取同时符合两个条件的值。 |
$ from type sound where name = "Hello" and volume = 0 |
或者 | 将两个表达式联用并取符合其中任一条件的值。 |
$ where name = "Hello" or name = "Hi" |
() | 指定多个表达式的逻辑运算顺序。 |
$ from type sound where (volume = -3 or volume = 0) and (name = "Hello" or name = "Hi") |
Perform complex data manipulations.
概览 | 说明 | 示例 |
---|---|---|
OBJECT_EXPRESSION.{EXPRESSION1,EXPRESSION2,...} |
Composition operator. Returns a new JSON object composed of the enumerated expressions. The enumerated expressions become keys on the resulting objects, with corresponding values. You can use this operator to control which elements to obtain on Wwise objects. Note: This operator can only be used in return expressions. |
$ from type sound $ from type audiofilesource where markers.any() $ from type event |
OBJECT_EXPRESSION.[EXPRESSION1,EXPRESSION2,...] |
Concatenation operator. Returns a new list, which is the concatenation of the enumerated lists or objects. |
$ from type randomsequencecontainer |
EXPRESSION as NAME |
Alias keyword. Renames the specified expression to another name, which becomes the key in the results. You can use this keyword to rename complex assessors. Note: This keyword can only be used in return expressions. |
$ from type sound $ from type event |