개요

※이 글은 유니티 다이얼로그 시스템 에셋 ‘Naninovel(나니노벨)’의 한국어 번역 페이지입니다.

※모든 내용의 저작권 및 내용의 책임과 권한은 Naninovel에 있습니다.

※원문 페이지: (링크)

커스텀 변수(Custom Variables)는 나니노벨 엔진 사용자의 맞춤형 변수입니다. 나니노벨 스크립트나 다른 시스템 환경에 대해 조건문을 사용할 수 있게 도와줍니다.

예를 들어, 커스텀 변수는 다양한 나니노벨 스크립트 중 하나를 선택해서 출력시킬 수 있게 합니다. 가령, 플레이어가 과거 선택했던 시나리오상 선택지에 따라 스토리가 분기하는 경우 등이 있습니다.

또다른 자주 쓰이는 상황은 바로, 플레이어가 게임플레이를 통해 선택한 것에 따라 플레이어의 스테이터스 창이 변동되는 경우입니다. (예: 점수, 소지금, 자원 등)

메모

변수 이름은 문자로 시작해야 하며 라틴 문자, 숫자, 밑줄만 포함할 수 있습니다. 변수명은 대소문자를 구분하지 않습니다.

• 예: name, Char1Score, my_score;
• 예: myscore는 MyScore와 같습니다.

@set 및 @if 명령어로 naninovel 스크립트와 ICustomVariableManager 엔진 서비스를 사용하는 C# 스크립트에서 커스텀 변수를 생성, 수정 및 사용할 수 있습니다.

예를 들어, 다음 스크립트 명령어는 선택지에 따라 score 커스텀 변수에 또 다른 값을 할당합니다.

@choice "I'm humble, one is enough…" set:score=1
@choice "Two, please." set:score=2
@choice "I'll take your entire stock!" set:score=999

그리고 다음은 score 변수값에 따라 스크립트 실행을 다시 라우팅합니다.

@goto MainRoute if:"score > 1 && score <= 900"
@goto BadEnd if:score>900

더 많은 예제는 @set 및 @if 명령어에 대한 API 레퍼런스를 확인하세요.

모든 커스텀 변수는 게임에 자동으로 저장됩니다. 기본적으로는 해당 변수가 로컬 범위에 저장됩니다. 가령, 게임플레이 과정에서 일부 변수를 할당하거나, 플레이어가 새로운 게임을 시작했거나, 또다른 게임 슬롯에서 게임을 불러오는 등 변수가 아직 할당되지 않은 상태에서는, 해당 변수값이 소실됩니다. 이는 대부분의 변수 자료형에 대해 유용하게 쓰입니다.

다만, 해당 변수를 전역 범위에서 사용하고 싶을 수 있습니다. 이 경우 G_, g_ 등의 접두사를 붙여주세요.

예시

• G_FinishedMainRoute
• g_total_score

전역 변수는 일부 또는 전체 정보 메타(예: 플레이어가 특정 루트를 완료한 횟수 또는 모든 플레이를 기반으로 한 총 스코어)를 나타내는 데 사용할 수 있습니다.

‘Custom Variables’ 구성 메뉴에서 사전에 초기값으로 정의된 변수에 맞춤형으로 전역 변수나 로컬 변수를 설정할 수 있습니다.

미리 정의된 전역 변수는 처음 애플리케이션을 시작할 때 초기화되는 반면, 로컬 변수는 각 상태가 재설정될 때 초기화됩니다. 메뉴의 값 필드에는 raw 데이터 문자열이 아니라 유효한 스크립트 표현식이 필요합니다.

팁

만약 일종의 전역 카운터를 만들어 롤백하거나 게임을 다시 시작하는 등 다시 플레이할 때 계수가 1회 증가하도록 만들고 싶다면 HasPlayed() 표현식 함수를 사용하세요.

변수 삽입하기

중괄호를 사용하여 naninovel 스크립트 매개변수 값에 커스텀 변수를 삽입(인라인)할 수 있습니다.

다음 스크립트는 사용자가 임의의 텍스트를 입력할 수 있는 입력 필드 UI를 보여줍니다. 입력한 텍스트가 제출될 시 지정된 커스텀 변수에 할당됩니다.

; 사용자가 임의의 텍스트를 입력하고 `name` 변수에 할당할 수 있도록 허용@input name summary:"Choose your name."
; 사용자가 입력을 제출할 때까지 스크립트 실행을 중지하려면 @stop이 필요합니다.
@stop

; 그런 다음 naninovel 스크립트에 할당된 `name` 변수를 삽입할 수 있습니다.
Archibald: Greetings, {name}!

