Wwise Authoring API는 종합적인 쿼리 시스템을 제공해 Wwise 프로젝트의 가장 중요한 부분을 검색할 수 있도록 합니다. 더 자세히 말해, 프로젝트 내 어떤 오브젝트든 불러올 수 있다는 뜻입니다.
쿼리 시스템은 ak.wwise.core.object.get function 에 빌드됩니다. 더 자세한 내용은 해당 참고 자료 문서에서 확인하실 수 있습니다.
쿼리는 두 부분으로 구성돼있습니다.
-
from: 쿼리 시작 지점을 지정합니다. 이는 데이터를 가져오는 출발지가 됩니다.
-
transform: 오브젝트에 적용할 일련의 변환을 지정합니다. 변형은 시퀀스에 추가할 수 있습니다.
또한, 쿼리는 다음과 같은 상세 내용을 지정하는 옵션이 있습니다.
-
return: 오브젝트로부터 무엇을 반환할 지 지정합니다. 특별히 지정된 게 없으면 기본 설정으로 ['id, 'name']이 됩니다.
-
platform: 플랫폼이 쿼리를 사용하도록 지정합니다. 특별히 지정된 게 없으면 기본 설정으로 현재 플랫폼이 됩니다.
from
The from 구문은 쿼리를 시작에 앞서 몇 가지 사항을 정합니다:
-
id: 오브젝트 ID(GUID)의 어레이를 지정합니다. 이미 오브젝트 ID가 있을 경우 해당 오브젝트를 검색할 때 유용합니다.
-
name: 타입으로 정규화된 오브젝트 이름의 어레이를 type:name의 형태로 지정합니다. 전역적으로 고유한 이름으로 된 오브젝트 타입만 지원됩니다. 사용 가능한 타입에 대한 정보는 Wwise Objects Reference 를 확인하세요.
-
search: Wwise 오브젝트 이름과 노트에서 검색할 텍스트를 지정합니다.. Wwise 검색과 동일한 검색 엔진을 사용합니다.
-
path: 검색할 경로 어레이를 지정합니다. 이 때 경로는 반드시 절대 경로여야 하며 물리적 폴더 이름에 해당하는 카테고리 이름으로 시작해야 합니다. 예시: \Actor-Mixer Hierarchy\Default Work Unit\MySound.
-
ofType: Wwise 오브젝트 타입의 어레이를 지정합니다. 모든 Game Parameter를 가져오는 경우와 같이 특정 오브젝트 타입에 해당하는 모든 오브젝트를 가져올 때 유용합니다. 사용 가능한 타입에 대한 정보는 Wwise Objects Reference 를 확인하세요.
transform
transform 구문은 선택된 오브젝트를 변형할 때 사용하는 변형 함수 몇 가지를 제공합니다. 첫 번째 변형은 from 구문으로 선택된 오브젝트에 적용됩니다. 다른 변형은 이전 변형의 결과물에 적용됩니다.
시퀀스에 여러 개의 변형이 적용될 수 있습니다.
-
select parent: 모든 오브젝트에 대해 각각에 해당하는 상위 오브젝트를 선택합니다.
-
select children: 모든 오브젝트에 대해 각각에 해당하는 하위 오브젝트 목록을 선택합니다.
-
select descendants: 모든 오브젝트에 대해 모든 하위 오브젝트를 반복적으로 선택합니다.
-
select ancestors: 모든 오브젝트에 대해 모든 상위 오브젝트를 반복적으로 선택합니다.
-
select referencesTo: 모든 오브젝트에 대해 해당 오브젝트를 참조하는 모든 오브젝트를 선택합니다.
-
where: 이전 반복자의 결과를 필터링합니다. 사용 가능한 기준은 다음과 같습니다.
-
name:contains: 오브젝트 이름을 검색할 때 대/소문자를 구분합니다.
-
name:matches: 오브젝트 이름을 정규 표현식으로 검색할 때 대/소문자를 구분합니다.
-
type:isIn: 특정 타입의 오브젝트만 유지함으로써 이전 반복자의 결과를 필터링합니다. 오브젝트 타입 목록에 대한 내용은 Wwise Objects Reference 를 참고하세요.
-
category:isIn: 특정 카테고리의 오브젝트만 유지함으로써 이전 반복자의 결과를 필터링합니다.
-
distinct: 고유한 오브젝트만 유지함으로써 이전 반복자의 결과를 필터링합니다.
return (선택 사항)
return 구문(표현식)은 모든 변형의 마지막에 한 번 실행됩니다. 아무 변형도 지정되지 않은 경우에는 from 구문으로부터 직접 실행됩니다. return 표현식은 Wwise 오브젝트가 반환할 요소를 지정합니다. 반환하는 요소의 개수에는 제한이 없습니다.
반환 표현식에는 접두어 '@'를 이용해 속성 및 참조를 포함시킬 수 있습니다. 예를 들어 '@Volume'이나 '@OutputBus'를 포함할 수 있습니다. 두 개로 된 '@@'의 접두어가 붙을 경우, 결과물은 오버라이드의 원본을 사용하게 되며, 이는 계층 구조에서 'override parent'의 다양한 값에 의해 결정됩니다.
표현식이 유효한 참조로 확인되면, 참조된 오브젝트의 속성에 대해 더 상세히 쿼리할 수 있습니다. 예를 들어, Sound 오브젝트의 '@UserAuxSend0' 참조가 기존 Auxiliary Bus를 참조할 경우, 속성 설명자 앞에 점('.')을 추가해 이 Auxiliary Bus의 속성을 쿼리할 수 있습니다. 즉, 참조된 Auxiliary Bus의 Attenuation의 쿼리는 간단히 '@UserAuxSend0.@Attenuation'가 됩니다. '@@'로 오버라이드의 원본을 사용할 때도 동일한 원리가 적용됩니다.
일부 오브젝트에는 랜덤화(randomization) 같이 특정 기능을 하는 속성이 있습니다. 이런 기능과 관련된 값을 가져오기 위해서는, 해당 속성에 연관된 특수한 오브젝트를 함수와 유사한 접근자를 통해 쿼리합니다. 예를 들어, 랜더마이저(randomizer) 기능은 오브젝트의 특정 속성에 연결된 Modifier 오브젝트로 서술할 수 있습니다. 이 오브젝트는 'randomizer("PropertyName")'로 쿼리될 수 있습니다. 여기서 PropertyName에는 'Volume' 같은 속성 이름이 들어갑니다. 접근자가 유효한 참조를 제공할 경우, 이전에 설명한 것처럼 반환되는 오브젝트를 더 상세히 쿼리할 수 있습니다. For example, the 'Max' property of the Volume randomizer can be obtained like so: 'randomizer("Volume").@Max'.
사용 가능한 접근자 목록은 다음과 같습니다.
반환 표현식의 요소가 반환된 오브젝트에서 존재하지 않거나 호환 불가능할 경우, 결과물에서 제외됩니다.
그 밖의 옵션
ak.wwise.core.object.get 함수를 비롯해 옵션 오브젝트를 취하는 다른 함수들은 다음을 정의합니다.
- 반환 표현식 (위에 나온 설명 참조)
- 플랫폼: 플랫폼의 이름이나 ID(GUID)
- 언어: 언어 이름이나 ID(GUID)
일부 접근자는 옵션에 따라 영향을 받을 수 있습니다. 예를 들어 속성이나 참조 값을 가져올 때, 플랫폼을 지정해 연결되지 않은 값을 구할 수 있습니다. 플랫폼이 지정돼있지 않은 경우, 현재 플랫폼을 사용합니다. 언어 또한 별도로 지정해 Sound 오브젝트의 오디오 음원 데이터와 같이 특정 언어로 된 정보를 가져올 수 있습니다. 특별히 지정돼있지 않은 경우, 현재 언어를 사용합니다.
예제
초기화에 대한 정보는 프로젝트 코드 를 참고하세요.
ak.wwise.core.object.get 에 더 많은 예제가 나와있습니다.
오브젝트 목록의 ID와 이름, 보이스 볼륨을 반환합니다.
var query = {
from: { id: [
'{A076AA65-B71A-45BB-8841-5A20C52CE727}',
'{2028C899-8300-4667-ADD0-ED10467BD91E}',
'{24979032-B170-43E3-A2E4-469E0193E2C3}'
] }
};
var options = {
return: ['id', 'name', '@Volume']
};
session.call('ak.wwise.core.object.get', [], query, options).then(
function (res) {
var objects = res.kwargs.return;
for(let i = 0; i < objects.length;++i ){
console.log(`${objects[i].name}: ${objects[i]['@Volume']}`);
}
},
function (error) {
console.log(`error: ${error}`);
}
);
정규 표현식을 이용해 'My'로 시작하는 Actor-Mixer Hierarchy 내 모든 오브젝트의 ID와 이름을 반환합니다.
var query = {
from:{path:['\\Actor-Mixer Hierarchy']},
transform:[
{select:['descendants']},
{where:['name:matches','^My']}
]
};
var options = {
return: ['id', 'name']
};
session.call('ak.wwise.core.object.get', [], query, options).then(
function (res) {
var objects = res.kwargs.return;
for(let i = 0; i < objects.length;++i ){
console.log(`${objects[i].name}`);
}
},
function (error) {
console.log(`error: ${error}`);
}
);