Spaces:
Sleeping
Sleeping
| # 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. |