; ...또는 집합 및 조건식 내에서 사용할 수 있습니다.
@set score+=3 if:name=="Felix"

팁

캐릭터 이름을 동적으로 만들려면 표시 이름 기능을 사용하세요.

파라미터 값이 허용하는 한 모든 매개변수 값에 커스텀 변수를 삽입할 수 있습니다. 예를 들어 문자열(텍스트)을 정수(숫자) 매개변수에 할당할 수 없습니다.

@set PlayerName=”Felix”;PlayerYPosition=0.1;PlayerTint=”lightblue”

; 다음은 PlayerTint가 숫자가 아니기 때문에 오류를 생성합니다.
@char {PlayerName} pos:50,{PlayerTint}

; …그리고 이것은 잘 실행될 것입니다.
@char {PlayerName} pos:50,{PlayerYPosition} tint:{PlayerTint}

변수 트리거

특정 커스텀 UI나 또다른 시스템을 제작할 때, 변수값이 변경될 때 그에 맞춰 특정 이벤트가 발생하거나 반응하는 구조를 만들고 싶은 경우가 있습니다.

가령, 캐릭터 스테이터스 스크린을 만드는 경우, 변수값에 따라 텍스트가 변동되어야하는 경우가 있습니다.

기존 방식에서는 C# 스크립트를 사용하여 이러한 동작을 구성하였지만, Custom Variable Trigger 컴포넡트를 이용해 이러한 구성을 짜는 것도 가능합니다.

컴포넌트는 특정 이름의 변수가 변경될 때 이 유니티 이벤트를 불러옵니다. 텍스트 값이 갱신되는 등의 이벤트가 호환되는 명령어를 바인딩하는 것도 가능합니다.

예시

GitHub의 맵 예시 프로젝트에서 지도 위치의 가용성을 높이기 위해 변수 트리거를 사용하는 예시를 찾아보세요.

변수 디버깅

게임이 실행되는 동안 모든 기존 변수를 보고 디버깅 목적으로 해당 값을 변경할 수 있습니다.

개발 콘솔을 열고 var 명령을 입력하여 변수 편집기 창을 엽니다.

목록에 있는 변수의 값을 변경하면 ‘SET’ 버튼이 나타나며, 이 버튼을 눌러 변경 사항을 적용할 수 있습니다.

게임 실행 중 커스텀 변수가 변경되면 변수 목록이 자동으로 업데이트됩니다.

C#에서 커스텀 변수 사용하기

커스텀 변수는 ICustomVariableManager 엔진 서비스를 통해 C#에서 액세스할 수 있습니다.

변수 값을 얻으려면 GetVariableValue(name) 메서드와 SetVariableValue(name, value)를 사용하여 변수 값을 설정하십시오. 예를 들어 ‘MyVarName’ 커스텀 문자열 변수가 존재하는 경우 아래 코드는 이를 검색하고 ‘Hello!’를 추가합니다. 값에 문자열을 추가하고 다시 설정합니다.

var varManager = Engine.GetService();
var myValue = varManager.GetVariableValue("MyVarName");
myValue += "Hello!";
varManager.SetVariableValue("MyVarName", myValue);

모든 커스텀 변수 값은 문자열로 저장된다는 점에 유의하세요. 이를 다른 유형(예: 정수형, 부울형 등)으로 사용하려면 반환된 문자열 값을 원하는 유형으로 구문 분석하고 값을 설정할 때 다시 문자열로 캐스팅해야 합니다.

가장 일반적인 데이터 유형의 경우 확장 방법을 사용할 수 있습니다. 예:

var varManager = Engine.GetService<ICustomVariableManager>();

varManager.TryGetVariableValue<float>("MyFloatVarName", out var floatValue);
Debug.Log($"My float variable value: {floatValue}");

varManager.TryGetVariableValue<int>("MyIntVarName", out var intValue);
Debug.Log($"My integer variable value: {intValue}");

varManager.TryGetVariableValue<bool>("MyBoolVarName", out var boolValue);
Debug.Log($"My boolean variable value: {boolValue}");

floatValue += 10.5f;
varManager.TrySetVariableValue("MyFloatVarName", floatValue);

intValue = -55;
varManager.TrySetVariableValue("MyIntVarName", intValue);

boolValue = !boolValue;
varManager.TrySetVariableValue("MyBoolVarName", boolValue);

연관글 목록

나니노벨 Samples

더 읽어보기

2025-03-163:47 오후

나니노벨 Custom Build Environment

더 읽어보기

2025-02-232:02 오후