Readme

ClueDraw - Draw & Guess Game

ClueDraw is an innovative Reddit-based rebus puzzle game where players create visual word puzzles by breaking words into sketches, and challenge the community to guess the original word. Think Pictionary meets word puzzles, with a progression system that rewards both creators and solvers!

Current Version: Active development with full feature set including unlimited guessing, community word submissions, and immersive drawing mode.

🎮 What Is ClueDraw?

ClueDraw is a social drawing game that lives inside Reddit posts. Players take turns being artists and detectives:

  • Artists receive a word and break it into 1-4 visual sketches (rebus-style)
  • Detectives view the sketches and try to guess the original word
  • Both roles earn XP and progress through difficulty tiers
  • The game features unlimited guessing, streak bonuses, achievements, and a global leaderboard

The game runs entirely within Reddit using Devvit's web platform, with drawings posted as interactive Reddit posts that anyone in the community can attempt to solve.

Key Innovation: Unlike traditional drawing games with daily limits, ClueDraw offers unlimited attempts - guess as many times as you want without penalties, encouraging experimentation and learning!

How It Works:

  1. Create a Drawing: Click "✏️ Create Drawing" from the home screen to launch an immersive full-screen drawing session
  2. Get Your Word: Receive a random word based on your tier (like "SUNFLOWER")
  3. Draw Sketches: Break the word into parts (SUN + FLOWER) and draw each part on a touch-enabled canvas
  4. Post to Reddit: Your drawing becomes a Reddit post with a tier-specific splash screen
  5. Community Guesses: Other players view your sketches and try to guess the word
  6. Earn XP: Creators earn XP when the first person guesses correctly; solvers earn XP for correct guesses
  7. Submit Words: Suggest new words with hints for the game - earn +5 XP if moderators approve your submission
  8. Level Up: Progress through 3 difficulty tiers (Easy → Medium → Hard) as you gain XP and level up

What Makes This Unique:

  • Rebus Puzzle Mechanics: Unlike traditional drawing games, words are broken into visual components (e.g., RAINBOW = RAIN + BOW)
  • Letter Substitution System: Add complexity with optional letter swaps (e.g., draw "SON" for "SUN" with U=O clue)
  • Immersive Drawing Experience: Full-screen drawing sessions launched via Devvit's immersive mode for distraction-free creation
  • Dual Reward Economy: Both creators and solvers earn XP, encouraging quality puzzles and active participation
  • Unlimited Guessing: No daily limits or penalties - experiment freely until you solve it
  • Progressive Difficulty: Unlock harder tiers as you level up, keeping the challenge fresh
  • Community-Driven: Puzzles appear as Reddit posts, creating organic discovery and social interaction

Key Features:

  • 🎨 HTML5 Canvas-based drawing with touch and mouse support
  • 🖼️ Immersive full-screen drawing mode for distraction-free creation
  • 🧩 Rebus-style puzzles with letter substitution mechanics (e.g., draw "SON" for "SUN" with U=O clue)
  • 📊 Progressive difficulty system (Easy → Medium → Hard) unlocked by leveling up
  • 🏆 20 achievements across 5 categories with claimable XP rewards
  • 📈 Global leaderboard ranked by level and XP
  • 🔥 Daily login bonuses (+5 XP on first activity) and 7-day streak rewards (+140 XP)
  • ♾️ Unlimited guessing - no daily attempt limits, guess as many times as you want!
  • 💡 Community word submissions - suggest new words with hints, earn +5 XP when approved
  • 📱 Mobile-first responsive design with compact 2×2 sketch grid
  • 🔔 Real-time toast notifications for XP gains and achievements
  • 🎯 Auto-focus input for instant guessing
  • 🚫 Smart detection prevents guessing your own drawings or duplicate guesses
  • 🎮 Clean, focused UI with streamlined navigation
  • 🎁 Flat XP rates by tier - no penalties for multiple attempts

✨ Current Implementation Status

The game is fully functional with a complete progression system:

Core Features:

  • Multi-sketch drawing system (1-4 sketches per word)
  • Letter substitution mechanics for creative rebus puzzles
  • Three difficulty tiers (Easy, Medium, Hard) with 10 words each
  • Unlimited guessing - no daily attempt limits, guess as many times as you want!
  • Flat XP rewards based on tier (Easy: 5 XP, Medium: 10 XP, Hard: 15 XP)
  • First-solver bonus: +5 XP for being the first to guess correctly
  • Community word submissions - players can suggest new words with hints (+5 XP when approved by moderators)
  • 20 achievements across 5 categories with claimable XP rewards
  • Global leaderboard ranked by level and XP
  • Daily login bonuses (+5 XP on first activity) and 7-day streak rewards (+140 XP for 7 days)

User Interface:

  • Mobile-first responsive design with touch-optimized controls
  • Compact stats display showing level, XP progress, and streak in header
  • Streamlined single-column navigation layout for all action buttons
  • 2×2 sketch grid for easy viewing on all devices
  • Letter substitution clues prominently displayed at top of each sketch with yellow highlighting
  • Real-time toast notifications for XP gains and achievements
  • Auto-focusing input field for instant guessing
  • Pattern background with subtle diagonal stripes and radial gradients
  • Creator attribution displayed at bottom center of sketch grid
  • Already guessed detection prevents duplicate guessing
  • Creator cannot guess their own drawings

Technical Implementation:

  • React 18 with TypeScript for type safety
  • Express server with Redis data persistence
  • HTML5 Canvas for drawing with SVG export
  • Devvit platform integration for Reddit posts
  • Two entry points: main game interface and immersive drawing creator
  • Daily login tracking with streak bonuses
  • Achievement tracking with progress bars and claimable rewards

🎨 Game Flow

  1. Browse Reddit → See ClueDraw posts in your subreddit feed with engaging splash screens
  2. Click "Play Now" → Opens the game in full-screen mode
  3. Choose Your Role:
    • Create a Drawing → Get a word, draw sketches, post to Reddit
    • Guess a Drawing → View sketches, submit guesses, earn XP
  4. Progress & Compete → Level up, unlock tiers, climb the leaderboard

