Konado .NET API

이 기능은 아직 실험적입니다.

소개

Konado.NET은 Konado 대화 시스템의 C# API 확장입니다. Konado 기본 플러그인을 대체하는 것이 아니라, C#에서 KND_DialogueManager를 제어하고, 대화 흐름 신호를 구독하고, .ks 스크립트를 파싱하며, Konado GDScript 데이터 리소스를 다루기 위한 얇은 레이어입니다.

진입점은 자동 로드 노드 KonadoAPI입니다. 일반적으로 KonadoAPI.DialogueManagerApi에서 시작합니다.

사용 조건

Konado.NET은 C#을 지원하는 Godot 프로젝트에서만 사용할 수 있습니다. Godot 4.7.1 이상의 .NET 에디터를 사용하세요. 비 .NET 프로젝트에서 활성화하면 res://addons/konadotnet/Konadotnet.cs를 로드하지 못할 수 있습니다. 이 경우 Konado 기본 플러그인은 사용할 수 있지만 C# API는 사용할 수 없습니다.

먼저 Konado 플러그인을 활성화하고, 그다음 Konadotnet을 활성화하세요. 장면에는 KND_DialogueManager의 전체 공개 API 계약을 구현한 대화 관리자가 필요합니다. Konado.NET은 현재 장면 트리를 검색하고 나중에 추가된 대상 노드도 자동으로 바인딩합니다. 노드 이름은 검색에 영향을 주지 않습니다. 대화 관리자가 여러 개라면 BindDialogueManager(Node source)로 명시적으로 지정하세요.

빠른 시작

csharp

using Godot;
using Konado.Runtime.API;
using Konado.Wrapper;

public partial class DialogueExample : Node
{
    public override void _Ready()
    {
        var dialogueManager = KonadoAPI.DialogueManagerApi;

        dialogueManager.DialogueLineStart += (string nodeId) =>
        {
            GD.Print($"Node started: {nodeId}");
        };

        dialogueManager.CustomSignal += (string content) =>
        {
            GD.Print($"Custom signal: {content}");
        };

        var interpreter = new KonadoScriptsInterpreter();
        var shot = interpreter.ProcessScriptsToData("res://sample/demo/demo_01.ks");

        dialogueManager.SetShot(shot);
        dialogueManager.InitDialogue();
        dialogueManager.StartDialogue();
    }
}

KonadoAPI

멤버	타입	설명
`IsApiReady`	`bool`	`KonadoAPI` 자동 로드 노드가 초기화되었는지 여부입니다. `KND_DialogueManager`를 찾았다는 뜻은 아닙니다.
`API`	`static KonadoAPI`	현재 자동 로드 인스턴스의 정적 참조입니다.
`DialogueManagerApi`	`static DialogueManagerAPI`	대화 관리자 API 인스턴스이며 주요 런타임 진입점입니다.
`InternationalizationApi`	`static InternationalizationAPI`	언어, 번역, 현지화 스토리 API입니다.

InternationalizationAPI

Locale, AvailableLocales, SetLocale, NormalizeLocale, RegisterTranslation, UnregisterTranslation, ResolveScriptPath, LoadLocalizedScript를 제공합니다.

csharp

var i18n = KonadoAPI.InternationalizationApi;
var shot = i18n?.LoadLocalizedScript("res://dialogues/chapter.ks", "ko");
if (shot != null)
    KonadoAPI.DialogueManagerApi?.SetShot(shot);

DialogueManagerAPI

DialogueManagerAPI는 KND_DialogueManager의 C# 제어 레이어이며 호출을 GDScript 노드로 전달합니다.

속성

속성	타입	설명
`IsReady`	`bool`	사용할 수 있는 `KND_DialogueManager`에 바인딩되었는지 여부입니다.
`Source`	`Node`	현재 바인딩된 원본 Godot 노드입니다.

메서드

