RPG Maker MZ

← Integre o conteúdo ao seu jogo

RPG Maker MZ · JavaScript + comandos de eventos

Comece exibindo uma frase. Este pequeno exemplo lê diretamente a exportação real do porto; ele ainda não é um sistema completo de diálogos. Depois, conecte os dados à interface do seu jogo.

1 · Prepare os arquivos e a cena

Este guia usa RPG Maker MZ. Copie story.json para data/. Crie um evento de mapa acionado por Action Button. Adicione primeiro o script de carregamento, depois o loop de espera abaixo e, por último, o script de exibição. Reserve a variável de jogo 1 para o texto e a 2 para o mapeamento da imagem. Em seguida, adicione Show Text com \V[1]. Não é necessário um plugin.

story.json · Entenda os arquivos exportados

2 · Exiba o primeiro 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();

Depois, adicione os comandos de evento: Loop → Conditional Branch (Script: $gameTemp.vnleExample.ready) → Break Loop → End → Wait: 1 frame → Repeat Above. Coloque o script de exibição após o loop. Assim, a engine continua respondendo durante o carregamento.

// 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.” Com locale = "de" ou o parâmetro de idioma de: “Willkommen im Hafen. Ich bin Mira.” Se o idioma não estiver disponível, será usado o texto original. Este exemplo aceita segmentos de texto e não descarta placeholders silenciosamente.

3 · De uma frase a uma conversa

O ID de texto fixo acima serve para o primeiro teste. No seu jogo, escolha flowRef/entryRef em story-index.json, leia execution.entries[entryRef].nodeRef e depois execution.nodes[nodeRef]. O diálogo atual fornece text.textRef e speakerRef. A continuação depende do tipo de nó.

Show Text exibe a variável 1 e aguarda confirmação. Show Choices oferece respostas com as ramificações de evento correspondentes. Para uma lista dinâmica da exportação completa, o jogo conecta os IDs das opções ao próprio controlador de escolhas. End encerra os eventos da conversa e remove a imagem do diálogo.

1. Continue e End: siga as conexões e feche a caixa de texto
2. Escolhas: ID da resposta, ordem e continuação selecionada
3. Condições e variáveis: dez ou duas moedas de ouro
4. Idioma: mesmos IDs, conteúdo resolvido novamente
5. Command: entregar um item ou abrir uma loja
6. Call/Return: entrar em uma sub-história e voltar

// 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 · Mapeie suas próprias imagens

Este trecho complementar espera um objeto de diálogo atual chamado node e os elementos de interface indicados nos comentários. Em C++ e MonoGame, speakerRef já foi lido como SpeakerId ou speakerId. A chave do mapeamento é o ID real da personagem Mira; o nome e a localização da imagem pertencem ao seu jogo. Insira as linhas nos locais 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.

Resolva o nome do personagem por content.characters[speakerRef].nameTextRef, como faz com o texto do diálogo. Se faltar um mapeamento, o jogo deve ocultar o retrato anterior ou mostrar uma imagem substituta. As imagens não são selecionadas pelo idioma.

Use as referências de imagem da exportação completa

5 · Distribua os arquivos com o jogo

Depois de gerar a versão para distribuição, confira se data/story.json está presente. Importe imagens pelo editor e leve em conta a opção de excluir arquivos não utilizados. Não presuma que as APIs do MZ funcionem sem alterações no MV, VX Ace ou em outras edições.

Confira o resultado

1. As saudações em inglês e alemão devem aparecer corretamente; um idioma indisponível deve usar o inglês.
2. Ao implementar o fluxo, teste as duas respostas, 10 e 2 moedas de ouro, a volta da sub-história e End.
3. Execute o jogo compilado fora da pasta do projeto. JSON, fontes e retratos também devem estar disponíveis ali.

Documentação oficial

Referências de API e configuração usadas nesta abordagem:

• Comandos de eventos MZ
• Referência do script MZ
• Comandos de mensagem MZ