🌟 What Makes ClueDraw Innovative & Unique

1. Rebus-Style Visual Word Puzzles

  • Unlike traditional drawing games, ClueDraw uses rebus puzzle mechanics where words are broken into visual components
  • Example: "SUNFLOWER" becomes SUN (☀️) + FLOWER (🌸), creating a visual word puzzle
  • Multiple sketches (1-4) combine to form the answer
  • HTML5 Canvas-based drawing with touch and mouse support
  • 60-second timer per sketch keeps the pace engaging
  • Auto-focus input for instant guessing without clicking
  • Drawing tools: Pen (black, 3px), Eraser (white, 20px), Undo, and Clear
  • Unlimited attempts - guess as many times as you want without daily limits

  1. Letter Substitution System

    • Add complexity with optional letter swaps (e.g., draw "SON" instead of "SUN" with U=O clue)
    • Creates an extra layer of wordplay and creativity
    • Makes puzzles more challenging and rewarding
    • Visual clues displayed prominently at the top of each sketch with yellow highlighting (💡 emoji)
    • Substitution rules clearly shown (e.g., "U = O" or "T = (remove)")
    • Primary hints automatically selected for streamlined creation

  2. Dual Reward Economy

    • Creators earn XP when the first person solves their puzzle (10-30 XP based on tier and sketch count)
    • Solvers earn flat XP for correct guesses based on tier:
      • Easy: 5 XP
      • Medium: 10 XP
      • Hard: 15 XP
    • First solver bonus: +5 XP for being the first to guess correctly (total: 10/15/20 XP)
    • Encourages both creating quality puzzles and solving them
    • No penalties - unlimited guessing means you can experiment freely without losing XP

  3. Progressive Difficulty Tiers

    • Tier 1 (Easy): Levels 1-10 - Simple compound words like RAINBOW, FOOTBALL
    • Tier 2 (Medium): Levels 11-25 - Complex words like NIGHTMARE, UNDERSTAND
    • Tier 3 (Hard): Levels 26+ - Challenging words like MISUNDERSTAND, EXTRAORDINARY
    • Unlock new tiers as you level up (50 XP per level)
    • Tier badges displayed with emojis (🟢 Easy, 🟡 Medium, 🔴 Hard)

  4. Daily Engagement Mechanics

    • Unlimited guessing - no daily attempt limits, guess as many times as you want!
    • Daily login bonus: +5 XP awarded on first activity each day (guessing correctly or creating a drawing)
    • 7-day streak bonus: +140 XP for consecutive logins
    • Streak counter resets if you miss a day
    • Encourages consistent play without frustrating restrictions
    • Activity-based tracking: Daily login counted when you actually play, not just open the app

  5. Community-Driven Discovery

    • Puzzles appear as Reddit posts in the subreddit feed
    • Organic discovery through browsing
    • Engaging splash screens with tier-specific messaging
    • Social interaction through shared challenges
    • Creator attribution displayed at bottom center of sketch grid
    • Players can't guess their own drawings (automatic detection)
    • Already-guessed detection prevents duplicate solving

  6. Achievement System with Claimable Rewards

    • 20 achievements tracking various milestones
    • Categories: Drawing creation (4), correct guesses (5), level progression (5), streaks (3), first solves (3)
    • Each achievement awards bonus XP (10-250 XP)
    • Two-step unlock system: Achievements unlock automatically, then players claim XP rewards manually
    • Real-time progress tracking with visual indicators
    • Progress bars show completion percentage for locked achievements
    • Unlocked achievements highlighted with orange border and checkmark
    • Claim button appears for unlocked but unclaimed achievements

  7. Global Leaderboard

    • Ranked by level first, then total XP as tiebreaker
    • Top 100 players displayed with medals for top 3 (🥇🥈🥉)
    • Current player highlighted in the list with orange background
    • Real-time updates as you progress
    • Composite scoring system (level × 1,000,000 + totalXP)
    • Refresh button to manually update rankings

  8. Mobile-First Design

    • Touch-optimized drawing canvas with prevent-scroll
    • Responsive layouts for all screen sizes
    • Full viewport height design (100dvh)
    • 2×2 sketch grid for easy viewing on mobile
    • Clean, streamlined interface with focused navigation
    • Pattern background with diagonal stripes and radial gradients
    • Touch-friendly buttons with large tap targets
    • Smooth scrolling with proper overflow handling

  9. Real-Time Notifications

    • XP gain notifications with animated slide-in entrance
    • Level up celebrations with 🎉 emoji
    • Tier unlock announcements with 🔓 emoji
    • Achievement unlock alerts with 🏆 emoji
    • Auto-dismissing toast system (2-5 seconds)
    • Click to dismiss notifications early
    • Stacked notifications in top-right corner

  10. Community Word Contributions

    • Players can submit new words with hints directly from the home screen
    • Simple prompt-based submission flow for quick contributions
    • Moderator review system with approve/reject workflow
    • Submitters earn +5 XP when their words are approved
    • Expands the game's word database organically through community input
    • Encourages creative hint writing with letter substitution support
    • Tracks submission history per user for accountability

  11. Optimized Guessing Experience

    • All sketches visible at once in a 2×2 grid layout
    • Letter substitution clues displayed at the top of each sketch with yellow highlighting
    • No need to navigate between sketches
    • Clear visual feedback for correct/incorrect guesses
    • Prominent answer reveal with XP display in green banner
    • Creator username displayed at bottom center of sketch grid (text only, no avatar)
    • Auto-focus input field for immediate typing
    • Sticky bottom input always accessible without scrolling
    • Streamlined header with Main Menu button for easy navigation (no distracting counters)
    • Smart detection: Players cannot guess their own drawings
    • Already-guessed protection: Shows message if you've already solved a drawing correctly
    • Unlimited attempts: Keep guessing until you get it right

