RPG Maker MZ

← Integra el contenido en tu juego

RPG Maker MZ · JavaScript + comandos de evento

Empieza mostrando una frase. Este pequeño ejemplo lee directamente la exportación real del puerto; no es un reproductor completo de diálogos. Después, conecta los datos a la interfaz de tu juego.

1 · Preparar archivos y escena

Esta guía es para MZ. Copia story.json en data/. Crea un evento de mapa activado por Action Button. Añade primero el script de carga, después el bucle de espera descrito abajo y por último el script de visualización. Reserva la variable de juego 1 para el texto y la 2 para las asociaciones de imágenes. Añade después una orden Show Text con \V[1]. No hace falta un plugin.

story.json · Explicación de los archivos exportados

2 · Mostrar el primer texto

// 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();

Añade las órdenes de evento: Loop → Conditional Branch (Script: $gameTemp.vnleExample.ready) → Break Loop → End → Wait: 1 frame → Repeat Above. Coloca el script de visualización después del bucle. Así, el motor sigue respondiendo durante la carga.

// 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.

Resultado esperado: «Welcome to the harbour. I am Mira.». Con locale = "de" o el parámetro de idioma de: «Willkommen im Hafen. Ich bin Mira.». Si falta un idioma, se usa el texto original. Este ejemplo admite segmentos de texto; no descarta silenciosamente los marcadores de posición.

3 · De una frase a una conversación

El identificador de texto fijo anterior sirve para la primera prueba. En tu juego, elige flowRef/entryRef en story-index.json, lee execution.entries[entryRef].nodeRef y después execution.nodes[nodeRef]. El diálogo actual proporciona text.textRef y speakerRef. La continuación depende del tipo de nodo.

Show Text muestra la variable 1 y espera confirmación. Show Choices ofrece respuestas con sus ramas de evento. Para una lista dinámica procedente de la exportación completa, el juego conecta los identificadores de opción a su propio controlador de decisiones. End termina los eventos de conversación y retira la imagen del diálogo.

1. Continue y End: seguir las conexiones y cerrar la caja de texto
2. Opciones: ID de respuesta, orden y continuación seleccionada
3. Condiciones y variables: diez o dos monedas de oro
4. Idioma: los mismos IDs, contenido recién resuelto
5. Command: dar un objeto o abrir una tienda
6. Call/Return: entrar en una subhistoria y regresar

// 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 · Asocia tus propias imágenes

Este fragmento adicional espera un objeto de diálogo actual llamado node y los elementos de interfaz indicados en sus comentarios. Para C++ y MonoGame, speakerRef ya se ha leído como SpeakerId o speakerId. La clave es el identificador real del personaje Mira; el nombre y la ubicación de la imagen pertenecen a tu juego. Inserta las líneas en los lugares indicados.

// 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.

Resuelve los nombres de los personajes mediante content.characters[speakerRef].nameTextRef, igual que el texto del diálogo. Si falta una asociación de imagen, oculta el retrato anterior o muestra una imagen de sustitución. Las imágenes no se seleccionan según el idioma.

Usar las referencias de imagen de la exportación completa

5 · Incluye los archivos en el juego

Después de publicar el juego, comprueba que exista data/story.json. Importa las imágenes desde el editor y ten en cuenta la opción que excluye los archivos sin usar. No supongas que las API de MZ funcionan sin cambios en MV, VX Ace u otras ediciones.

Comprueba el resultado

1. Los saludos en inglés y alemán se muestran correctamente; si el idioma no está disponible, se usa el inglés.
2. Al añadir el flujo, prueba ambas respuestas, 10 y 2 monedas de oro, el regreso de la subhistoria y End.
3. Ejecuta el juego compilado fuera de la carpeta del proyecto. El JSON, las fuentes y los retratos también deben estar disponibles allí.

Documentación oficial

Referencias de API y configuración para este enfoque:

• Órdenes de evento de MZ
• Referencia del script MZ
• Órdenes de mensajes de MZ