Cocos Creator

← Интеграция контента в игру

Cocos Creator 3.8 LTS · TypeScript

Начните с вывода одной фразы. Этот небольшой пример напрямую читает реальные данные экспорта гавани, но ещё не является полноценной системой диалогов. Затем подключите данные к интерфейсу своей игры.

1 · Подготовка файлов и сцены

Здесь используется Cocos Creator 3.8, а не Cocos2d-x. Поместите story.json в assets/resources/story/story.json. Создайте Label внутри Canvas. Добавьте FirstText.ts к узлу и назначьте Label полю dialogue. Запустите Preview.

story.json · Назначение файлов экспорта

2 · Выведите первый текст

import { _decorator, Component, JsonAsset, Label, resources } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('FirstText')
export class FirstText extends Component {
  @property(Label) dialogue: Label | null = null;

  start() {
    resources.load('story/story', JsonAsset, (error, asset) => {
      if (!this.dialogue) return;
      if (error || !asset) { this.dialogue.string = 'Cannot load story.json'; return; }
      try {
        // A data-only sample: validate the complete contract in your integration.
        const story = asset.json as any;
        const locale = 'en';
        const id = 'fd7b61a3-8233-4ba7-8f77-b88b119a91bf';
        const translation = story.content.translations[locale]?.[id];
        const message = translation ? translation.message : story.content.texts[id].sourceMessage;
        this.dialogue.string = message.segments.map((segment: any) => {
          if (segment.kind !== 'text') throw new Error('Text-only example');
          return segment.text;
        }).join('');
      } catch (error) { this.dialogue.string = 'Cannot read this story text'; }
    });
  }
}

Ожидаемый текст: «Welcome to the harbour. I am Mira.» При locale = "de" или параметре языка de: «Willkommen im Hafen. Ich bin Mira.» Если язык отсутствует, используется оригинал. Этот пример поддерживает текстовые сегменты и не отбрасывает подстановочные поля без предупреждения.

3 · От одной фразы к разговору

Фиксированный ID текста выше нужен только для первого теста. В игре выберите flowRef/entryRef из story-index.json, прочитайте execution.entries[entryRef].nodeRef, затем execution.nodes[nodeRef]. Текущий диалог содержит text.textRef и speakerRef. Дальнейший путь зависит от типа узла.

Имя и диалог: Label.string. Ответы: события Button или Node.EventType.TOUCH_END с сохранением ID варианта. End: установите node.active = false у родительского узла диалога. При смене языка заново получите текст, сохранив ID текущего узла.

1. Continue и End: переходы по связям и закрытие окна диалога
2. Выбор: ID ответа, порядок и выбранное продолжение
3. Условия и переменные: десять или две золотые монеты
4. Язык: те же ID, заново полученный текст
5. Command: выдать предмет или открыть магазин
6. Call/Return: перейти в подысторию и вернуться

// 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 · Настройте соответствия для своих изображений

Этот дополнительный фрагмент ожидает текущий объект диалога с именем node и элементы интерфейса, указанные в комментариях. В C++ и MonoGame speakerRef уже прочитан как SpeakerId или speakerId. Ключ — реальный ID персонажа Миры, а имя и расположение изображения определяются вашей игрой. Вставьте строки в указанные места.

// Add Sprite and SpriteFrame to the imports from cc.
// Import mira.png at assets/resources/portraits/mira.png as a sprite-frame image.
const portraits: Record<string, string> = {'807b2957-7bab-4a28-83a4-1f3d1589bbc2': 'portraits/mira/spriteFrame'};
const path = portraits[node.speakerRef];
// portrait is the Sprite component assigned by your game.
portrait.spriteFrame = null;
if (path) resources.load(path, SpriteFrame, (error, frame) => {
  if (!error) portrait.spriteFrame = frame;
});
// If the dialogue can advance during loading, discard callbacks from older lines.

Получайте имена персонажей через content.characters[speakerRef].nameTextRef так же, как текст диалога. Если соответствие изображения отсутствует, скройте предыдущий портрет или покажите заглушку. Изображения не выбираются по языку.

Используйте ссылки на изображения из полного экспорта

5 · Включите файлы в сборку игры

resources.load использует путь внутри resources без расширения. Дождитесь callback. Включите используемые SpriteFrames или изображения в resources; проверьте пути и регистр букв также в собранной игре.

Проверьте свой результат

1. Приветствия на английском и немецком отображаются правильно; при выборе недоступного языка используется английский.
2. Добавив выполнение сюжета, проверьте оба ответа, 10 и 2 золотых, возврат из подыстории и End.
3. Запустите собранную игру за пределами папки проекта. JSON, шрифты и портреты должны быть доступны и там.

Официальная документация

Документация по API и настройке для этого подхода:

• Загрузка ресурсов / пути SpriteFrame
• JsonAsset API
• Label