🎯 How to Play

Game Overview

ClueDraw is a rebus-style drawing puzzle game where players create visual word puzzles and challenge others to guess the original word. It's a two-mode game where you can either create drawing puzzles or solve them:

🎨 Creator Mode:

  • Access from the home screen or via the "Create Drawing Challenge" menu action
  • Receive a random word based on your tier (Easy/Medium/Hard)
  • Choose a hint that breaks the word into 1-4 parts
  • Draw each part on a separate canvas (60 seconds per sketch)
  • Submit your drawing, which gets posted to the subreddit
  • Earn XP when the first person guesses your drawing correctly (10-30 XP based on tier and sketch count)

🔍 Guesser Mode:

  • Browse Reddit posts in the subreddit feed
  • Click "Play Now" on any ClueDraw post to open the game
  • View all sketches in a 2×2 grid with letter substitution clues
  • Submit your guess (unlimited attempts - keep trying until you get it!)
  • Earn XP for correct guesses (2-15 XP based on tier)
  • Get a +5 XP bonus if you're the first person to guess correctly

📊 Progression System:

  • Start at Level 1 with Easy tier access
  • Earn 50 XP to level up (currentXP resets, totalXP accumulates)
  • Unlock Medium tier at Level 11, Hard tier at Level 26
  • Compete on the global leaderboard (ranked by level, then XP)
  • Unlock 20 achievements for various milestones
  • Maintain daily login streaks for bonus XP

Getting Started

When you first open ClueDraw, you'll see the Home Screen with:

  • Compact header with app name, refresh button, and leaderboard button
  • Player stats card showing your current level, XP, and progress bar to next level
  • Tier indicator (Easy/Medium/Hard) showing your current difficulty access
  • Streak counter (🔥) displaying consecutive login days
  • Quick stats showing drawings created and correct guesses
  • Navigation buttons in a streamlined single-column layout:
    • ✏️ Create Drawing: Launch immersive drawing session (large orange gradient button)
    • 💡 Submit Word: Suggest new words with hints for the game (large green gradient button)
    • 🎨 Mine: View your created drawings (white button with border)
    • 🎖️ Awards: Check achievements and claim rewards (white button with border)
    • ❓ Help: Learn how to play (white button with border)

You automatically receive +5 XP as a daily login bonus when you perform your first activity each day (guessing correctly or creating a drawing). This encourages active gameplay rather than just opening the app!

First-Time Experience: If you're a new player, the game automatically creates your profile with Level 1, 0 XP, and Easy tier access.

Submitting Word Suggestions

How to Submit Words:

  1. From Home Screen (Primary Method):

    • Click the "💡 Submit Word" button (green button in the primary actions row)
    • A prompt appears asking for the word to guess (e.g., "RED CARPET")
    • Enter your word and click OK
    • Another prompt asks for hints (comma-separated)
    • Enter hints like: bed(b=r)+car+pet, red+car+pet
    • Click OK to submit
    • Your submission is sent to the moderation queue

  2. From Subreddit Menu (Alternative):

    • Click "Submit Word Suggestion" from the subreddit menu (3 dots)
    • Fill out the form with word and hints
    • Submit for moderator review

Word Submission Guidelines:

  • Word length: 1-50 characters
  • Hints: At least 1 hint required, max 200 characters each
  • Format: Use comma-separated hints
  • Letter substitutions: Use notation like (b=r) to indicate letter swaps
  • Examples:

    • Word: SUNFLOWER

    • Hints: sun+flower, son(o=u)+flower

    • Word: RED CARPET

    • Hints: bed(b=r)+car+pet, red+car+pet

Moderator Review Process:

  • Submissions enter a pending queue
  • Moderators review via "Review Word Submissions" menu action
  • Moderators can approve or reject submissions
  • If approved: You earn +5 XP immediately
  • If rejected: No XP awarded, but you can submit again

XP Reward:

  • +5 XP when your word is approved by moderators
  • XP is awarded automatically upon approval
  • May trigger level ups and tier unlocks
  • Counts toward achievement progress

Status Tracking:

  • Submissions are tracked with status: pending, approved, or rejected
  • You can submit multiple words
  • Each submission is reviewed independently

Creating a Drawing (Artist Mode)

How to Start Creating:

  1. From Home Screen (Primary Method):

    • Click the "✏️ Create Drawing" button on the home screen
    • Opens an immersive full-screen drawing session
    • Dedicated drawing interface without distractions
    • Closes automatically after submission, returning you to Reddit

  2. From Subreddit Menu (Alternative):

    • Click "Create Drawing Challenge" from the subreddit menu
    • Opens the same immersive drawing creator
    • Same functionality as creating from home screen

Step 1: Start Creating

  • Click the "✏️ Create Drawing" button on the home screen
  • This launches an immersive full-screen drawing session (separate from the main app)
  • The system assigns you a random word based on your current tier
  • Words are selected from pre-defined pools (10 easy, 10 medium, 10 hard words)
  • A loading spinner appears while fetching your word
  • The primary hint is automatically selected to streamline the creation process
  • Your tier determines available word difficulties:
    • Levels 1-10: Easy words only
    • Levels 11-25: Easy or Medium (randomly selected)
    • Levels 26+: Easy, Medium, or Hard (randomly selected)

Step 2: Automatic Hint Selection

  • The system automatically selects the primary hint to streamline the creation process
  • Primary hints: No letter substitutions (easier for solvers)
    • Example: RAINBOW = RAIN + BOW
  • Alternative hints: Include letter substitutions for added complexity
    • Example: NIGHTMARE = KNIGHT + MARE (with I=K substitution)
  • The hint determines how many sketches you'll create (1-4 parts)
  • You'll proceed directly to the drawing canvas

