# Colorful Semantics - "To Whom?" Game - Administrator Guide

This guide explains how to customize and manage the Colorful Semantics "To Whom?" educational game.

## Table of Contents
1. [Game Overview](#game-overview)
2. [Adding New Questions](#adding-new-questions)
3. [Media Requirements](#media-requirements)
4. [Question JSON Structure](#question-json-structure)
5. [Troubleshooting](#troubleshooting)

## Game Overview

The "To Whom?" game teaches sentence structure using four colorful semantic components:
- **Orange**: Who (the subject)
- **Yellow**: Doing (the verb phrase)
- **Green**: What (the object)
- **Pink**: To Whom (the recipient)

Players are presented with an image or video and must select the correct recipient ("to whom") from multiple choices.

## Adding New Questions

### Step 1: Prepare Media File
1. Create or select an image (JPG/PNG) or short video (MP4) that clearly shows someone giving something to someone else
2. Name your file without spaces (e.g., `teacher_book.jpg` or `dad_gift.mp4`)
3. Place the file in the `/public/media/` directory

### Step 2: Add Question to JSON
1. Open the file `/public/questions.json`
2. Add a new JSON object to the array, following this structure:

```json
{
  "file": "/media/your_file_name.jpg",
  "who": "The person giving",
  "doing": "is passing/giving/handing",
  "what": "the object being given",
  "to_whom": "to the recipient",
  "distractors": ["wrong option 1", "wrong option 2", "wrong option 3"]
}
```

3. Save the file
4. Refresh the application to see your new question appear in the rotation

## Media Requirements

### Images
- **Formats**: JPG, PNG
- **Recommended size**: 800-1200px wide
- **File size**: Keep under 500KB for optimal performance

### Videos
- **Format**: MP4
- **Duration**: Keep under 5 seconds to minimize load time
- **Resolution**: 720p or lower recommended
- **File size**: Keep under 2MB

## Question JSON Structure

Each question in the `questions.json` file must include these fields:

| Field | Description | Example |
|-------|-------------|---------|
| `file` | Path to media file, starting with "/media/" | "/media/teacher_book.jpg" |
| `who` | The subject (person giving) | "The teacher" |
| `doing` | The verb phrase | "is giving" |
| `what` | The object being given | "a book" |
| `to_whom` | The correct recipient | "to the student" |
| `distractors` | Array of incorrect options | ["to Mom", "to the principal"] |

Notes:
- You can include 1-5 distractors
- The "to_whom" value should start with "to " 
- Keep text short so it fits in the colored boxes

## Troubleshooting

### Media Not Displaying
- Ensure the path in the JSON matches the actual file location
- Check that the file has no spaces in its name
- Verify the file format is supported (JPG, PNG, or MP4)

### Game Not Loading New Questions
- Check JSON file for syntax errors (missing commas, brackets, etc.)
- Ensure the JSON file is properly formatted with square brackets `[]` enclosing all questions
- Refresh the page completely (Ctrl+F5 or Cmd+Shift+R)

### Video Playback Issues
- Make sure the video is in MP4 format
- Try reducing video file size or resolution
- Check if the video codec is widely supported (H.264 recommended)

For additional support, please contact the development team.