메서드	설명
`bool BindDialogueManager(Node source = null)`	지정한 대화 관리자에 바인딩합니다. 생략하면 장면 트리를 순회합니다. 성공하면 `true`를 반환합니다.
`void InitDialogue()`	`init_dialogue()`를 호출합니다. 보통 `SetShot()` 뒤, `StartDialogue()` 앞에서 호출합니다.
`void SetShot(Resource shot)` / `void SetShot(KndShot shot)`	현재 샷을 변경합니다. 래퍼를 직접 전달할 수 있습니다.
`void StartDialogue()`	`start_dialogue()`를 호출해 재생을 시작합니다.
`void StopDialogue()`	`stop_dialogue()`를 호출해 재생을 중지합니다.
`void StartAutoplay(bool value)`	자동 재생을 전환합니다.
`bool SaveGame(int saveId)`	진행 상황을 저장합니다. API가 준비되지 않았거나 저장에 실패하면 `false`를 반환합니다.
`bool LoadGame(int saveId)`	지정한 저장 슬롯을 불러옵니다.
`bool DeleteSave(int saveId)`	지정한 저장 슬롯을 삭제합니다.
`Dictionary GetSaveInfo(int saveId)`	단일 저장 정보를 가져옵니다. API가 준비되지 않았으면 빈 딕셔너리를 반환합니다.
`Array<Dictionary> GetAllSaveInfo()`	모든 저장 정보를 가져옵니다. API가 준비되지 않았으면 빈 배열을 반환합니다.

일반적인 재생 순서:

csharp

var shot = interpreter.ProcessScriptsToData("res://dialogues/chapter_01.ks");
dialogueManager.SetShot(shot);
dialogueManager.InitDialogue();
dialogueManager.StartDialogue();

이벤트

이벤트	설명
`ShotStart`	`shot_start`에 연결됩니다. 샷이 시작될 때 발생합니다.
`ShotEnd`	`shot_end`에 연결됩니다. 샷이 끝날 때 발생합니다.
`DialogueLineStart(string nodeId)`	`dialogue_line_start(node_id)`에 연결됩니다. 현재 버전은 이전 줄 번호 대신 노드 ID를 사용합니다.
`DialogueLineEnd(string nodeId)`	`dialogue_line_end(node_id)`에 연결됩니다.
`CustomSignal(string content)`	`custom_signal(content)`에 연결됩니다. `.ks`의 `signal` 문에서 발생합니다.

ActingInterface

열거값	효과
`NoneEffect`	효과 없음
`EraseEffect`	지우기 효과
`BlindsEffect`	블라인드 효과
`WaveEffect`	웨이브 효과
`AlphaFadeEffect`	알파 페이드 효과
`VortexSwapEffect`	소용돌이 전환 효과
`WindmillEffect`	풍차 효과
`CyberGlitchEffect`	사이버 글리치 효과

Wrapper 클래스

Wrapper 클래스는 Konado GDScript 리소스를 감싸는 가벼운 C# 래퍼입니다. 기존 리소스를 감쌀 때는 스크립트 타입을 검증하고, 새 래퍼를 만들 때는 대응하는 GDScript 리소스를 생성합니다. Godot API가 기반 Resource를 명시적으로 요구할 때만 SourceResource를 사용하세요. SetShot(KndShot)에는 래퍼를 직접 전달할 수 있습니다.

Dialogue

Dialogue는 KND_Dialogue를 감쌉니다: res://addons/konado/scripts/dialogue/knd_dialogue.gd.

멤버	설명
`Dialogue()`	새 `KND_Dialogue` 리소스를 생성합니다.
`Dialogue(GodotObject source)`	기존 `KND_Dialogue`를 감쌉니다. 잘못된 소스면 예외를 던집니다.
`SourceResource`	원본 `Resource`를 반환합니다.

