마인크래프트 JE 1.21.6 대화 상자(Dialog) 가이드

마인크래프트 자바에디션 1.21.6 대화 상자(Dialog) 가이드

이 글은 마인크래프트 위키의 dialog 항목을 바탕으로 작성되었습니다.

이 글은 마인크래프트 자바에디션 1.21.6 버전에 새롭게 추가된 기능인 대화 상자(Dialog)에 대한 모든 것을 다룹니다. 대화 상자가 무엇인지, 어떻게 사용하는지, 그리고 어떤 종류가 있는지 자세히 알아보겠습니다.

해당 글에는 AI가 사용되었습니다.

---

대화 상자(Dialog)란?

대화 상자는 플레이어에게 정보를 표시하고 입력을 받을 수 있는 간단한 모달 창입니다. 게임플레이 중 서버 관리자가 /dialog 명령어를 사용하거나, 대화 구성 요소 또는 다른 대화 상자 내의 show_dialog 액션을 통해 표시할 수 있습니다. 또한, 일시 정지 메뉴나 빠른 실행 단축키(기본 G)를 통해서도 설정된 대화 상자를 열 수 있습니다.

대화 상자를 통해 다음과 같은 다양한 상호작용이 가능합니다:

• 대화 구성 요소를 사용한 메시지 또는 정보 전달 (서식 있는 텍스트 및 클릭 가능한 링크 포함)
• 대화 상자, 토글, 슬라이더, 옵션 선택과 같은 입력 컨트롤 필드를 통한 플레이어 입력 수신
• 액션 버튼을 통한 명령어 실행 (권한 있는 명령어는 서버 관리자만 실행 가능)
• 중첩된 구조를 사용한 여러 대화 상자 간의 이동

지뢰찾기 - https://www.reddit.com/r/PhoenixSC/comments/1km6bjp/minesweeper_using_a_data_pack_and_the_new_dialog/

배드애플 - https://www.youtube.com/watch?v=GobJAxLJtkw

대화 상자는 주로 다음 세 가지 요소로 구성되지만, 정확한 내용은 유형에 따라 달라집니다:

• 헤더: 제목과 경고 버튼을 포함합니다.
• 본문 요소: 레이블, 입력, 버튼, 제출 액션 등을 포함하며, 필요한 경우 스크롤이 가능합니다.
• 선택적 푸터(footer): 확인 버튼과 제출 액션을 포함할 수 있습니다.

대화 상자 창이 열리면 플레이어 컨트롤이 일시적으로 비활성화되며, 사용자가 종료 액션 버튼, Esc 키 또는 대화 상자 제목 옆의 경고 버튼(타이틀 화면으로 돌아감)을 통해 창을 종료할 때까지 유지됩니다. 싱글플레이어에서는 대화 상자를 통해 게임을 일시 중지하도록 설정할 수 있으며, 이 경우 게임이 자동 저장됩니다.

대화 상자 정의 및 띄우기

대화 상자는 데이터 팩 내에서 다음과 같은 디렉토리 구조로 정의할 수 있습니다:

<데이터 팩 이름>.zip 또는 <데이터 팩 이름>/
├── pack.mcmeta
└── data/
    └── <네임스페이스>/
        └── dialog/
            └── <이름>.json

레지스트리이기 때문에 실험적 기능이 활성화되며 맵을 재시작해야합니다.

혹은 명령어 내부에서 내용을 인라인 작성하여 출력할 수 있습니다.

