Cocos Creator

← Intégrer le contenu à votre jeu

Cocos Creator 3.8 LTS · TypeScript

Commencez par afficher une seule phrase. Ce petit exemple lit directement les données exportées de La clé du port ; il ne constitue pas un système de dialogue complet. Reliez ensuite ces données à l’interface de votre jeu.

1 · Préparer les fichiers et la scène

Ce guide concerne Cocos Creator 3.8, et non Cocos2d-x. Placez story.json dans assets/resources/story/story.json. Créez un Label sous un Canvas. Attachez FirstText.ts à un nœud et affectez le Label au champ dialogue. Lancez Preview.

story.json · Comprendre les fichiers exportés

2 · Afficher le premier texte

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'; }
    });
  }
}

Résultat attendu : « Welcome to the harbour. I am Mira. » Avec locale = "de" ou le paramètre de langue de : « Willkommen im Hafen. Ich bin Mira. » Une langue absente utilise le texte source. Cet exemple prend en charge les segments de texte ; il ne supprime pas silencieusement les paramètres de substitution.

3 · D'une phrase à une conversation

L’identifiant de texte fixe ci-dessus sert au premier test. Dans votre jeu, choisissez flowRef/entryRef dans story-index.json, puis lisez execution.entries[entryRef].nodeRef et execution.nodes[nodeRef]. Le dialogue courant fournit text.textRef et speakerRef. La suite dépend du champ kind du nœud.

Nom et dialogue : Label.string. Réponses : événements de Button ou Node.EventType.TOUCH_END, en conservant l’identifiant de l’option. À End, définissez node.active = false sur le parent du dialogue. Un changement de langue relit le texte sans changer l’identifiant du nœud courant.

1. Continue et End : suivre les connexions et fermer la boîte de dialogue
2. Choix : identifiant, ordre et suite de la réponse sélectionnée
3. Conditions et variables : dix ou deux pièces d’or
4. Langue : mêmes identifiants, contenu relu dans la langue choisie
5. Command : donner un objet ou ouvrir une boutique
6. Call/Return : appeler une sous-histoire puis revenir

// 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 · Associer vos propres images

Cet extrait complémentaire suppose que le dialogue courant se trouve dans un objet nommé node et que les éléments d’interface cités en commentaire existent. En C++ et MonoGame, speakerRef a déjà été lu dans SpeakerId ou speakerId. La clé est le véritable identifiant de Mira ; le nom et l’emplacement de l’image dépendent de votre jeu. Insérez les lignes aux endroits indiqués.

// 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.

Retrouvez le nom du personnage avec content.characters[speakerRef].nameTextRef, comme pour un texte de dialogue. Si aucune image n’est associée, masquez l’ancien portrait ou affichez une image de remplacement. Les images ne sont pas choisies selon la langue.

Utiliser les références d'image de l'exportation complète

5 · Inclure les fichiers dans le jeu distribué

resources.load utilise un chemin relatif à resources, sans extension. Attendez son callback. Incluez les SpriteFrames ou images référencés dans resources. Vérifiez aussi les chemins et leur casse dans le jeu compilé.

Vérifiez votre résultat

1. Les salutations en anglais et en allemand s'affichent correctement; une langue non disponible revient à l'anglais.
2. Après avoir ajouté la progression, testez les deux réponses, 10 puis 2 pièces d’or, le retour de la sous-histoire et End.
3. Lancez le jeu compilé en dehors du dossier du projet. Les fichiers JSON, les polices et les portraits doivent y être accessibles aussi.

Documentation officielle

Documentation des API et de la configuration utilisées :

• Chargement des ressources et chemins des SpriteFrames
• API JsonAsset
• Label