RPG Maker MZ

← 게임에 콘텐츠 연결하기

RPG Maker MZ · JavaScript + 이벤트 명령

먼저 문장 하나를 화면에 표시해 보세요. 이 작은 예제는 실제 항구 내보내기 파일을 직접 읽으며, 완전한 대화 재생기는 아닙니다. 이후 데이터를 게임 UI에 연결하세요.

1 · 파일 및 장면 준비

이 안내는 MZ용입니다. story.json을 data/에 복사하세요. Action Button으로 시작하는 맵 이벤트를 만드세요. 로드 스크립트, 아래의 대기 루프, 표시 스크립트 순서로 추가하세요. 게임 변수 1은 텍스트, 2는 이미지 연결 정보용으로 비워 두세요. 이어서 \V[1]이 포함된 Show Text를 추가하세요. 플러그인은 필요하지 않습니다.

story.json · 내보낸 파일 설명

2 · 첫 번째 텍스트 표시

// Event command: Script. The next command waits until loading finishes.
$gameTemp.vnleExample = { ready: false, story: null, error: null };
const request = new XMLHttpRequest();
request.open('GET', 'data/story.json');
request.overrideMimeType('application/json');
request.timeout = 15000;
request.onload = () => {
  try {
    if (request.status >= 400) throw new Error('HTTP ' + request.status);
    $gameTemp.vnleExample.story = JSON.parse(request.responseText);
  } catch (error) { $gameTemp.vnleExample.error = String(error); }
  $gameTemp.vnleExample.ready = true;
};
request.onerror = request.ontimeout = () => {
  $gameTemp.vnleExample.error = 'Cannot load data/story.json';
  $gameTemp.vnleExample.ready = true;
};
request.send();

이벤트 명령을 다음 순서로 추가하세요. Loop → Conditional Branch (Script: $gameTemp.vnleExample.ready) → Break Loop → End → Wait: 1 frame → Repeat Above. 루프 뒤에 표시 스크립트를 넣으세요. 그러면 로딩 중에도 엔진이 응답합니다.

// Event command: Script, AFTER the loading loop below has finished.
const result = $gameTemp.vnleExample;
if (result.error) {
  $gameVariables.setValue(1, result.error);
} else {
  const locale = 'en';
  const id = 'fd7b61a3-8233-4ba7-8f77-b88b119a91bf';
  const content = result.story.content;
  const translation = (content.translations[locale] || {})[id];
  const message = translation ? translation.message : content.texts[id].sourceMessage;
  const line = message.segments.map(segment => {
    if (segment.kind !== 'text') throw new Error('Text-only example');
    return segment.text;
  }).join('');
  $gameVariables.setValue(1, line);
}
// Next event command: Show Text, containing \V[1]. Reserve variable 1 for this sample.

예상 출력은 “Welcome to the harbour. I am Mira.”입니다. locale = "de" 또는 언어 매개변수 de를 사용하면 “Willkommen im Hafen. Ich bin Mira.”가 표시됩니다. 없는 언어는 원문을 사용합니다. 이 예제는 텍스트 세그먼트를 지원하며, 자리표시자를 알림 없이 무시하지 않습니다.

3 · 한 문장에서 대화

위의 고정 텍스트 ID는 첫 번째 테스트용입니다. 게임에서는 story-index.json에서 flowRef/entryRef를 선택하고 execution.entries[entryRef].nodeRef, 이어서 execution.nodes[nodeRef]를 읽으세요. 현재 대화 노드는 text.textRef와 speakerRef를 제공합니다. 다음 진행 방식은 노드 종류에 따라 달라집니다.

Show Text는 변수 1을 표시하고 확인을 기다립니다. Show Choices는 답변과 해당 이벤트 분기를 제공합니다. 전체 내보내기에서 동적으로 만든 답변 목록은 게임의 선택지 처리기에 ID로 연결하세요. End는 대화 이벤트를 끝내고 대화 이미지를 지웁니다.

1. Continue와 End: 연결을 따라 진행하고 대화창 닫기
2. 선택지: 답변 ID, 표시 순서, 선택한 답변의 다음 진행
3. 조건과 변수: 10 또는 2 골드
4. 언어: 같은 ID로 새 언어의 콘텐츠 가져오기
5. 명령: 아이템을 주고 가게를 엽니다.
6. Call/Return: 하위 이야기로 이동했다가 돌아오기

// story is already loaded. Keep each optionId on its answer button.
const choice = story.execution.nodes['42edfff8-b8fe-46bf-ae0d-9e2347b6e726'];
for (const optionId of choice.optionOrder) {
  const option = choice.options[optionId];
  console.log(optionId, option.text.textRef); // Resolve text, then create your button.
}
// Inspect the actual purchase check. This particular node is Gold >= 5.
const branch = story.execution.nodes['c1c3c372-0a73-4cd0-851d-ede59d5709bb'];
const gold = 10; // Repeat with 2, using your current game value.
const next = gold >= branch.condition.right.value.value ? branch.whenTrue : branch.whenFalse;
console.log(next.nodeRef);

4 · 자신의 이미지 연결하기

이 추가 예제는 현재 대화 객체 node와 주석에 적힌 UI 요소가 있다고 가정합니다. C++와 MonoGame에서는 speakerRef를 이미 SpeakerId 또는 speakerId로 읽은 상태입니다. 키는 미라의 실제 캐릭터 ID이며, 이미지 이름과 위치는 게임에서 정합니다. 표시된 위치에 코드를 넣으세요.

// node is your current VNLE dialogue. Reserve variable 2 for this mapping.
$gameVariables.setValue(2, node.speakerRef === '807b2957-7bab-4a28-83a4-1f3d1589bbc2' ? 1 : 0);
// Event commands: if Variable 2 == 1, Show Picture 20: mira from img/pictures.
// Otherwise: Erase Picture 20. Erase it again when the conversation ends.

화자 이름도 대사처럼 content.characters[speakerRef].nameTextRef로 구하세요. 이미지 연결이 없으면 이전 초상화를 숨기거나 대체 이미지를 표시하세요. 이미지는 언어에 따라 선택되지 않습니다.

전체 내보내기의 이미지 참조 사용하기

5 · 게임과 함께 파일 배포하기

배포 후 data/story.json이 있는지 확인하세요. 에디터로 이미지를 가져오고 사용하지 않는 파일 제외 옵션을 고려하세요. MZ API가 MV, VX Ace 등 다른 버전에서 그대로 작동한다고 가정하지 마세요.

결과 확인

1. 영어와 독일어 인사말이 올바르게 표시되고, 사용할 수 없는 언어를 선택하면 영어 원문이 표시되어야 합니다.
2. 진행 로직을 추가했다면 두 답변, 금화 10개와 2개, 하위 이야기에서 돌아오기, End를 시험하세요.
3. 빌드한 게임을 프로젝트 폴더 밖에서 실행하세요. JSON, 글꼴, 초상화가 그곳에서도 제공되어야 합니다.

공식 문서

API 및 이 접근 방식을 위한 설정 참조:

• MZ 이벤트 명령
• MZ 스크립트 참조
• MZ 메시지 명령