속성	타입	설명
`SourceFileLine`	`int`	원본 `.ks` 줄 번호입니다. 디버깅과 오류 위치에 사용합니다.
`DialogueType`	`Dialogue.Type`	노드 타입이며 재생 처리 방식을 결정합니다.
`NodeId`	`string`	대화 그래프 노드 ID입니다.
`NextId`	`string`	기본 다음 노드 ID입니다.
`IfNextId`	`string`	조건이 참일 때 이동할 노드입니다.
`ElseNextId`	`string`	조건이 거짓일 때 이동할 노드입니다.
`VarName`	`string`	조건 판단에 사용할 변수명입니다.
`ConditionOperator`	`int`	조건 연산자: `0 ==`, `1 >`, `2 <`, `3 >=`, `4 <=`.
`TargetValue`	`int`	조건 비교 대상 값입니다.
`CharacterId`	`string`	말하는 캐릭터 ID입니다.
`DialogueContent`	`string`	대화 텍스트입니다.
`VoiceId`	`string`	음성 ID입니다.
`CharacterName`	`string`	표시하거나 생성할 캐릭터 ID입니다.
`CharacterState`	`string`	캐릭터 상태 또는 일러스트 상태 ID입니다.
`ActorPosition`	`Vector2`	캐릭터 위치입니다. 현재 버전은 그리드 기반 배치를 사용합니다.
`ExitActor`	`string`	퇴장 또는 숨길 캐릭터 ID입니다.
`ChangeStateActor`	`string`	상태를 변경할 캐릭터 ID입니다.
`ChangeState`	`string`	대상 상태 ID입니다.
`TargetMoveChara`	`string`	이동할 캐릭터 ID입니다.
`TargetMovePos`	`Vector2`	이동 목표 위치입니다.
`Choices`	`Array<DialogueChoice>`	선택지 목록입니다. 각 선택지는 `NextId`로 대상 노드를 가리킵니다.
`JumpShotPath`	`string`	다른 `KND_Shot`으로 이동할 리소스 경로입니다.
`JumpBranchTarget`	`string`	현재 샷 내부의 분기 라벨입니다.
`BgmName`	`string`	재생할 BGM 이름입니다.
`SoundeffectName`	`string`	재생할 효과음 이름입니다.
`BackgroundName`	`string`	전환할 배경 이름입니다.
`BackgroundToggleEffects`	`BackgroundTransitionEffectsType`	배경 전환 효과입니다.
`CustomSignalName`	`string`	`CustomSignal` 이벤트로 전달되는 내용입니다.
`AchievementId`	`string`	업적 ID입니다.
`AchievementValue`	`int`	업적 진행 값입니다.
`AchievementFlagName`	`string`	업적 플래그 이름입니다.
`AchievementFlagValue`	`bool`	업적 플래그 값입니다.
`VariableName`	`string`	조작할 변수명입니다.
`VariableOperation`	`int`	변수 연산: `0 SET`, `1 ADD`, `2 SUB`, `3 MUL`, `4 DIV`.
`VariableOperand`	`string`	문자열로 저장되며 런타임에 기본 플러그인이 해석하는 피연산자입니다.
`IsPersistent`	`bool`	지속 변수 여부입니다. 보통 `%`는 지속 변수, `$`는 임시 변수입니다.

Dialogue.Type

값	설명
`OrdinaryDialog`	일반 대화.
`DisplayActor`	캐릭터 표시 또는 생성.
`ActorChangeState`	캐릭터 상태 변경.
`MoveActor`	캐릭터 이동.
`SwitchBackground`	배경 전환.
`ExitActor`	캐릭터 퇴장.
`PlayBgm`	BGM 재생.
`StopBgm`	BGM 중지.
`PlaySoundEffect`	효과음 재생.
`ShowChoice`	선택지 표시.
`IfElseBranch`	조건 분기.
`Branch`	호환성을 위해 남겨진 이전 분기 값.
`Jump`	점프 노드.
`JumpBranch`	분기 라벨로 점프.
`Signal`	사용자 정의 신호 노드.
`AchievementUnlock`	업적 잠금 해제.
`AchievementProgress`	업적 진행 업데이트.
`AchievementFlag`	업적 플래그 설정.
`SetVariable`	변수 설정 또는 변경.
`TheEnd`	종료 노드.

DialogueChoice

속성	타입	설명
`ChoiceText`	`string`	플레이어에게 표시되는 선택지 텍스트입니다.
`NextId`	`string`	선택 후 이동할 대상 노드 ID입니다.

