# Story Content Schema (Reachy Tales)

This file documents the **actual** schema the `story-engine` reads.
It supersedes the legacy `STORIES_DOCUMENTATION.md` from the original AI_game project.

## Layout

```
content/
├── narrator/
│   └── narrator.json
└── <story_id>/
    ├── manifest.json
    ├── map.json
    ├── flags.json
    ├── story_state_template.json
    ├── characters/<id>.json
    ├── scenes/<id>.json
    └── storylines/chapter<n>/<node_id>.json
```

## File formats

(Brief schema description — kept minimal to avoid drift; engine code is the source of truth.)

### narrator.json / characters/<id>.json
```json
{
  "name": "string",
  "description": "string",
  "introduction": "string",
  "background": "string",
  "goal": "string",
  "voice": "string (OpenAI Realtime voice preset name, e.g. \"cedar\", \"ash\")",
  "voice_tone": "string"
}
```

### manifest.json
```json
{
  "id": "string (matches folder name)",
  "title": "string",
  "description": "string",
  "languages": ["en"],
  "entry_point": "storylines/chapter1/<node_id>.json",
  "narrator": { /* same shape as a character */ }
}
```

### scenes/<id>.json
```json
{
  "name": "string",
  "description": "string",
  "actions": [ { "id": "string", "description": "string", "effects": "string" } ],
  "characters_present": ["character_id_or_name"]
}
```

### storylines/chapter<n>/<node_id>.json
```json
{
  "id": "string",
  "scene": "scene_id",
  "type": "dialogue | narration | character_interaction",
  "speaker": "character_id_or_name | narrator | \"\"",
  "text": "string",
  "actions": [
    {
      "id": "string",
      "description": "string",
      "next": "node_id (optional, end-node if omitted)",
      "effects": { "set_flags": { "flag_name": true } }
    }
  ]
}
```

### map.json
```json
[
  {
    "from": "scene_id",
    "to": "scene_id",
    "description": "string",
    "conditions": [
      {
        "type": "requires_flag",
        "flag": "flag_name",
        "condition_failed": "string (player-facing explanation)"
      }
    ]
  }
]
```

### flags.json
```json
["flag_name_1", "flag_name_2"]
```

## Notes
- All strings are English. Bilingual `{ "en": "...", "fr": "..." }` envelopes from the legacy schema are NOT supported.
- Image fields (`picture`, `cover_image`) are ignored by the engine.