Stingray 엔진에 포함된 노드 세트를 연장하는 자체 사용자 정의 흐름 노드를 생성할 수 있습니다. 기타 다른 기본 노드처럼 Stingray 수준 편집 도구에서 작업하는 수준 디자이너 및 게임플레이 프로그래머는 이러한 사용자 정의 노드를 수준 및 유닛에 대한 흐름 그래프로 불러올 수 있습니다. 그러나 사용자 정의 노드가 런타임에 게임에서 트리거되거나 평가되면 자체 사용자 지정 Lua 코드를 호출합니다.
게임 엔진이 사용자가 정의한 사용자 정의 Lua 함수를 실행해야 할 때 이러한 사용자 지정 노드를 사용하여 게임플레이 이벤트에 대한 복잡한 사용자 지정 응답을 생성하거나 게임 디자이너가 직접 제어할 수 있도록 할 수 있습니다.
참고: Stingray SDK를 사용하여 Lua 대신 C에서 사용자 정의 흐름 노드를 구현할 수도 있습니다. 자세한 내용은 C에서 사용자 정의 흐름 노드 생성을 참조하십시오.
사용자 정의 Lua 흐름 노드 사용 방법:
노드가 흐름 그래프에서 평가될 때 호출되는 일부 Lua 콜백 함수를 씁니다. 아래의 콜백 함수 쓰기를 참조하십시오.
.script_flow_nodes라는 확장자로 데이터 리소스 파일에 각 노드의 특성(예: 예상하는 입력 및 생성되는 출력 유형)을 정의합니다. 아래의 [흐름 노드 정의]를 참조하십시오.
사용자 정의 노드가 런타임에 트리거되고, 게임이 노드 정의에 포함된 .script_flow_nodes 파일 및 호출하는 함수가 포함된 Lua 스크립트 파일 모두를 메모리로 로딩하는지 확인하십시오. 이러한 파일은 상대적으로 적은 메모리를 차지하는 경향이 있으므로 게임 시작 동안 모두 로딩하고 최종 종료할 때까지 로딩되어 있도록 하는 것이 좋습니다.
로딩된 콜백 함수에 포함된 Lua 스크립트 및 런타임 시의 일부 Lua 환경 받기에 대한 자세한 내용은 자체 스크립트 파일 로드 및 실행을 참조하십시오.
게임에서 .script_flow_nodes 파일 받기에 대한 자세한 내용은 컨텐츠 및 리소스 관리를 참조하십시오.
게임 엔진이 Lua 함수를 호출할 때 항상 두 개의 인수가 전달됩니다.
항목이 흐름 노드 구성의 args 설정에 의해 정의되는 테이블. 아래를 참조하십시오.
이 흐름 노드 인스턴스를 고유하게 식별하는 값. Lua 코드에서 여러 평가에 걸쳐 흐름 노드에 대한 일부 상태 데이터를 유지 관리해야 하는 경우 이 값을 사용자 정의 변수에서 유지 관리하는 테이블의 상태 데이터를 저장 및 검색하는 키로 사용할 수 있습니다.
Lua 함수는 하나의 값, 즉 흐름 노드 구성의 returns 설정에 구성한 이름 및 유형과 일치하는 항목이 포함된 테이블을 반환해야 합니다. 아래를 참조하십시오. 원하는 경우 인수를 전달하는 데 사용했던 동일한 테이블을 재사용할 수 있습니다. 노드의 특정 평가 동안 반환 값을 설정하지 않은 경우 흐름 노드는 어떤 값이든 테이블에 마지막으로 할당된 값을 재사용합니다. 값을 설정하길 원하지 않는 경우 테이블을 반환할 필요가 전혀 없습니다.
예를 들어 다음 함수는 두 개의 입력 값(둘 다 부동이며 a와 b로 명명됨)을 허용하는 방법과 테이블의 멤버로 sum이라고 명명된 부동 값을 반환하는 방법을 보여줍니다.
function FlowCallbacks.add(t)
t.sum = t.a + t.b
return t
end
이 함수를 불러오고 출력 부동 값을 처리하는 흐름 노드 정의에 대해서는 아래의 쿼리 예제를 참조하십시오.
Lua 함수를 작성하려면 흐름 노드가 현재 작동하고 있는 컨텍스트에 대한 일부 정보가 필요할 수 있습니다. 예를 들어 흐름 노드를 유닛 흐름에서 사용하려면 흐름 그래프가 현재 평가되고 있는 유닛의 ID가 필요할 수도 있습니다.
이 정보는 stingray.Application.flow_callback_context_world (), stingray.Application.flow_callback_context_unit (), stingray.Application.flow_callback_context_level () 및 stingray.Application.flow_callback_context_entity ()를 호출하여 Lua Application에서 가져올 수 있습니다.
데이터 파일의 사용자 정의 흐름 노드를 .script_flow_nodes 확장자로 정의해야 합니다. 이러한 데이터 파일은 프로젝트 리소스 디렉토리의 어디에든 있을 수 있으며, 필요한 경우 프로젝트의 다른 데이터 파일과 함께 메모리 안 및 밖으로 로딩할 수 있습니다.
원하는 만큼 얼마든지 .script_flow_nodes 파일을 가질 수 있으므로 프로젝트에 적합한 어떤 방법으로든 노드 정의를 정리할 수 있습니다.
.script_flow_nodes 파일은 대부분의 다른 Stingray 데이터 리소스에서 사용하는 SJSON 형식으로 되어 있습니다. 자세한 내용은 SJSON 데이터 형식 정보를 참조하십시오.
각 파일에는 단일 최상 수준의 nodes 요소가 포함되어 있어야 합니다. 이 요소의 값은 각각이 단일 흐름 노드를 정의하는 오브젝트의 목록이어야 합니다. 이러한 각 노드 오브젝트는 아래에 정의된 여러 구성 매개변수를 순서대로 사용할 수 있습니다.
참고: 모든 이름은 각 흐름 노드 내에서 고유해야 합니다. 예를 들어 동일한 노드의 인수와 반환 값 모두에 동일한 이름을 사용해서는 안 됩니다.
예:
// A sample .script_flow_nodes file.
nodes = [
// demonstrates basic usage, calling a specified Lua function
{
name = "Tile Collapsed"
category = "Tiles/Actions"
visibility = "unit"
function = "flow_callback_tile_collapsed"
args = {
collapsed_tile = "unit"
other_unit = "unit"
}
}
// your nodes list can have as many node definitions as you need.
{
name = "Wake Enemy"
category = "AI"
visibility = "all"
function = "flow_callback_ai_enemy_awake"
args = {
enemy = "unit"
}
}
]
다음 섹션에는 .script_flow_nodes 파일에 정의하는 흐름 노드에 대해 설정할 수 있는 모든 매개변수가 설명되어 있습니다.
흐름 노드의 이름입니다.
지정된 경우, 노드가 흐름 편집기의 이 범주 아래에 표시됩니다. 이름에 슬래시를 사용하여 하위 범주에 흐름 노드를 표시할 수 있습니다.
지정된 경우, 지정한 유형의 오브젝트에 대한 흐름 편집기에서만 흐름 노드를 볼 수 있습니다. 지정되지 않은 경우 또는 "모두"로 설정된 경우, 모든 흐름 편집기에서 노드를 볼 수 있습니다.
다음 값을 허용합니다.
이 매개변수를 사용하면 흐름 노드가 In이라는 단일 입력 이벤트에 할당됩니다. 이 In 이벤트가 트리거되면 게임 엔진이 사용자가 여기에 지정한 Lua 함수를 호출합니다.
이 설정의 값은 다음 중 하나일 수 있습니다.
Lua 함수를 반환하는 임의 Lua 코드. 예:
// demonstrates a query node with inline function code
{
name = "Multiply"
args = {
a = "float"
b = "float"
}
returns = {
product = "float"
}
query = true
function = """ return function(t) t.product = t.a * t.b return t end """
}참고: function 또는 function_map 중 하나를 사용하여 각 노드에서 호출해야 하는 Lua 함수를 지정해야 합니다. 단일 노드에서 둘 모두를 사용하지 마십시오.
이 매개변수를 사용하면 흐름 노드에 대한 대체 트리거 이벤트 목록을 설정할 수 있으며, 이 이벤트들은 각각 서로 다른 Lua 함수를 불러옵니다.
이 매개변수에는 하위 리스트 목록이 포함되어야 합니다. 각 하위 리스트에는 다음 두 개의 항목이 포함되어야 합니다.
예:
// demonstrates usage of a function_map
{
name = "Giant Dust"
function_map = [
["Armpit Left" "CinematicGiant.cb_dust_armpit_left"]
["Armpit Right" "CinematicGiant.cb_dust_armpit_right"]
["Elbow Left" "CinematicGiant.cb_dust_elbow_left"]
["Elbow Right" "CinematicGiant.cb_dust_elbow_right"]
["Hip Left" "CinematicGiant.cb_dust_hip_left"]
["Hip Right" "CinematicGiant.cb_dust_hip_right"]
["Knee Left" "CinematicGiant.cb_dust_knee_left"]
["Knee Right" "CinematicGiant.cb_dust_knee_right"]
]
args = {
unit = "unit"
}
}
참고: function 또는 function_map 중 하나를 사용하여 각 노드에서 호출해야 하는 Lua 함수를 지정합니다. 단일 노드에서 둘 모두를 사용하지 마십시오.
Lua 함수에서 허용하는 인수와 이들의 유형을 정의하는 오브젝트입니다.
다음 섹션에 설명된 것처럼 두 가지 방법으로 각 인수를 지정할 수 있습니다. 둘 모두에서 args 오브젝트에 있는 각 요소의 키는 흐름 노드에 표시되는 입력 변수 슬롯의 이름과 Lua 함수로 전달되는 테이블의 변수 이름을 지정합니다. 그러나 값은 두 구문에서 서로 다르게 표현됩니다.
이 구문에서 args 오브젝트에 있는 각 요소의 값은 간단한 인수 유형, 즉 흐름 노드에 표시된 입력 슬롯에 연결될 수 있는 변수 유형입니다. 허용되는 유형 값: unit, actor, mover, vector3, quaternion, float, bool, string, instance_id, material, id, light, 및 mesh.
예:
...
args = {
setting = "float"
character = "unit"
position = "vector3"
}
...
이 구문에서 각 요소의 값은 다음 항목을 포함할 수 있는 테이블입니다.
예:
// demonstrates the detailed syntax for argument definitions, with
// default values and enumerations
{
name = "SetEnemyAttitude"
args = {
unit = "unit"
hostility = {
type = "enum"
choices = [
"Neutral"
"Hostile"
"Friendly"
]
default = "Neutral"
}
courtesy = {
type = "float"
default = 0.5
}
}
}
Lua 함수의 출력 값을 정의하는 오브젝트입니다.
이러한 반환 값은 흐름 노드에 출력 변수 슬롯으로 표시되며, 이를 다른 흐름 노드의 입력 슬롯에 연결할 수 있습니다.
반환 값 선언을 위한 구문은 위에 설명한 인수의 간단한 구문과 동일합니다.
returns 오브젝트에 있는 각 요소의 키는 흐름 노드에 표시되는 출력 변수 슬롯의 이름과 Lua 함수에 의해 반환되는 테이블의 출력 변수 이름을 지정합니다.
returns 오브젝트에 있는 각 요소의 값은 반환 값 유형, 즉 흐름 노드에 표시된 입력 슬롯에 연결될 수 있는 변수 유형입니다.
반환 값은 위에 나온 args 설정과 동일한 유형을 사용할 수 있고, 여기에 event 유형이 추가됩니다. event유형을 사용하는 경우 흐름 노드에는 출력 변수 커넥터 대신 out event 커넥터가 있습니다. 사용자의 함수가 해당 항목이 true로 설정된 테이블을 반환하면 out event가 트리거됩니다. 두 개 이상의 event 항목을 true로 설정해 두 개 이상의 out event를 트리거할 수 있습니다.
이전 버전과의 호환성을 위해, 아무 이벤트도 지정하지 않으면 out으로 호출된 단일 이벤트가 자동 생성됩니다. 이 out 이벤트는 Lua 함수에서 반환 테이블에 무엇을 기록하든 상관없이 함수가 반환할 때 항상 트리거됩니다.
query 매개변수를 true로 설정하면 흐름 노드는 query node가 됩니다. 쿼리 노드에는 입력 이벤트가 없는 대신 다른 노드에서 이 출력 데이터를 필요로 할 때마다 요청 시 자동으로 트리거됩니다. 일반적으로 쿼리 노드는 유닛의 현재 위치처럼 언제든 부실해질 수 있는 변동적인 데이터를 가져올 때 유용합니다.
예:
// demonstrates a basic query node
{
name = "Add"
args = {
a = "float"
b = "float"
}
returns = {
sum = "float"
}
query = true
function = "FlowCallbacks.add"
}