KndData

KndData는 Konado 데이터 리소스의 기본 래퍼입니다. 대부분의 경우 KndShot, Dialogue, DialogueChoice 같은 구체 클래스를 사용합니다.

KndShot

속성	타입	설명
`KsPath`	`string`	원본 `.ks` 경로입니다.
`ShotId`	`string`	샷 ID입니다.
`StartNodeId`	`string`	시작 노드 ID입니다. 비어 있으면 보통 첫 노드를 사용합니다.
`Dialogues`	`Array<Dialogue>`	샷에 포함된 모든 대화 노드입니다.

메서드	설명
`Dialogue FindNode(string nodeId)`	`node_id`로 노드를 찾습니다. 없으면 `null`을 반환합니다.
`Dialogue GetStartNode()`	시작 노드를 가져옵니다.

KonadoScriptsInterpreter

멤버	설명
`KonadoScriptsInterpreter(Dictionary<string, Variant> flags = null)`	새 인터프리터를 생성합니다. `flags`는 호환성을 위해 남겨져 있습니다.
`KonadoScriptsInterpreter(GodotObject source)`	기존 인터프리터 객체를 감쌉니다.
`KndShot ProcessScriptsToData(string path)`	`.ks` 파일을 `KND_Shot`으로 파싱합니다.
`Dialogue ParseSingleLine(string line, long lineNumber, string path)`	Konado 스크립트 한 줄을 파싱합니다.

예시

csharp

var interpreter = new KonadoScriptsInterpreter();
var shot = interpreter.ProcessScriptsToData("res://sample/demo/demo_01.ks");

var api = KonadoAPI.DialogueManagerApi;
api.SetShot(shot);
api.InitDialogue();
api.StartDialogue();

FAQ

`IsApiReady`는 true이지만 `DialogueManagerApi.IsReady`가 false입니다

IsApiReady는 Konado.NET 자동 로드 노드 초기화 상태만 의미합니다. 현재 장면에 KND_DialogueManager가 있는지 확인하거나 수동으로 바인딩하세요.

csharp

KonadoAPI.DialogueManagerApi.BindDialogueManager(GetNode<Node>("path/to/manager"));

`SetShot` 후 재생되지 않습니다

SetShot()은 샷만 변경합니다. 다음 순서로 호출하세요.

csharp

api.SetShot(shot);
api.InitDialogue();
api.StartDialogue();

배경

액터

오디오

카메라

Konado .NET API

소개

사용 조건

빠른 시작

KonadoAPI

InternationalizationAPI

DialogueManagerAPI

속성

메서드

이벤트

ActingInterface

Wrapper 클래스

Dialogue

Dialogue.Type

DialogueChoice

KndData

KndShot

KonadoScriptsInterpreter

예시

FAQ

`IsApiReady`는 true이지만 `DialogueManagerApi.IsReady`가 false입니다

`SetShot` 후 재생되지 않습니다

Konado .NET API ​

소개 ​

사용 조건 ​

빠른 시작 ​

KonadoAPI ​

InternationalizationAPI ​

DialogueManagerAPI ​

속성 ​

메서드 ​

이벤트 ​

ActingInterface ​

Wrapper 클래스 ​

Dialogue ​

Dialogue.Type ​

DialogueChoice ​

KndData ​

KndShot ​

KonadoScriptsInterpreter ​

예시 ​

FAQ ​

IsApiReady는 true이지만 DialogueManagerApi.IsReady가 false입니다 ​

SetShot 후 재생되지 않습니다 ​

Konado .NET API

소개

사용 조건

빠른 시작

KonadoAPI

InternationalizationAPI

DialogueManagerAPI

속성

메서드

이벤트

ActingInterface

Wrapper 클래스

Dialogue

Dialogue.Type

DialogueChoice

KndData

KndShot

KonadoScriptsInterpreter

예시

FAQ

`IsApiReady`는 true이지만 `DialogueManagerApi.IsReady`가 false입니다

`SetShot` 후 재생되지 않습니다