Unity

← Inhalte ins Spiel einbauen

Unity 6 · C# · Newtonsoft Json

Beginne mit einem sichtbaren Satz. Dieses kleine Beispiel liest direkt den echten Harbour-Export; es ist kein vollständiger Dialogplayer. Anschließend verbindest du die Daten mit deiner Spieloberfläche.

1 · Dateien und Szene vorbereiten

Importiere story.json in Assets/Story. Installiere im Package Manager das Unity-Paket com.unity.nuget.newtonsoft-json. Erstelle Canvas → Text - TextMeshPro und importiere bei Bedarf TMP Essentials. Hänge FirstText.cs an ein GameObject. Ziehe die JSON-TextAsset-Datei und das Textobjekt in storyFile und dialogueText im Inspector. Drücke Play.

story.json · Exportdateien erklärt

2 · Den ersten Text anzeigen

using System;
using Newtonsoft.Json.Linq;
using TMPro;
using UnityEngine;

public class FirstText : MonoBehaviour
{
    [SerializeField] private TextAsset storyFile;
    [SerializeField] private TMP_Text dialogueText;
    private JObject story;

    private void Start()
    {
        try { story = JObject.Parse(storyFile.text); ShowLanguage("en"); }
        catch (Exception error) { dialogueText.text = "Cannot read story.json"; Debug.LogException(error); }
    }

    public void ShowLanguage(string locale)
    {
        const string id = "fd7b61a3-8233-4ba7-8f77-b88b119a91bf";
        var content = story["content"];
        var translation = content["translations"]?[locale]?[id];
        var message = translation?["message"] ?? content["texts"][id]["sourceMessage"];
        string line = "";
        foreach (var segment in message["segments"])
        {
            if ((string)segment["kind"] != "text") throw new Exception("Text-only example");
            line += (string)segment["text"];
        }
        dialogueText.text = line;
    }
}

Erwartet: „Welcome to the harbour. I am Mira.“ Mit locale = "de" beziehungsweise dem Sprachparameter de: „Willkommen im Hafen. Ich bin Mira.“ Fehlt die Sprache, wird der Quelltext verwendet. Das Beispiel unterstützt Textsegmente; Platzhalter werden absichtlich nicht stillschweigend übersprungen.

3 · Von einem Satz zum Gespräch

Die feste Text-ID oben dient dem ersten Test. Im Spiel wählst du flowRef/entryRef aus story-index.json, liest execution.entries[entryRef].nodeRef und dann execution.nodes[nodeRef]. Der aktuelle Dialog liefert text.textRef und speakerRef. Fortsetzungen hängen vom Knotentyp ab.

Name/Dialog: TMP_Text.text. Antworten: Button.onClick; die Options-ID in einer lokalen Variable pro Button festhalten. Ende: dialogPanel.SetActive(false). Ein Button kann ShowLanguage mit dem String de aufrufen; dabei wird kein Fortschritt zurückgesetzt.

1. Weiter und Ende: Verbindungen verfolgen, Textbox schließen
2. Choices: Antwort-ID, Reihenfolge und ausgewählter Ausgang
3. Conditions und Variablen: zehn oder zwei Goldstücke
4. Sprache: dieselben IDs, neu aufgelöste Inhalte
5. Command: Gegenstand geben oder einen Shop öffnen
6. Call/Return: Untergeschichte aufrufen und zurückkehren

// Inside a method after story (JObject) has been loaded.
var choice = story["execution"]["nodes"]["42edfff8-b8fe-46bf-ae0d-9e2347b6e726"];
foreach (var optionIdToken in choice["optionOrder"])
{
    string optionId = (string)optionIdToken;
    var option = choice["options"][optionId];
    Debug.Log(optionId + " " + (string)option["text"]["textRef"]);
    // Resolve the text and retain optionId in your Button.onClick listener.
}
var branch = story["execution"]["nodes"]["c1c3c372-0a73-4cd0-851d-ede59d5709bb"];
int gold = 10; // Repeat with 2.
var next = gold >= (int)branch["condition"]["right"]["value"]["value"]
    ? branch["whenTrue"] : branch["whenFalse"];
Debug.Log((string)next["nodeRef"]);

4 · Eigene Bilder zuordnen

Dieses Ergänzungsstück setzt einen aktuellen dialogue-Knoten namens node und die im Kommentar genannten UI-Elemente voraus. Bei C++ und MonoGame ist speakerRef bereits als SpeakerId beziehungsweise speakerId ausgelesen. Der Schlüssel ist Miras tatsächliche Charakter-ID; der Bildname und sein Ablageort gehören deinem Spiel. Füge die Zeilen an den angegebenen Stellen ein.

// Add inside your own MonoBehaviour. Assign a Sprite and a UI Image in Inspector.
[SerializeField] private Sprite miraPortrait;
[SerializeField] private UnityEngine.UI.Image portrait;
// node is the current JObject dialogue:
portrait.sprite = (string)node["speakerRef"] == "807b2957-7bab-4a28-83a4-1f3d1589bbc2" ? miraPortrait : null;
portrait.enabled = portrait.sprite != null;

Sprechernamen über content.characters[speakerRef].nameTextRef genauso wie Dialogtexte auflösen. Eine fehlende Zuordnung soll das alte Porträt ausblenden oder ein Ersatzbild zeigen. Bilder werden nicht nach Sprache gewählt.

Bildverweise aus dem vollständigen Export verwenden

5 · Dateien mit dem Spiel ausliefern

Die referenzierte TextAsset wird mit der Szene eingebunden. Die ID-Tabellen sind JSON-Objekte mit dynamischen Schlüsseln; JsonUtility ist dafür kein direkter Ersatz für JObject. Dieses Beispiel benötigt keinen StreamingAssets-Dateizugriff.

Dein Ergebnis prüfen

1. Der englische und deutsche Begrüßungstext erscheinen korrekt; eine nicht vorhandene Sprache fällt auf Englisch zurück.
2. Beim Ergänzen des Ablaufs: beide Antworten, Gold 10/2, Rückkehr aus der Untergeschichte und Ende ausprobieren.
3. Den gebauten Spielordner außerhalb deines Projekts starten. JSON, Schriften und Porträts müssen dort ebenfalls vorhanden sein.

Offizielle Dokumentation

API- und Einrichtungsreferenzen für diesen Weg:

• Unity Newtonsoft Json package
• TextAsset
• JSON serialization constraints