版本
menu_open
Wwise SDK 2023.1.3
查询 Wwise 工程

Wwise Authoring API 提供了综合查询系统，可用于获取 Wwise 工程最关键方面的信息。 更具体地说，它用于获取工程中任何对象的信息。

该查询系统内置于 ak.wwise.core.object.get 功能里。请参阅它的参考文档了解更多详情。

查询可分为 2 种不同的形式：

备注: 建议使用 WAQL 而非 JSON 查询格式。WAQL 具有更强的功能和适用性，可更好地处理错误且更加易于使用。

WAQL 查询

WAQL 查询允许在一行文本中指定整个查询。

技巧: WAQL 查询还可直接用在 Wwise 设计工具内以供测试。这样非常方便在整合到 WAAPI 程序或脚本中之前验证查询语法和结果。比如，您可以在 Wwise 工具栏或 List View 搜索字段中键入以下 WAQL 查询：
$ from type Event

详细了解 WAQL：

JSON 查询

备注: 不建议使用 JSON 查询，最好使用 WAQL 查询。请参阅 使用 Wwise Authoring Query Language (WAQL) 和 WAQL 快速入门 。

JSON 查询包含两个部分：

  • from： 指定查询的起点。这是获取数据的来源。
  • transform： 指定应用于对象的一系列转换。可以按次序添加转换。

此外，查询可以用选项指定：

  • return： 指定从对象返回的内容。如果没有指定，则默认值为 ['id', 'name']。
  • platform： 指定使用查询的平台。如果没有指定，则默认为当前平台

from

from 语句为查询开始提供了几个起点：

  • id： 指定: 指定一列对象 ID（GUID）。当您已经有对象 ID 时，可用于查找该对象。
  • name： 按照 type:name 形式指定一组由对象类型限定的对象名称。仅支持采用全局唯一名称的对象类型。请参阅 Wwise 对象参考 了解可用类型。
  • search： 指定在 Wwise 对象和备注中要搜索的文本。这与 Wwise 中的搜索功能所用的搜索引擎是一样的。
  • path： 指定要查找的一系列路径。路径必须是绝对路径，并且必须以类别名称开头，就相当于物理文件夹名称。例如： \Actor-Mixer Hierarchy\Default Work Unit\MySound。
  • ofType： 指定一系列 Wwise 对象类型。用于获取某个对象类型的所有对象。例：获取所有 Game Parameters。请参阅 Wwise 对象参考 了解可用类型。

transform

transform 语句提供了几个转换功能，可以用于转换已选择的对象。第一个转换是应用于 from 语句所选择的对象的。另一个 transformation 应用于之前转换的结果。

可以按次序添加多个转换。

  • select parent： 为每个对象选择父级对象。
  • select children： 为每个对象选择子级对象列表。
  • select descendants： 为每个对象递归选择所有子级对象。
  • select ancestors： 为每个对象递归选择父级对象。
  • select referencesTo： 为每个对象选择所有引用该对象的对象。
  • where： 用于过滤之前迭代器的结果。可能的标准是：
    • name:contains： 对对象名称中文本的搜索，不区分大小写。
    • name:matches: 对对象名称的正则表达式搜索，不区分大小写。
    • type:isIn： 筛选之前迭代器的结果，仅保留特定类型的对象。如需查看对象类型列表，请参阅 Wwise 对象参考 。
    • category:isIn： 筛选之前迭代器的结果，仅保留特定类别的对象。
  • distinct： 筛选之前迭代器的结果，仅保留独特的对象。

返回选项

return 表达式用于指定所要返回的 Wwise 对象元素。可以返回任意数量的要素。

return 表达式可能包含：

属性和引用名称可选用以下两种前缀：

  • '@PROPERTYNAME'：返回直接在对象上设置的值。这种情况下会忽略重写系统，并且可能会返回未使用和隐藏的值。
  • '@@PROPERTYNAME'：返回重写系统所解析的值。这种情况下可能会返回从父对象继承的值或直接返回对象的值（如对象不沿用属性）。

若未使用任何前缀，则返回重写系统所解析的值。其效果跟使用 @@ 前缀相同。此时建议不使用前缀。