Step 3: Draw Your Sketches

  • You'll draw each part of the word separately using the DrawingCanvas component in immersive full-screen mode

  • The canvas displays:

    • All hints horizontally scrollable at the top showing word breakdowns
    • Current sketch counter (e.g., "Sketch 1 of 2") above the canvas
    • Navigation arrows (← →) to move between sketches
    • Drawing tools overlay in top-left corner
    • Action buttons at the bottom

  • Drawing tools (touch-friendly buttons in top-left):

    • ✏️ Pen (black, 3px width) - Draw your sketch
      • Click/tap to select pen tool (highlighted in orange when active)
      • Draw by clicking and dragging (mouse) or touching and dragging (touch)
    • 🧹 Eraser (white, 20px width) - Erase mistakes
      • Click/tap to select eraser tool (highlighted in orange when active)
      • Erase by dragging over areas you want to remove

  • Navigation features:

    • ← → buttons: Navigate between sketches without losing your work (above canvas)
    • ➕ Add Sketch button: Add up to 4 sketches total (bottom-left)
    • 🗑️ Delete button: Remove the current sketch (bottom-right, must have at least 1)
    • Done button: Complete the current sketch and move to next (bottom-right)
    • Your drawings are automatically saved as you navigate between sketches

  • Technical details:

    • Canvas size: 400×400px (responsive on mobile, scales to fit screen)
    • Touch and mouse support with preventDefault to avoid scrolling
    • Path-based drawing system for smooth, continuous lines
    • No time limit - take as long as you need to create quality sketches
    • SVG export for efficient storage and scalable display
    • Real-time rendering with immediate visual feedback
    • Immersive full-screen mode for distraction-free creation

Step 4: Preview & Submit

  • Review all your sketches in a 2-column grid layout (responsive on all devices)

  • The preview screen uses full viewport height with scrollable content

  • Each sketch card shows:

    • Sketch number and word part
    • Letter substitution clue (if applicable)
    • The actual drawing rendered from SVG
    • Restart button to redraw that specific sketch
    • Remove button (only if you have more than 1 sketch)

  • Additional options:

    • Add Another Sketch button (if you have fewer than 4 and more word parts available)
    • Submit Drawing button to finalize and post

Step 5: Success & Earn XP

  • After submission, you'll see a success screen with:

    • 🎉 Celebration animation
    • Confirmation that your drawing was posted
    • Your word and tier displayed in an orange card
    • Information about potential XP earnings when someone first solves your drawing (💰 Potential XP Earnings section)
    • 📍 View Post button to navigate to your Reddit post

  • The immersive drawing session remains open - close it manually to return to Reddit

  • Your drawing appears as a new post in the subreddit feed

  • Your drawing is posted to the subreddit as a new Reddit post with:

    • Title format: Can you guess it? - [Tier Emoji] [TIER] (X sketch[es])
      • Example: "Can you guess it? - 🟢 EASY (2 sketches)"
    • Custom splash screen with tier-specific messaging:
      • 🟢 Easy Challenge: "A fun puzzle to warm up your brain! Perfect for beginners."
      • 🟡 Medium Challenge: "Can you crack this challenge? Test your skills!"
      • 🔴 Hard Challenge: "Only the sharpest minds will solve this! Are you ready?"
    • Play button: "🎮 Play Now" to open the game
    • Post metadata: Drawing ID, tier, sketch count, creation timestamp
    • Drawing data stored in Redis (not in post content)

  • When the first person guesses correctly, you earn XP:

    • Easy: 10 XP (1 sketch), 13 XP (2), 16 XP (3), 20 XP (4)
    • Medium: 15 XP (1 sketch), 18 XP (2), 21 XP (3), 25 XP (4)
    • Hard: 20 XP (1 sketch), 23 XP (2), 26 XP (3), 30 XP (4)

  • Important: Only the first correct guess awards creator XP - no additional XP for subsequent solvers

  • Your totalDrawingsCreated stat increments immediately

  • Daily login bonus (+5 XP) is awarded when you create a drawing (first activity of the day)

Solving a Drawing (Detective Mode)

Step 1: Find a Puzzle

  • Browse Reddit posts in the subreddit feed
  • Look for posts with tier emojis (🟢🟡🔴) and "Draw & Guess" in the title
  • Click the "🎮 Play Now" button on the splash screen
  • The app opens in full-screen mode with the drawing viewer

