Crafting Conversation Pack Schemas with Hierarchical Topics

1. The Building Blocks: JSON and JSON Schema

Before we design our specific structure, let's ensure we have a solid grasp of the tools we'll be using. Our entire conversation system will be defined in JSON files, making it easy for us (and modders) to read, write, and extend.

As a CS student, you are almost certainly familiar with JSON. However, a quick review of how to represent hierarchical data is always useful.

While JSON lets us structure our data, JSON Schema lets us define the rules for that structure. It acts as a contract or a blueprint, ensuring that any conversation pack we or a modder creates is valid. This is critical for preventing crashes and making the system robust.

Let's explore what JSON Schema is and how it works.

2. Designing a Hierarchical Conversation Structure

Our goal is a system that is both organized and context-aware. A flat list of every possible dialogue line would be unmanageable. Instead, we'll use a three-level hierarchy inspired by established dialogue systems, similar to the concepts discussed in the "Modular Design for Delivering Character Focused Dialogue in Games" paper.

Our hierarchy will be:

1. Conversation Pack: The top-level container, grouping conversations by broad context (e.g., "Friends," "Strangers," "Romance"). This is analogous to a "module" in the paper.
2. Topic: A specific subject of conversation within a pack (e.g., "Getting to Know You," "Gossip," "Deep Talk").
3. Interaction: A single, actionable line of dialogue the player can choose (e.g., "Ask About Day," "Share a Secret," "Tell a Joke").

This structure allows us to filter options efficiently. First, the game checks which packs are available based on the relationship type. Then, it shows the relevant topics from that pack. Finally, it lists the specific interactions for the chosen topic.

Let's look at how this can be modeled in JSON, drawing inspiration from the practical example in the AFCode tutorial.

Our JSON Structure

Here is a concrete example of what a simple "Strangers" pack might look like in JSON, following our three-level hierarchy.

{
  "id": "pack_strangers",
  "name": "Strangers",
  "conditions": {
    "relationship_type": "Acquaintance" 
  },
  "topics": [
    {
      "id": "topic_introduction",
      "name": "Introductions",
      "interactions": [
        {
          "id": "interaction_ask_name",
          "prompt": "Ask name",
          "outcomes": [
            { "type": "relationship_change", "target": "friendship", "value": 2 },
            { "type": "mood_change", "value": 1 }
          ]
        },
        {
          "id": "interaction_wave",
          "prompt": "Wave",
          "outcomes": [
            { "type": "relationship_change", "target": "friendship", "value": 1 }
          ]
        }
      ]
    }
  ]
}

Let's break this down:

• pack_strangers: The top-level object is the pack. It has a unique id and a display name.
• conditions: This object dictates when this pack is available. Here, it's only for characters who are "Acquaintances".
• topics: An array of topic objects. This pack has one topic: "Introductions".
• interactions: Inside the topic, we have an array of interaction objects. Each has an id, a prompt (what the player sees in the UI), and an array of outcomes.
• outcomes: This is the "effect" of the interaction. It's an array of objects describing what happens, such as changing a relationship score or mood. This makes the system very data-driven.

3. Formalizing with JSON Schema

Now that we have a target JSON structure, let's create the JSON Schema to enforce it. This schema will be a file in our project that our Rust code can use to validate any conversation pack files it loads.

We'll define the structure for each part of our hierarchy: Interaction, Topic, and ConversationPack.

To handle the arrays of objects (like the interactions within a topic), we'll use array-specific keywords. The video on JSON Schema demonstrated this well.

Here is the complete JSON Schema for our conversation packs. We use $defs (definitions) to create reusable schemas for Interaction, Topic, and Outcome, which keeps the main schema clean and readable.

conversation_pack_schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Conversation Pack",
  "description": "A collection of topics and interactions for a specific context.",
  "type": "object",
  "properties": {
    "id": { "type": "string", "description": "Unique identifier for the pack." },
    "name": { "type": "string", "description": "Display name for the pack." },
    "conditions": { "type": "object" },
    "topics": {
      "type": "array",
      "items": { "$ref": "#/$defs/Topic" }
    }
  },
  "required": ["id", "name", "topics"],
  
  "$defs": {
    "Outcome": {
      "type": "object",
      "properties": {
        "type": { "type": "string", "enum": ["relationship_change", "mood_change", "need_change"] },
        "target": { "type": "string" },
        "value": { "type": "number" }
      },
      "required": ["type", "value"]
    },
    "Interaction": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "prompt": { "type": "string" },
        "conditions": { "type": "object" },
        "outcomes": {
          "type": "array",
          "items": { "$ref": "#/$defs/Outcome" }
        }
      },
      "required": ["id", "prompt", "outcomes"]
    },
    "Topic": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "conditions": { "type": "object" },
        "interactions": {
          "type": "array",
          "items": { "$ref": "#/$defs/Interaction" }
        }
      },
      "required": ["id", "name", "interactions"]
    }
  }
}

This schema precisely defines our data contract:

• A conversation pack must be an object with an id, name, and an array of topics.
• Each item in the topics array must conform to the Topic definition.
• A Topic must have an id, name, and an array of interactions.
• An Interaction must have an id, prompt, and an array of outcomes.
• An Outcome has a type, a value, and an optional target (e.g., for specifying which relationship or need to change).

This schema is the blueprint we'll use to build our entire social interaction system. It's structured enough to be reliable but flexible enough to allow for rich, moddable content.

Conclusion

Fantastic work today. We've moved from a conceptual idea of a conversation system to a formal, well-defined data structure. This design is the cornerstone of all social interactions in our game.

Key Takeaways:

• Hierarchical Design: We've structured conversations into a logical Pack -> Topic -> Interaction hierarchy, making them manageable and context-aware.
• Data-Driven Approach: By defining interactions with conditions and outcomes directly in the JSON, we empower ourselves and modders to create new content without writing new code.
• JSON Schema as a Contract: We created a formal JSON Schema to validate our conversation packs, ensuring data integrity and preventing errors. This is a professional practice that makes our system far more robust.

In our next lesson, we will put this schema to use. We'll create our first two conversation pack JSON files—friends.json and strangers.json—and write the Rust code to load and parse them, bringing our design to life in the game engine.