Cocos Creator

← コンテンツをゲームに組み込む

Cocos Creator 3.8 LTS · TypeScript

まず、一文を画面に表示してみましょう。この小さなサンプルは「港の鍵」の実際のエクスポートを直接読み込みます。会話をすべて実行する仕組みではありません。表示できたら、データをゲームのUIにつなげていきます。

1 ・ファイルやシーンの準備

対象はCocos Creator 3.8です。Cocos2d-xではありません。story.jsonをassets/resources/story/story.jsonに置きます。Canvasの下にLabelを作成します。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は、最初の動作確認用です。実際のゲームでは、story-index.jsonからflowRef/entryRefを選び、execution.entries[entryRef].nodeRef、続いてexecution.nodes[nodeRef]を読みます。現在の会話ノードからtext.textRefとspeakerRefを取得します。次へ進む方法はノードのkindによって異なります。

名前と会話はLabel.stringで表示します。回答にはButtonのイベントかNode.EventType.TOUCH_ENDを使い、選択肢のIDを保持します。Endでは会話の親ノードにnode.active = falseを設定します。言語を変更したときは現在のノードIDを維持し、文章だけを読み直します。

1. ContinueとEnd：接続をたどり、会話ボックスを閉じる
2. 選択肢：回答のID、表示順、選択後の進行先
3. 条件と変数：10ゴールドと2ゴールドで試す
4. 言語：同じIDから別の言語の内容を読み出す
5. コマンド: アイテムを与えるか、ショップを開く
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とし、コメントに記載したUI要素が存在することを前提とします。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からの相対パスを拡張子なしで渡します。コールバックを待ってから処理を続けてください。参照するSpriteFrameや画像もresourcesに含めます。ビルド後のゲームでも、パスと大文字・小文字を確認してください。

結果を確認する

1. 英語とドイツ語の挨拶が正しく表示され、対応していない言語では英語に戻ることを確認します。
2. 進行処理を追加したら、両方の回答、所持金10と2、サブストーリーからの復帰、Endを試してください。
3. ビルドしたゲームをプロジェクトフォルダーの外で実行します。JSON、フォント、ポートレートがそこでも読み込めることを確認してください。

公式ドキュメント

この実装で使用するAPIと設定の資料：

• アセットロード/ SpriteFrame パス
• JsonAsset API
• Label