MonoGame

← Połącz treść ze swoją grą

MonoGame 3.8 · DesktopGL · C# / .NET

Zacznij od jednego widocznego zdania. Ten krótki przykład odczytuje bezpośrednio rzeczywisty eksport The Harbour Key; nie jest kompletnym systemem odtwarzania dialogów. Następnie połącz dane z interfejsem swojej gry.

1 · Przygotowanie plików i sceny

Zacznij od projektu MonoGame DesktopGL. Umieść story.json w Content/ i skopiuj go jako surowy plik do katalogu wynikowego (patrz wpis projektu poniżej). Dodaj ReadWelcome do Game1. W Content Pipeline Tool utwórz SpriteFont o nazwie DialogueFont, zbuduj zasoby i wczytaj go przez Content.Load("DialogueFont").

story.json · Opis plików eksportu

2 · Pokaż pierwszy tekst

<ItemGroup>
  <None Update="Content/story.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

Dodaj pola SpriteFont _dialogueFont; i string _dialogueLine = ""; do Game1. W LoadContent użyj _dialogueFont = Content.Load("DialogueFont"); _dialogueLine = ReadWelcome("en");. W Draw, wewnątrz istniejącego bloku SpriteBatch, użyj _spriteBatch.DrawString(_dialogueFont, _dialogueLine, new Vector2(24, 24), Color.White);. Jeśli nie masz SpriteBatch, utwórz go w LoadContent przez new SpriteBatch(GraphicsDevice) i użyj Begin()/End() w Draw.

// Game1.cs: add using System.IO; using System.Text.Json; using System.Text;
// Place this method inside the existing Game1 class.
private string ReadWelcome(string locale)
{
    using var stream = TitleContainer.OpenStream("Content/story.json");
    using var document = JsonDocument.Parse(stream);
    var content = document.RootElement.GetProperty("content");
    const string id = "fd7b61a3-8233-4ba7-8f77-b88b119a91bf";
    var message = content.GetProperty("texts").GetProperty(id).GetProperty("sourceMessage");
    if (content.GetProperty("translations").TryGetProperty(locale, out var table)
        && table.TryGetProperty(id, out var translation))
        message = translation.GetProperty("message");
    var line = new StringBuilder();
    foreach (var segment in message.GetProperty("segments").EnumerateArray())
    {
        if (segment.GetProperty("kind").GetString() != "text")
            throw new InvalidDataException("Text-only example");
        line.Append(segment.GetProperty("text").GetString());
    }
    return line.ToString();
}

Oczekiwany wynik: „Welcome to the harbour. I am Mira.” Przy locale = "de" lub parametrze języka de: „Willkommen im Hafen. Ich bin Mira.” Jeśli język jest niedostępny, zostanie użyty tekst źródłowy. Przykład obsługuje segmenty tekstowe; celowo nie pomija po cichu znaczników podstawianych wartości.

3 · Od jednego zdania do rozmowy

Stały identyfikator tekstu powyżej służy do pierwszego testu. W grze wybierz flowRef/entryRef z story-index.json, odczytaj execution.entries[entryRef].nodeRef, a następnie execution.nodes[nodeRef]. Bieżący dialog udostępnia text.textRef i speakerRef. Dalszy przebieg zależy od typu węzła.

Imię i dialog: SpriteBatch.DrawString między Begin/End. Dla dłuższego tekstu obsłuż zawijanie wierszy i potrzebne znaki czcionki. Prostokąty odpowiedzi oraz obsługa myszy i klawiatury należą do gry; przechowuj ID, nie przetłumaczony tekst. Przy zakończeniu wyłącz rysowanie i wejście przez dialogueOpen = false, nie przez Game.Exit().

1. Continue i End: przechodzenie po połączeniach i zamykanie okna tekstu
2. Wybory: ID odpowiedzi, kolejność i dalsza ścieżka
3. Warunki i zmienne: dziesięć lub dwie sztuki złota
4. Język: te same ID, treść odczytana w innym języku
5. Polecenie: wydanie przedmiotu lub otwarcie sklepu
6. Call/Return: wywołanie pobocznej sekwencji i powrót

// Inside ReadWelcome while document is alive; inspect data before returning.
var nodes = document.RootElement.GetProperty("execution").GetProperty("nodes");
var choice = nodes.GetProperty("42edfff8-b8fe-46bf-ae0d-9e2347b6e726");
foreach (var idToken in choice.GetProperty("optionOrder").EnumerateArray())
{
    string optionId = idToken.GetString();
    var option = choice.GetProperty("options").GetProperty(optionId);
    System.Console.WriteLine(optionId + " " + option.GetProperty("text").GetProperty("textRef").GetString());
}
var branch = nodes.GetProperty("c1c3c372-0a73-4cd0-851d-ede59d5709bb");
int gold = 10; // Repeat with 2.
int minimum = branch.GetProperty("condition").GetProperty("right").GetProperty("value").GetProperty("value").GetInt32();
var next = branch.GetProperty(gold >= minimum ? "whenTrue" : "whenFalse");
System.Console.WriteLine(next.GetProperty("nodeRef").GetString());
// Copy strings/values you need later before disposing JsonDocument.

4 · Przypisz własne obrazy

Ten dodatkowy fragment zakłada dostępność bieżącego obiektu dialogu o nazwie node i elementów interfejsu wymienionych w komentarzach. W C++ i MonoGame speakerRef został już odczytany jako SpeakerId lub speakerId. Klucz to rzeczywisty identyfikator postaci Mira; nazwę i lokalizację obrazu ustalasz w swojej grze. Wstaw linie we wskazanych miejscach.

// Game1 class field, so both LoadContent and Draw can access it:
private readonly System.Collections.Generic.Dictionary<string, Texture2D> portraits = new();
// Inside LoadContent(): import/build mira.png as portraits/mira.
portraits["807b2957-7bab-4a28-83a4-1f3d1589bbc2"] = Content.Load<Texture2D>("portraits/mira");
// Inside a SpriteBatch Begin/End in Draw; speakerId comes from speakerRef:
if (portraits.TryGetValue(speakerId, out var portrait))
    _spriteBatch.Draw(portrait, new Vector2(24, 120), Color.White);

Odczytuj imiona przez content.characters[speakerRef].nameTextRef tak samo jak tekst dialogu. Jeśli brakuje przypisanego obrazu, ukryj poprzedni portret lub pokaż obraz zastępczy. Wybór obrazu nie zależy od języka.

Użyj odwołań do obrazów z pełnego eksportu

5 · Dołącz pliki do gry

W tym przykładzie nie wczytuj JSON przez Content.Load. TitleContainer otwiera surowy plik, a csproj go kopiuje. SpriteFont i tekstury buduj przez Content Pipeline. Zacznij od DesktopGL; inne platformy sprawdź osobno.

Sprawdź wynik

1. Powitania po angielsku i niemiecku wyświetlają się poprawnie; dla niedostępnego języka pojawia się tekst angielski.
2. Po dodaniu obsługi przebiegu sprawdź obie odpowiedzi, 10 i 2 sztuki złota, powrót z pobocznej sekwencji oraz End.
3. Uruchom zbudowaną grę poza folderem projektu. Pliki JSON, czcionki i portrety muszą być dostępne także tam.

Oficjalna dokumentacja

Dokumentacja API i konfiguracji użytych w tej instrukcji:

• TitleContainer.OpenStream
• Konfiguracja i rysowanie SpriteFont
• Dostęp do dokumentów JSON