Unreal Engine

← Integra el contenido en tu juego

Unreal Engine 5 · C++

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

Usa un proyecto C++ y un Actor propio colocado en el mapa abierto. Añade Json a las dependencias del módulo en .Build.cs. Pon story.json en Content/Story. Añade la función siguiente al .cpp del Actor y llama a UE_LOG(LogTemp, Display, TEXT("%s"), *ReadWelcome()); en BeginPlay después de Super::BeginPlay(). Consulta el resultado en Output Log.

story.json · Explicación de los archivos exportados

2 · Mostrar el primer texto

// Add these includes at the top of your existing Actor .cpp file.
#include "Misc/FileHelper.h"
#include "Misc/Paths.h"
#include "Dom/JsonObject.h"
#include "Serialization/JsonReader.h"
#include "Serialization/JsonSerializer.h"

// File-local helper; call from your Actor's BeginPlay.
static FString ReadWelcome()
{
    FString Raw;
    if (!FFileHelper::LoadFileToString(Raw, *(FPaths::ProjectContentDir() / TEXT("Story/story.json"))))
        return TEXT("Cannot load story.json");
    TSharedPtr<FJsonObject> Story;
    const auto Reader = TJsonReaderFactory<>::Create(Raw);
    if (!FJsonSerializer::Deserialize(Reader, Story) || !Story.IsValid())
        return TEXT("Invalid JSON");
    // Following accesses expect the supplied, validated Harbour export.
    const auto Content = Story->GetObjectField(TEXT("content"));
    const FString Id = TEXT("fd7b61a3-8233-4ba7-8f77-b88b119a91bf");
    auto Message = Content->GetObjectField(TEXT("texts"))->GetObjectField(Id)->GetObjectField(TEXT("sourceMessage"));
    const FString Locale = TEXT("en");
    const TSharedPtr<FJsonObject>* Table = nullptr;
    const TSharedPtr<FJsonObject>* Translation = nullptr;
    if (Content->GetObjectField(TEXT("translations"))->TryGetObjectField(Locale, Table)
        && (*Table)->TryGetObjectField(Id, Translation))
        Message = (*Translation)->GetObjectField(TEXT("message"));
    FString Line;
    for (const auto& Segment : Message->GetArrayField(TEXT("segments")))
    {
        const auto Part = Segment->AsObject();
        if (Part->GetStringField(TEXT("kind")) != TEXT("text"))
            return TEXT("Text-only example");
        Line += Part->GetStringField(TEXT("text"));
    }
    return Line;
}

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.

Para la barra de diálogo, usa UMG: UTextBlock::SetText(FText::FromString(Line)), UButton::OnClicked y UImage. El widget necesita la dependencia del módulo UMG y sus campos de widgets vinculados. End: usa RemoveFromParent() o cambia la visibilidad y restaura el modo de entrada del juego. El lector JSON anterior no necesita UMG.

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

// Inside ReadWelcome, after Story has been parsed successfully.
const auto Nodes = Story->GetObjectField(TEXT("execution"))->GetObjectField(TEXT("nodes"));
const auto Choice = Nodes->GetObjectField(TEXT("42edfff8-b8fe-46bf-ae0d-9e2347b6e726"));
for (const auto& IdValue : Choice->GetArrayField(TEXT("optionOrder")))
{
    const FString OptionId = IdValue->AsString();
    const auto Option = Choice->GetObjectField(TEXT("options"))->GetObjectField(OptionId);
    UE_LOG(LogTemp, Display, TEXT("%s: %s"), *OptionId, *Option->GetObjectField(TEXT("text"))->GetStringField(TEXT("textRef")));
}
const auto Branch = Nodes->GetObjectField(TEXT("c1c3c372-0a73-4cd0-851d-ede59d5709bb"));
const double Minimum = Branch->GetObjectField(TEXT("condition"))->GetObjectField(TEXT("right"))->GetObjectField(TEXT("value"))->GetNumberField(TEXT("value"));
const int32 Gold = 10; // Repeat with 2.
const auto Next = Branch->GetObjectField(Gold >= Minimum ? TEXT("whenTrue") : TEXT("whenFalse"));
UE_LOG(LogTemp, Display, TEXT("%s"), *Next->GetStringField(TEXT("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.

// In your UUserWidget header; assign the imported texture in its Blueprint defaults.
UPROPERTY(EditDefaultsOnly, Category="Dialogue")
TMap<FString, TObjectPtr<UTexture2D>> Portraits;
// Set the map key to: 807b2957-7bab-4a28-83a4-1f3d1589bbc2
// In widget code, PortraitImage is your bound UImage; SpeakerId comes from speakerRef.
auto* Texture = Portraits.Find(SpeakerId);
PortraitImage->SetBrushFromTexture(Texture ? Texture->Get() : nullptr);
PortraitImage->SetVisibility(Texture && Texture->Get()
    ? ESlateVisibility::Visible : ESlateVisibility::Hidden);

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

Añade Story en Project Settings → Packaging → Additional Non-Asset Directories to Package. FFileHelper utiliza el acceso a archivos de Unreal. No importes este JSON como DataTable: sus tablas anidadas de identificadores no son filas de DataTable. Esta guía usa C++; exponer los resultados a Blueprint es una decisión de tu proyecto.

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:

• Deserialización JSON
• Campos de objeto JSON
• Ajustes de empaquetado
• UMG