Step 2: Study the Clues

  • The DrawingViewer component displays all sketches in a 2×2 grid layout:

    • All sketches visible at once for easy comparison
    • Letter substitution clues displayed at the top of each sketch with yellow highlighting (💡 emoji)
    • Each sketch numbered (#1, #2, etc.) if no substitution clue
    • Creator username displayed at the bottom center of the sketch grid
    • Clean, streamlined header: Main Menu button for easy navigation back to home

  • Visual layout:

    • Mobile-optimized: 2×2 grid on all screen sizes for consistency
    • Clean, focused design: Streamlined interface with essential navigation only
    • Clear labeling: Letter clues prominently displayed at top of each sketch
    • Clue highlighting: Yellow background with 💡 emoji for letter substitution hints
    • Maximized viewing space: Interface optimized to show sketches clearly
    • Pattern background: Subtle diagonal stripes with radial gradients for visual appeal

Step 3: Make Your Guess

  • Click the "🎯 Guess It" button to reveal the input field

  • The GuessInput component appears in a white card at the bottom:

    • Text input field (max 50 characters) with auto-focus
    • Placeholder text: "Your guess..."
    • Guess button (disabled when input is empty)
    • Cancel button to hide the input and return to the "Guess It" button

  • Input behavior:

    • Auto-focuses for immediate typing when revealed
    • Guesses are case-insensitive (RAINBOW = rainbow)
    • Whitespace is trimmed automatically
    • Input clears after each submission
    • Real-time feedback with colored borders (green for correct, red for incorrect)
    • Unlimited attempts: Keep guessing until you get it right
    • Click Cancel to hide the input without submitting
    • Already guessed detection: If you've already guessed correctly, you'll see "✓ You already guessed this correctly!" message in a white card instead of the button
    • Creator protection: If you created the drawing, you'll see "🎨 You created this drawing!" message in a white card instead of the button

Step 4: Receive Feedback

  • Incorrect guess:

    • Red border appears on the input field
    • Input remains available for next attempt
    • Feedback clears after 3 seconds
    • No limit: Keep trying as many times as you need

  • Correct guess:

    • ✅ Success notification appears: "Correct! You guessed the word!"
    • Answer is revealed in a large green banner at the top of the screen
    • Shows the correct word in large text (e.g., "✅ RAINBOW")
    • Displays XP earned (e.g., "+10 XP earned!")
    • XP notification also appears as an animated toast in the top-right corner
    • Drawing marked as solved
    • Input is replaced with "✓ You already guessed this correctly!" message

Step 5: Earn XP XP awarded for correct guesses depends on:

  • Flat XP rates by tier:

    • Easy: 5 XP
    • Medium: 10 XP
    • Hard: 15 XP

  • First solver bonus: +5 XP if you're the first person to guess correctly

    • Total XP for first solver: 10/15/20 XP
    • Tracked separately for achievement progress
    • Only awarded once per drawing

  • Daily login bonus: +5 XP awarded on first activity each day (guess or create)

    • Triggers automatically when you make a correct guess
    • Also triggers when you create a drawing

  • Word submission bonus: +5 XP when moderators approve your word suggestion

    • Submit via home screen or subreddit menu
    • Pending submissions reviewed by moderators
    • XP awarded immediately upon approval

  • No penalties: Unlimited guessing means you can keep trying without losing XP

  • XP processing:

    • Automatically added to totalXP and currentXP
    • Level up check performed (50 XP per level)
    • Tier unlock check at levels 11 and 26
    • Leaderboard position updated
    • totalCorrectGuesses stat incremented
    • Animated notification shows XP gain

Progression System

Leveling Up

  • Earn 50 XP to advance one level
  • Your currentXP resets to 0 after leveling up (totalXP continues accumulating)
  • Level up check runs automatically after any XP gain
  • Multiple level ups possible in one action (e.g., 7-day streak bonus)
  • Level up notification appears with 🎉 emoji
  • Progress bar on home screen shows XP toward next level

Tier Unlocks

  • Tier 1 (Easy): Levels 1-10

    • Words: SUNFLOWER, RAINBOW, FOOTBALL, BUTTERFLY, SNOWMAN, STARFISH, CUPCAKE, FIREFLY, MOONLIGHT, SEASHELL
    • Can only create Easy drawings
    • Green tier badge (🟢)

  • Tier 2 (Medium): Levels 11-25

    • Words: NIGHTMARE, UNDERSTAND, BREAKFAST, OUTSTANDING, WATERFALL, LIGHTHOUSE, HANDSHAKE, KEYBOARD, BACKPACK, EYEBROW
    • Can create Easy or Medium drawings (randomly selected)
    • Yellow tier badge (🟡)
    • Tier unlock notification appears at level 11

  • Tier 3 (Hard): Levels 26+

    • Words: MISUNDERSTAND, NEVERTHELESS, EXTRAORDINARY, OVERWHELM, THUNDERSTORM, GRASSHOPPER, SKATEBOARD, FINGERPRINT, EARTHQUAKE, STRAWBERRY
    • Can create Easy, Medium, or Hard drawings (randomly selected)
    • Red tier badge (🔴)
    • Tier unlock notification appears at level 26

Daily Bonuses

  • Login bonus: +5 XP awarded on first activity each day (guessing correctly or creating a drawing)

    • Checked by comparing lastLoginDate with current date
    • Triggers automatically when you perform an activity
    • Updates lastLoginDate to current timestamp
    • No notification shown (silent bonus)

  • Streak tracking: Consecutive days of activity

    • Increments by 1 for consecutive days (daysDiff === 1)
    • Resets to 1 if you miss a day (daysDiff > 1)
    • Displayed with 🔥 emoji on home screen
    • Tracked in player profile

  • 7-day streak bonus: +140 XP when you complete 7 consecutive days

    • Awarded automatically when streak reaches 7
    • Streak counter resets to 0 after bonus (can earn again)
    • Console log: "🔥 7-day streak completed by [username]! Bonus: +140 XP"
    • May trigger multiple level ups

Achievements The Achievements component displays 20 achievements across 5 categories:

  • Drawing Creation (4 achievements):

    • 🎨 First Steps: Create 1 drawing (+10 XP)
    • 🖌️ Artist: Create 5 drawings (+25 XP)
    • 🎭 Master Artist: Create 10 drawings (+50 XP)
    • 🏆 Prolific Creator: Create 25 drawings (+100 XP)

  • Correct Guesses (5 achievements):

    • 🔍 Detective: Guess 1 correctly (+10 XP)
    • 🧠 Sharp Mind: Guess 10 correctly (+25 XP)
    • 🕵️ Master Detective: Guess 25 correctly (+50 XP)
    • 🎯 Puzzle Master: Guess 50 correctly (+100 XP)
    • 👑 Legend: Guess 100 correctly (+200 XP)

  • Level Milestones (5 achievements):

    • ⭐ Rising Star: Reach level 5 (+20 XP)
    • 🌟 Experienced: Reach level 10 (+40 XP)
    • 💫 Expert: Reach level 15 (+60 XP)
    • ✨ Elite: Reach level 25 (+100 XP)
    • 🌠 Legendary: Reach level 50 (+250 XP)

  • Streak Completion (3 achievements):

    • 🔥 Committed: Complete 3-day streak (+15 XP)
    • 🔥🔥 Dedicated: Complete 7-day streak (+50 XP)
    • 🔥🔥🔥 Unstoppable: Complete 14-day streak (+100 XP)

  • First Solver (3 achievements):

    • ⚡ Quick Thinker: Be first to guess 5 drawings (+30 XP)
    • ⚡⚡ Speed Demon: Be first to guess 10 drawings (+60 XP)
    • ⚡⚡⚡ Lightning Fast: Be first to guess 25 drawings (+150 XP)

  • Achievement features:

    • Progress bars for incomplete achievements showing current/target values
    • Unlocked achievements highlighted with orange border and checkmark
    • Locked achievements shown with reduced opacity
    • Real-time progress tracking
    • Automatic unlock check on relevant actions
    • Two-step reward system: Achievements unlock automatically, then players manually claim XP
    • Claim button appears for unlocked but unclaimed achievements: "🎁 Claim +X XP"
    • Claimed achievements show "✓ Claimed" badge
    • Achievement unlocks are checked via /api/achievements/check endpoint
    • XP is awarded when you click the claim button via /api/achievements/claim endpoint

Leaderboard The Leaderboard component displays:

  • Top 100 players globally
  • Ranking algorithm:
    • Primary: Level (descending)
    • Tiebreaker: Total XP (descending)
    • Composite score: level × 1,000,000 + totalXP
  • Visual features:
    • 🥇 Gold medal for rank 1
    • 🥈 Silver medal for rank 2
    • 🥉 Bronze medal for rank 3
    • Numeric rank for positions 4-100
    • Current player highlighted with orange background
    • "(You)" label next to your username
  • Refresh button to manually update
  • Empty state: "😴 No players yet! Be the first!"
  • Updates automatically when you earn XP or level up

Strategy Tips

For Creators:

  • Use clear, recognizable drawings - abstract art makes puzzles too hard

    • The canvas provides pen (✏️) and eraser (🧹) tools for precision
    • Navigate between sketches using ← and → buttons without losing your work
    • No time limit - take as long as you need to create quality sketches

  • More sketches = higher XP when someone solves it (but also harder to solve)

    • 1 sketch: 10-20 XP depending on tier
    • 4 sketches: 20-30 XP depending on tier
    • Balance complexity with solvability

  • Letter substitutions make puzzles more challenging and interesting

    • Alternative hints provide creative wordplay options
    • Substitution clues are displayed to solvers
    • Example: Draw "SON" for "SUN" with "U = O" clue

  • Balance difficulty - too easy gets solved instantly, too hard never gets solved

    • Easy words get solved quickly but give less XP
    • Hard words take longer but reward more XP
    • Consider your audience's skill level

For Solvers:

  • Study all sketches before guessing - don't rush

    • All sketches are visible at once in a 2×2 grid
    • Look for visual patterns and connections across all sketches
    • Letter substitution clues are shown at the top of each sketch with yellow highlighting
    • Clean interface with Main Menu button for easy navigation
    • Focused view maximizes space for the puzzle

  • Letter substitution clues are critical - they tell you what to change

    • "U = O" means replace U with O in the word part
    • "T = (remove)" means remove the T
    • Apply substitutions to what you see drawn

  • Unlimited attempts - take your time and experiment

    • No penalty for wrong guesses
    • Keep trying different combinations until you get it right
    • Learn from each incorrect guess

  • Race to be first for the +5 XP bonus

    • First solver gets extra XP
    • Also counts toward "First Solver" achievements
    • Check new posts frequently

  • Try different word combinations - think creatively about how parts connect

    • Compound words are common (SUN + FLOWER = SUNFLOWER)
    • Consider phonetic similarities
    • Think about rebus puzzle logic
    • Don't be afraid to guess - unlimited attempts mean you can experiment freely

For Everyone:

  • Maintain login streaks for bonus XP (7-day streak = 140 XP!)

    • Open the app daily to keep streak alive
    • Streak counter shows on home screen with 🔥 emoji
    • Missing one day resets streak to 1

  • Check achievements regularly to see progress toward unlocks

    • View from home screen or profile
    • Progress bars show how close you are
    • Some achievements unlock naturally through play

  • Balance creating, solving, and contributing - all activities earn XP

    • Creating: 10-30 XP per first solve
    • Solving: 5-20 XP per correct guess (tier-based + first solver bonus)
    • Word submissions: +5 XP per approved word
    • Diversify your gameplay for maximum XP

  • Submit word suggestions to expand the game and earn XP

    • Click "💡 Submit Word" on home screen
    • Provide creative hints with letter substitutions
    • Earn +5 XP when moderators approve your word
    • Help grow the word database for all players

  • Play daily to maximize XP from login bonuses

    • +5 XP daily login bonus
    • Unlimited guessing on all drawings
    • Consistent play builds streaks and unlocks achievements

Advanced Tips:

  • Monitor the leaderboard to see top player strategies
  • Focus on achievements that are close to completion for quick XP boosts
  • Create drawings at different tiers to appeal to various skill levels
  • Time your guesses - if a drawing is new, you have a better chance at first solver bonus
  • Submit quality word suggestions with creative hints for easy +5 XP rewards
  • Use the profile screen to track your stats and identify areas to improve
  • Contribute to the community by submitting words that are fun and challenging

🛠️ Technology Stack

Getting Started

Make sure you have Node 22 downloaded on your machine before running!

Development

  1. Clone this repository
  2. Run npm install to install dependencies
  3. Run npm run dev to start the development server
  4. Open the playtest URL provided in the terminal (e.g., https://www.reddit.com/r/cluedraw_dev?playtest=cluedraw)

Testing in Devvit Playtest

The app will automatically create a test subreddit (r/cluedraw_dev) when you run npm run dev. You can:

  • Test drawing creation
  • Test guessing functionality
  • Verify XP and level progression
  • Check leaderboard updates
  • Test achievement unlocks

Deployment

  1. Build the app: npm run build
  2. Upload to Reddit: npm run deploy
  3. Publish for review: npm run launch

Note: Apps require review for subreddits with >200 members.

Technical Implementation

Architecture Overview

ClueDraw is built as a full-stack Devvit application with clear separation between client and server:

Application Structure:

  • Monorepo: Single repository with multiple TypeScript projects
  • Client-Server Split: Clear API boundaries with shared types
  • Two Entry Points:
    • index.html → main.tsx → App.tsx (main game interface with home screen, guessing, leaderboard, etc.)
    • drawing.html → drawing.tsx → DrawingApp.tsx (immersive full-screen drawing creator)
  • Immersive Drawing Mode: Uses Devvit's emitEffect API to open drawing sessions in full-screen immersive mode
  • API-First Design: All client-server communication via RESTful /api/ endpoints

Client (src/client/)

  • React 18 with TypeScript for type safety
  • Vite for fast development and optimized production builds
  • Tailwind CSS for styling with custom pattern backgrounds
  • HTML5 Canvas API for drawing functionality
  • Component-based architecture with hooks for state management

Server (src/server/)

  • Express.js server handling API endpoints
  • All endpoints prefixed with /api/ per Devvit requirements
  • Redis for data persistence (player profiles, drawings, leaderboard)
  • Reddit API integration for post creation and user authentication
  • Daily login tracking with streak bonuses

Shared (src/shared/)

  • TypeScript interfaces for type safety across client-server boundary
  • API request/response types
  • Data models (PlayerProfile, Drawing, Sketch, Achievement, etc.)

Key Components

Client Components:

  • App.tsx: Main application shell with routing and global state
  • HomeScreen.tsx: Landing page with player stats, navigation, and immersive drawing launcher
  • DrawingCreator.tsx: Multi-step drawing creation flow (used in immersive mode)
  • DrawingCanvas.tsx: HTML5 canvas with touch/mouse drawing support
  • DrawingViewer.tsx: Display and guess interface for drawings
  • GuessInput.tsx: Input field with validation and feedback
  • Leaderboard.tsx: Top 100 players ranked by level and XP
  • Achievements.tsx: Achievement tracking with progress bars
  • ProfileScreen.tsx: Player statistics and progression
  • Notification.tsx: Toast notification system with animations
  • drawing.tsx: Standalone entry point for immersive drawing sessions

Server Modules:

  • index.ts: Express server with API endpoints and middleware
    • Player management endpoints (/api/player/*)
    • Drawing endpoints (/api/drawing/*)
    • Achievement endpoints (/api/achievements/*)
    • Word submission endpoints (/api/words/*)
    • Menu action handlers (/internal/menu/*)
    • Form submission handlers (/internal/form/*)
  • core/redis.ts: Redis data access layer with store classes
    • PlayerProfileStore, DrawingStore, GuessAttemptStore
    • LeaderboardStore, AchievementStore, WordSubmissionStore
  • core/words.ts: Word database with hints and tier management
  • core/achievements.ts: Achievement definitions and logic
  • core/post.ts: Reddit post creation functionality

Data Flow

  1. Player Authentication: Automatic via Devvit middleware
  2. Drawing Creation: Client → /api/drawing/request-word → /api/drawing/submit → Reddit post
  3. Guessing: Client → /api/drawing/:id → /api/drawing/:id/guess → XP update
  4. Progression: XP gain → Level check → Tier unlock → Leaderboard update
  5. Daily Reset: Middleware checks date change → Reset all daily attempts

Redis Data Structure

Primary Data Stores:

  • player:{userId}: Hash storing PlayerProfile
    • Fields: userId, username, level, totalXP, currentXP, tier, streak, lastLoginDate, totalDrawingsCreated, totalCorrectGuesses, achievements (JSON), createdAt
  • drawing:{drawingId}: Hash storing Drawing data
    • Fields: id, creatorId, creatorUsername, word, tier, sketches (JSON), sketchCount, isSolved, firstCorrectGuesserId, createdAt, postId
  • attempts:{userId}:{drawingId}: Hash storing GuessAttempt
    • Fields: drawingId, userId, totalAttempts, hasGuessedCorrectly (tracks if user already solved this drawing)

Leaderboard & Rankings:

  • leaderboard: Sorted set with composite score (level × 1,000,000 + totalXP)
    • Ensures level takes priority, XP acts as tiebreaker
    • O(log N) insertion and retrieval
    • Efficient range queries for top 100

Achievement Tracking:

  • achievements:{userId}: JSON array of unlocked achievement IDs
  • achievement:progress:{userId}:{achievementId}: Progress counter (string)
    • Tracks progress toward incomplete achievements
    • Used for streak tracking, first guesses, etc.

Word Pools:

  • words:easy: JSON array of easy tier words
  • words:medium: JSON array of medium tier words
  • words:hard: JSON array of hard tier words

Word Submissions:

  • word:submission:{id}: Hash storing WordSubmission data
    • Fields: id, word, hints (JSON), submitterId, submitterUsername, status (pending/approved/rejected), reviewedBy, reviewedAt, createdAt
  • word:submissions:pending: JSON array of pending submission IDs
  • word:submissions:by:user:{userId}: JSON array of user's submission IDs

Daily Login System:

  • Daily login bonus (+5 XP) awarded on first activity each day (guessing correctly or creating a drawing)
  • Streak tracking for consecutive days (increments by 1 for consecutive days, resets to 1 if you miss a day)
  • 7-day streak bonus (+140 XP) when streak reaches 7, then streak resets to 0
  • No daily attempt limits - unlimited guessing on all drawings

Indexes (for efficient queries):

  • drawings:by:creator:{userId}:{drawingId}: Creator's drawing index
  • drawings:by:tier:{tier}:{drawingId}: Tier-based drawing index
  • drawings:unsolved:{drawingId}: Unsolved drawings index

Performance Optimizations

  • Composite scoring for O(log N) leaderboard operations
  • Path-based drawing for smooth canvas performance with real-time rendering
  • Lazy loading of components where applicable
  • Optimized Redis queries with minimal round trips
  • Touch event optimization with preventDefault to avoid scrolling during drawing
  • Responsive design with mobile-first approach
  • SVG export for scalable, lightweight drawing storage
  • On-demand daily reset instead of scanning all keys
  • Automatic achievement checking triggered by relevant actions

Drawing System Implementation

Canvas Technology:

  • HTML5 Canvas API for real-time drawing
  • Path-based rendering system (stores array of points per stroke)
  • Separate paths for pen and eraser tools
  • Real-time preview as you draw
  • SVG export for storage (converts canvas paths to SVG format)

Drawing Tools:

  • Pen: Black stroke, 3px width, round cap and join
  • Eraser: White stroke, 20px width (draws white over existing content)
  • No undo or clear buttons (use eraser to fix mistakes)

Touch & Mouse Support:

  • Unified event handling for both input types
  • touchstart/mousedown: Begin new path
  • touchmove/mousemove: Add points to current path
  • touchend/mouseup: Complete path and add to paths array
  • preventDefault() on all touch events to prevent scrolling

No Time Limit:

  • Take as long as you need to create quality sketches
  • Navigate between sketches freely using ← → buttons
  • Drawings are automatically saved as you navigate

Mobile Responsiveness

  • Full viewport height design (100dvh) for immersive experience
  • Touch-optimized drawing canvas with gesture prevention
  • Responsive grid layouts: 2×2 sketch grid on all screen sizes for consistency
  • Large touch targets: Minimum 44×44px for all interactive elements
  • Simplified headers: Clean design with essential navigation only
  • Single-column navigation: Streamlined button layout for easy thumb access on mobile
  • Scrollable content areas with proper overflow handling
  • Auto-scaling canvas: 400×400px canvas scales to fit mobile screens
  • Sticky bottom input: Always accessible without scrolling

Notification System

Toast Notifications:

  • Position: Fixed top-right corner, stacked vertically
  • Types: XP gain, level up, tier unlock, achievement, success, error, info
  • Auto-dismiss: 2-5 seconds depending on type
  • Manual dismiss: Click notification or X button
  • Animations: Slide-in entrance, fade-out exit
  • Visual design: Color-coded by type with emoji icons

Notification Types:

  • ⭐ XP Gain: Orange background, shows "+X XP" (2s duration)
  • 🎉 Level Up: Purple background, shows new level (4s duration)
  • 🔓 Tier Unlock: Blue background, shows unlocked tier (5s duration)
  • 🏆 Achievement: Yellow background, shows achievement name and XP (5s duration)
  • ✅ Success: Green background, general success messages (3s duration)
  • ❌ Error: Red background, error messages (4s duration)
  • ℹ️ Info: Gray background, informational messages (3s duration)

Implementation:

  • Custom React hook: useNotifications()
  • Convenience methods: showXPGain(), showLevelUp(), showTierUnlock(), etc.
  • Notification container component with stacking logic
  • Unique IDs for each notification to prevent duplicates

Commands

  • npm run dev: Starts a development server where you can develop your application live on Reddit
  • npm run build: Builds your client and server projects
  • npm run deploy: Uploads a new version of your app
  • npm run launch: Publishes your app for review
  • npm run login: Logs your CLI into Reddit
  • npm run check: Type checks, lints, and prettifies your app

Configuration

devvit.json

The app is configured with:

  • App Name: cluedraw (must not be changed for deployment)
  • Redis: Enabled for data persistence (player profiles, drawings, attempts, leaderboard)
  • Reddit API: Enabled for post creation and user authentication
    • Permissions: SUBMIT_POST, SUBSCRIBE_TO_SUBREDDIT
  • Post Configuration:
    • Two entry points:
      • default (index.html): Main game interface with home screen, guessing, leaderboard
      • drawing (drawing.html): Immersive full-screen drawing creator
    • Directory: dist/client
    • Height: tall for optimal viewing experience
  • Server Configuration:
    • Directory: dist/server
    • Entry: index.cjs (CommonJS format)
  • Menu Actions:
    • "Create Drawing Challenge" - Opens immersive drawing session from subreddit menu (all users)
    • "Submit Word Suggestion" - Opens word submission form (all users)
    • "Review Word Submissions" - Opens moderator review interface (moderators only)
  • Forms:
    • submitWordForm: Word submission form with word and hints fields
    • reviewWordForm: Moderator review form with approve/reject options
  • Triggers:
    • onAppInstall: Creates welcome post when app is installed on a subreddit
  • Dev Configuration:
    • Test subreddit: cluedraw_dev (auto-created during development)

Environment Variables

Optional environment variables can be set in .env:

  • DEVVIT_SUBREDDIT: Custom test subreddit for development (default: r/cluedraw_dev)

Game Mechanics

Difficulty Tiers

  • Easy (Levels 1-10): Simple words, lower XP rewards
  • Medium (Levels 11-25): Moderate words, medium XP rewards
  • Hard (Levels 26+): Complex words, higher XP rewards

XP System

  • Guessing: Flat rates by tier (Easy: 5 XP, Medium: 10 XP, Hard: 15 XP)
    • First solver bonus: +5 XP (total: 10/15/20 XP)
    • Unlimited attempts - no penalties for wrong guesses
  • Creating: 10-30 XP when the first person guesses your drawing correctly (based on tier and sketch count)
    • Only awarded on first correct guess
    • No additional XP for subsequent correct guesses
  • Word Submissions: 5 XP per approved word suggestion
    • Submit via home screen or subreddit menu
    • Moderators review and approve/reject submissions
    • XP awarded immediately upon approval
  • Daily Login: 5 XP per day (awarded on first activity: guessing correctly or creating a drawing)
  • 7-Day Streak: 140 XP bonus when streak reaches 7 consecutive days
  • Achievements: Various XP rewards (10-250 XP per achievement, claimable after unlock)

Guessing System

  • Unlimited attempts per drawing - no daily limits
  • Flat XP rates based on tier (Easy: 5 XP, Medium: 10 XP, Hard: 15 XP)
  • First solver bonus: +5 XP (total: 10/15/20 XP)
  • No penalties for incorrect guesses
  • Keep trying until you solve it!
  • Can only solve each drawing once (prevents duplicate XP)
  • Cannot guess your own drawings

Cursor Integration

This template comes with a pre-configured cursor environment. To get started, download cursor and enable the devvit-mcp when prompted.

About this app