示例：

  • 'volume'、'Volume'、'@Volume'、'@@Volume'：返回对象的音量。因为音量不可重写，所以这些前缀的效果都是一样的。注意，属性名称不区分大小写。
  • 'OutputBus'、'outputbus'、'@@OutputBus'：返回重写系统所解析的 Output Bus（使用 Override Parent）。该值在播放时使用。注意，引用名称不区分大小写。
  • '@OutputBus'：返回直接在对象上设置的 Output Bus。该值同时保留用于与此对象关联的 Work Unit。若对象未选中 Override Parent 选项，则可能会不使用并隐藏该值。

在表达式解析为有效引用时，可进一步查询被引用对象的属性。 比如，若 Sound 对象的 'UserAuxSend0' 引用了现有 Auxiliary Bus，则可通过附加点号 ('.') 并后缀属性描述符来查询此 Auxiliary Bus 的属性。因此，如需查询被引用 Auxiliary Bus 的 Attenuation，直接使用 'UserAuxSend0.Attenuation' 即可。

示例：

  • OutputBus.name：返回输出总线的名称。
  • parent.name：返回父对象的名称。
  • parent.parent.type：返回祖对象的类型。
  • OutputBus.Volume：返回输出总线的音量。
  • OutputBus.Attenuation.name：返回输出总线的名称。
  • Attenuation.path：返回输出总线的路径。
  • Effects.first.effect.id: returns the ID of the first Effect.

有些对象包含带有特定功能（如随机化）的属性。为了检索与这些功能相关的值，可通过类似函数的访问器来查询与属性绑定的特殊对象。比如，随机化器功能由绑定到对象特定属性的 Modifier 对象描述。此对象可作为 'randomizer("PropertyName")' 来查询，其中 PropertyName 为属性（如 'Volume'）的名称。 在访问器提供有效引用时，可按照前文所述方式进一步查询返回的对象。比如，可按照以下方式获取 Volume 随机化器的 'Max' 属性：'randomizer("Volume").@Max'。

可用的访问器包括：

  • randomizer

如果返回表达式中的一个条目不兼容或不在返回对象中，则结果将不含该条目。

其他选项

ak.wwise.core.object.get 函数及其他函数允许使用选项对象来定义：

  • return 语句（参见上文）
  • platform：平台的 ID (guid) 或名称。
  • language：语言的 ID (guid) 或名称。

有些访问器会区分选项。比如，在检索属性或引用值时，可通过指定平台来获取取消链接的值。若未指定平台，则使用当前平台。 另外，还可通过指定语言来检索针对语言的信息，如 Sound SFX（音效）对象的音频源数据。 若未指定语言，则使用当前语言。

示例

请参照 to 工程代码 了解初始化。

如需查看更多示例，请参阅 ak.wwise.core.object.get 。

返回一列对象的 ID、名称和音量：

from waapi import WaapiClient
import pprint
# Connect (default URL)
client = WaapiClient()
# Return two objects
args = {
'waql': '$ "\\Audio Devices\\Default Work Unit\\System", "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}"'
}
options = {
'return': ['id', 'name', 'Volume']
}
result = client.call("ak.wwise.core.object.get", args, options=options)
pprint.pprint(result)
# Disconnect
client.disconnect()

返回 Actor-Mixer Hierarchy 中以‘My’开头所有对象的 ID 和名称，并使用以下的正则表达式返回：

from waapi import WaapiClient
import pprint
# Connect (default URL)
client = WaapiClient()
# Return all objects under the actor-mixer hierarchy with loop in the name
args = {
'waql': '$ "\Actor-Mixer Hierarchy" select descendants where name = /^My/'
}
options = {
'return': ['name', 'id']
}
result = client.call("ak.wwise.core.object.get", args, options=options)
pprint.pprint(result)
# Disconnect
client.disconnect()

如需进一步了解 WAQL，请参阅 使用 Wwise Authoring Query Language (WAQL) 章节。

此页面对您是否有帮助？

需要技术支持？

仍有疑问？或者问题？需要更多信息？欢迎联系我们，我们可以提供帮助！

查看我们的“技术支持”页面

介绍一下自己的项目。我们会竭力为您提供帮助。

来注册自己的项目，我们帮您快速入门，不带任何附加条件！

开始 Wwise 之旅