Hugging Face's logo

Spaces:
Ibrahim-Study
/
to-where
Sleeping

App Files Community
to-where / public /admin-guide.md
elyor-ml's picture
elyor-ml
to where game
0f4962a
preview code
|
raw
history blame contribute delete
3.29 kB

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
  2. Adding New Questions
  3. Media Requirements
  4. Question JSON Structure
  5. 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:
{
  "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"]
}
  1. Save the file
  2. 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.