생성기 사용하기 ( https://misode.github.io/dialog/)

https://misode.github.io/dialog/

[Generator - Minecraft 1.21.6

misode.github.io](https://misode.github.io/dialog/)

위 사이트에서 대화 상자의 json 내용을 간편하게 생성할 수 있습니다.

이 글에서는 생성기를 사용하는데 필요한 개념만 알려드리고 예시 json 내용은 제외하도록 하겠습니다.

대화 상자 형식 (공통)

모든 대화 상자 유형에 적용되는 공통적인 최상위 필드는 다음과 같습니다:

• type (문자열, 필수):
  • 대화 상자 유형을 지정합니다. (minecraft:dialog_type 레지스트리의 값 중 하나)
    • minecraft:notice
    • minecraft:confirmation
    • minecraft:multi_action
    • minecraft:server_links
    • minecraft:dialog_list
• title (대화 구성 요소, 필수):
  • 화면 제목입니다. 특정 유형에 관계없이 항상 화면에 표시되어야 합니다.
• external_title (대화 구성 요소, 선택 사항):
  • 이 대화 상자로 연결되는 버튼에 사용될 이름입니다 (예: 일시 정지 메뉴).
  • 지정하지 않으면 title이 사용됩니다.
• body (본문 요소 목록 또는 단일 본문 요소, 선택 사항):
  • 대화 상자의 본문 내용을 정의합니다. (자세한 내용은 "본문 형식" 참조)
• inputs (입력 컨트롤 목록, 선택 사항):
  • 플레이어 입력을 받기 위한 컨트롤 목록입니다. (자세한 내용은 "입력 컨트롤 형식" 참조)
• can_close_with_escape (boolean, 선택 사항):
  • Esc 키로 대화 상자를 닫을 수 있는지 여부입니다. (기본값: true)
• pause (boolean, 선택 사항):
  • 싱글플레이어 모드에서 대화 상자 화면이 게임을 일시 중지해야 하는지 여부입니다. (기본값: true)
• after_action (문자열, 선택 사항):
  • 클릭 또는 제출 작업 후 대화 상자에 수행되는 추가 작업입니다. (기본값: close)
    • close: 대화 상자를 닫고 이전의 비-대화 상자 화면으로 돌아갑니다 (있는 경우).
    • none: 아무 작업도 하지 않습니다. 즉, 현재 대화 상자 화면을 계속 열어둡니다 (싱글플레이어 모드에서 게임이 잠기는 것을 방지하기 위해 pause가 false인 경우에만 사용 가능).
    • wait_for_response: 현재 대화 상자를 "응답 대기 중" 화면으로 대체합니다.

대화 상자 유형별 형식

1. minecraft:notice

• 하나의 액션 버튼을 푸터에 가지는 간단한 알림 화면입니다.
• action 필드를 추가적으로 요구하며 액션 버튼을 눌렀을 때의 기능을 설정합니다. (기본값: 대화 상자 종료 후 게임플레이 복귀)
• action (클릭 액션):
  • 버튼 클릭 시 수행할 작업을 정의합니다. (기본값: gui.ok(한국어:확인) 라벨을 가지며 아무 작업도 하지 않는 버튼)
  • label (대화 구성 요소, 필수):
    • 버튼에 표시될 텍스트입니다.
  • tooltip (대화 구성 요소, 선택 사항):
    • 버튼에 마우스를 올리거나 강조 표시했을 때 표시될 텍스트입니다.
  • width (정수, 1~1024):
    • 버튼의 너비입니다. (기본값: 150)
  • action (액션 객체):
    • 버튼 클릭 시 수행할 액션입니다. ("액션 형식" 참조)

2. minecraft:confirmation

• '예/아니오' 와 같이 두 개의 액션 버튼을 푸터에 가지는 확인 화면입니다.
• yes와 no 필드로 각 버튼을 정의합니다.
• 기본적으로 종료 액션은 no 버튼입니다.
• yes (클릭 액션, 필수):
  • 긍정적인 결과에 대한 액션 버튼입니다. (구조는 notice의 action과 동일)
• no (클릭 액션, 필수):
  • 부정적인 결과에 대한 액션 버튼입니다. (구조는 notice의 action과 동일)

3. minecraft:multi_action

• 여러 열로 배열된 스크롤 가능한 액션 버튼 목록을 표시하는 화면입니다.
• exit_action 필드가 있으면 해당 버튼이 푸터에 나타나고, 없으면 푸터가 표시되지 않습니다.
  • exit_action은 Esc 키 액션에도 사용됩니다.
• 본문에 먼저 Body가 표시되고 그 밑에 actions 버튼이 나열되기 시작합니다.
• actions (클릭 액션 목록, 필수):
  • 나열될 액션 버튼 목록입니다.(1개 이상) (각 항목의 구조는 notice의 action과 동일)
• columns (양의 정수, 선택 사항):
  • 열의 수를 나타냅니다. (기본값: 2)
• exit_action (클릭 액션, 선택 사항):
  • 대화 상자를 나가는 액션 버튼입니다. (구조는 notice의 action과 동일)

4. minecraft:server_links

• 여러 열로 배열된 스크롤 가능한 서버 링크 목록을 표시하는 화면입니다.
• 서버 링크는 서버에서 설정된 서버 링크가 자동으로 나열됩니다.
• exit_action 필드가 있으면 해당 버튼이 푸터에 나타나고, 없으면 푸터가 표시되지 않습니다.
  • exit_action은 Esc 키 액션에도 사용됩니다.
• 본문에 먼저 Body가 표시되고 그 밑에 서버 버튼들이 나열되기 시작합니다.
• exit_action (클릭 액션, 선택 사항):
  • 대화 상자를 나가는 액션 버튼입니다. (구조는 notice의 action과 동일)
• columns (양의 정수, 선택 사항):
  • 열의 수를 나타냅니다. (기본값: 2)
• button_width (정수, 1~1024, 선택 사항):
  • 버튼의 너비입니다. (기본값: 150)

5. minecraft:dialog_list

• 다른 대화 상자로 직접 연결되는 버튼들의 스크롤 가능한 목록을 여러 열로 배열하여 표시하는 화면입니다.
• 이 버튼들의 제목은 대상 대화 상자의 external_title 필드에서 가져옵니다.
• exit_action 필드가 있으면 해당 버튼이 푸터에 나타나고, 없으면 푸터가 표시되지 않습니다.
  • exit_action은 Esc 키 액션에도 사용됩니다.
• dialogs (대화상자 ID, 대화 상자 인라인, 태그, 리스트, 필수):
  • 목록에 표시할 하나 이상의 대화 상자입니다.
• exit_action (클릭 액션, 선택 사항):
  • 대화 상자를 나가는 액션 버튼입니다. (구조는 notice의 action과 동일)
• columns (양의 정수, 선택 사항):
  • 열의 수를 나타냅니다. (기본값: 2)
• button_width (정수, 1~1024, 선택 사항):
• 버튼의 너비입니다. (기본값: 150)

---

본문 형식 (Body Format)

• 모든 대화 상자는 제목과 액션 또는 입력 사이에 내용을 설명하는 본문 요소 목록을 가질 수 있습니다.
• 각 요소의 유형을 결정하는 것은 type에 적히는 메세지입니다.

{
    "type": "minecraft:item",
    "item": {
        "id": "minecraft:potato"
    }
},
{
    "type": "minecraft:plain_message",
    "contents": "ㅁㄴㅇㄹ"
}

1. minecraft:plain_message

여러 줄의 레이블입니다.

• type (문자열, 필수): minecraft:plain_message
• contents (텍스트 구성 요소, 필수):
  • 표시할 텍스트입니다.
• width (정수, 1~1024, 선택 사항):
  • 메시지의 최대 너비입니다. (기본값: 200)

2. minecraft:item

• 선택적 설명이 있는 아이템입니다.
• 아이템 위에 마우스를 올리면 인벤토리 슬롯에 있는 것처럼 보입니다.
• 너비와 높이를 기본값 이외의 값으로 설정해도 크기는 조절되지 않습니다.
• 설명이 있으면 아이템 오른쪽에 표시됩니다.
• type (문자열, 필수): minecraft:item
• item (아이템 스택 객체, 필수):
  • 개수가 포함된 아이템 스택입니다.
  • id (문자열, 필수):
    • 아이템 식별자입니다.
  • count (정수, 필수):
    • 아이템 개수입니다.
  • components (객체, 선택 사항):
    • 아이템에 대한 추가 정보입니다. (아이템 구성 요소 참조)
• description (텍스트 구성 요소 또는 객체, 선택 사항):
  • 아이템 설명입니다. 객체인 경우 다음 필드를 가집니다:
    • contents (텍스트 구성 요소, 필수):
      • 표시할 텍스트입니다.
    • width (정수, 1~1024, 선택 사항):
      • 메시지의 최대 너비입니다. (기본값: 200)
• show_decoration (boolean, 선택 사항):
  • true이면 아이템 위에 개수와 내구도 막대가 렌더링됩니다. (기본값: true)
• show_tooltip (boolean, 선택 사항):
  • true이면 아이템에 마우스를 올렸을 때 아이템 툴팁이 표시됩니다. (기본값: true)
• width (정수, 1~256, 선택 사항):
  • 요소의 가로 크기입니다. (기본값: 16)
• height (정수, 1~256, 선택 사항):
  • 요소의 세로 크기입니다. (기본값: 16)

---

입력 컨트롤 형식 (Input Control Format)

• 입력 컨트롤은 플레이어로부터 특정 정보를 받는 데 사용됩니다.
  • 이 정보는 연관된 key 태그를 사용하여 참조할 수 있습니다
  • (예: 액션 버튼 클릭 시 매크로 대체를 통해 명령어를 실행하거나 서버로 전송되는 사용자 지정 NBT 태그).
• 모든 입력 컨트롤 유형에는 label 필드가 있습니다.
• type (문자열, 필수):
  • 입력 컨트롤 유형을 지정합니다.
  • minecraft:input_control_type 레지스트리의 값 중 하나
    • minecraft:text
    • minecraft:boolean
    • minecraft:single_option
    • minecraft:number_range
• key (문자열, 필수):
  • 데이터를 제출할 때 사용되는 값의 식별자입니다. 유효한 템플릿 인수여야 합니다 (문자, 숫자, 밑줄 _).
• label (텍스트 구성 요소, 필수):
  • 입력 왼쪽에 표시될 텍스트입니다.

1. minecraft:text

기본적인 한 줄 텍스트 입력입니다.

• 출력 값:
  • 템플릿 대체 시: 특수 문자가 SNBT 문자열에 맞게 이스케이프 시퀀스를 사용하여 이스케이프된 내용입니다.
  • 태그로 전송 시: 수정되지 않은 내용의 문자열 태그입니다.
• width (정수, 1~1024, 선택 사항):
  • 입력의 너비입니다. (기본값: 200)
• label_visible (boolean, 선택 사항):
  • 레이블 표시 여부를 제어합니다. (기본값: true)
• initial (문자열, 선택 사항):
  • 텍스트 입력의 초기 값입니다.
• max_length (정수, 선택 사항):
  • 입력의 최대 길이입니다. (기본값: 32)
• multiline (객체, 선택 사항):
  • 존재하는 경우 여러 줄 입력을 허용합니다. 다음 필드를 가집니다:
    • max_lines (양의 정수, 선택 사항):
      • 존재하는 경우 최대 줄 수를 제한합니다.
    • height (정수, 1~512):
      • 입력의 높이입니다.

2. minecraft:boolean

체크박스입니다.

• 출력 값:
  • 템플릿 대체 시: 체크 시 on_true 값, 해제 시 on_false 값입니다.
  • 태그로 전송 시: 체크 시 1b, 해제 시 0b입니다.
• initial (boolean, 선택 사항):
  • 체크박스의 초기 값입니다. (기본값: false (체크 해제))
• on_true (문자열, 선택 사항):
  • true일 때 전송할 문자열 값입니다. (기본값: 'true')
• on_false (문자열, 선택 사항):
  • false일 때 전송할 문자열 값입니다. (기본값: 'false')

3. minecraft:single_option

미리 설정된 옵션 선택입니다.

• label_visible (boolean, 선택 사항):
  • 레이블 표시 여부를 제어합니다. (기본값: true)
• width (정수, 1~1024, 선택 사항):
  • 입력의 너비입니다. (기본값: 200)
• options (옵션 목록, 필수):
  • 선택할 수 있는 비어 있지 않은 옵션 목록입니다.
    • option (옵션 객체): 각 옵션은 다음을 포함합니다.
      • id (문자열, 필수):
        • 제출 시 전송될 값입니다.
      • display (텍스트 구성 요소):
        • 옵션이 표시되는 방식입니다.
      • initial (boolean, 선택 사항):
        • 하나의 옵션만 true로 설정할 수 있습니다.
        • true이면 해당 옵션이 초기 선택 옵션이 됩니다.
        • 기본값: 첫 번째 옵션이 true, 나머지는 false

4. minecraft:number_range

숫자 슬라이더입니다.

• 출력 값:
  • 템플릿 대체 시: 현재 값의 텍스트 표현입니다. 정수는 소수점 없이 전송됩니다.
  • 태그로 전송 시: 현재 값의 float 태그입니다.
• label_format (번역 키, 선택 사항):
  • 레이블을 만드는 데 사용될 번역 키입니다
  • 첫 번째 인수는 label 필드의 내용, 두 번째 인수는 현재 값
  • 기본값: options.generic_value
• width (정수, 1~1024, 선택 사항):
  • 입력의 너비입니다. (기본값: 200)
• start (float, 필수):
  • 슬라이더의 최소값입니다.
• end (float, 필수):
  • 슬라이더의 최대값입니다.
• step (float, 선택 사항):
  • 단계 크기입니다
  • 존재하는 경우 initial + <정수> * step 값만 허용됩니다.
  • 없는 경우 범위 내 모든 값이 허용됩니다
• initial (정수, 선택 사항):
  • 슬라이더의 초기 세팅 값입니다. (기본값: 범위의 중간값)

---

액션 형식 (Action Format)

정적 액션 유형 (Static Action Types)

정적 액션은 입력 필드의 값에 의존하지 않는 액션입니다. 대화 구성 요소의 클릭 이벤트와 동일합니다 (open_file 제외)

기존의 action 태그 대신 type으로 변경하여 사용합니다.

예를 들어, show_dialog를 사용할 때 대화 구성 요소 사용법이 다음과 같다면

    "click_event": {
        "action": "show_dialog",
        "dialog": "custom:my_dialog"
    }

버튼의 경우 다음과 같습니다.

{
    "label": "대화 상자 표시 레이블",
    "action": {
        "type": "show_dialog",
        "dialog": "custom:my_dialog"
    }
}

• open_url:
  • 지정된 URL을 사용자의 기본 웹 브라우저에서 엽니다.
  • type: open_url
  • url (문자열):
    • 사이트의 URL입니다.
• run_command:
  • 지정된 명령어를 실행합니다. 플레이어가 채팅에 명령어를 입력하고 Enter 키를 누른 것처럼 실행됩니다.
  • 단, /say, /tell, /teammsg와 같이 직접 채팅 메시지를 보내는 명령어는 사용할 수 없습니다.
  • 채팅에서 실행되므로 플레이어는 필요한 권한을 가지고 있어야 합니다.
  • 만약 권한이 요구되는 명령어를 사용할 시 경고문이 출력됩니다.

    

  • type: run_command
  • command (문자열): 실
    • 행할 명령어입니다. / 접두사는 필요하지 않습니다.
• suggest_command:
  • 채팅을 열고 지정된 텍스트나 명령어를 채웁니다.
  • 이미 작성 중인 채팅 메시지가 있으면 덮어씁니다.
  • 책에서는 작동하지 않습니다.
    • type: suggest_command
    • command (문자열): 채팅에 채울 명령어입니다. 일반 텍스트도 작동합니다.
• change_page:
  • 쓰여진 책에서만 사용할 수 있습니다. 해당 페이지가 존재하면 지정된 페이지로 변경합니다.
    • type: change_page
    • page (정수): 변경할 페이지입니다.
• copy_to_clipboard:
  • 지정된 텍스트를 클립보드에 복사합니다.
    • type: copy_to_clipboard
    • value (문자열): 복사할 텍스트입니다.
• show_dialog:
  • 지정된 대화 상자를 엽니다.
    • type: show_dialog
    • dialog (문자열 ID 또는 새 대화 상자 정의): 표시할 하나의 대화 상자입니다.
• custom:
  • 서버로 사용자 지정 이벤트를 전송합니다. 바닐라 서버에서는 효과가 없습니다.
    • type: custom
    • id (문자열): 이벤트를 식별하는 ID입니다.
    • payload (문자열, 선택 사항): 이벤트의 페이로드입니다.

동적 액션 유형 (Dynamic Action Types)

입력 컨트롤과 함께 사용할 수 있습니다.

• dynamic/run_command:
  • 제공된 매크로 템플릿을 사용하여 run_command 이벤트를 빌드합니다.
    • type (문자열, 필수): dynamic/run_command
    • template (문자열): 명령어로 해석될 매크로 템플릿이 있는 문자열입니다.
• dynamic/custom:
  • 모든 입력 값을 사용하여 minecraft:custom 이벤트를 빌드합니다.
  • 모든 입력 내용은 각 입력의 key 필드 ID 아래에 해당 입력의 태그 값이 있는 복합 태그 내부에 함께 전송됩니다. 페이로드에 정적 필드를 추가할 수 있습니다.
    • type (문자열, 필수): dynamic/custom
    • additions (객체): 페이로드에 추가될 필드입니다.
    • id (네임스페이스 ID): 이벤트의 네임스페이스 ID입니다.

---

기본 대화 상자 태그 (Dialog Tag)

• #minecraft:pause_screen_additions
  • 해당 태그를 가진 대화상자가 존재할 경우 일시 정지 화면의 버그 제보하기 버튼을 대체합니다.
  • 버튼에는 external_title이 표시됩니다.
  • 서버 링크가 존재할 경우 서버 링크 대화 상자가 이 태그에 있는 것처럼 버튼을 대체합니다.
    • 그 경우 피드백 버튼도 대체될 수 있습니다.
      

      

  • 만약 여러 대화 상자가 태그에 존재할 경우 대화 상자 리스트를 띄우는 사용자 지정 설정 대화상자를 버튼에 배치합니다.

• #minecraft:quick_actions
  • 해당 태그를 가진 대화 상자가 존재할 경우 빠른 행동 키 (기본값 G) 를 통해 해당 대화 상자를 띄울 수 있습니다.
  • 만약 여러 대화 상자가 존재할 경우 대화 상자 리스트를 띄우는 빠른 행동 대화 상자를 띄웁니다.
    • 버튼에는 external_title이 표시됩니다.

---

이 가이드가 마인크래프트 1.21.6의 새로운 대화 상자 기능을 이해하고 활용하는 데 도움이 되기를 바랍니다!