🎮 Wordle Battle

A real-time competitive Wordle game where players battle to guess the most 5-letter words within a timed session. Built with Phoenix LiveView for instant, multiplayer gameplay.

🚀 Play Live

---

✨ Features

• 🎯 Real-time Multiplayer - Compete with friends in the same session
• ⚡ Live Updates - See opponent progress in real-time via Phoenix PubSub
• 🏆 Smart Scoring - Bonus points for speed and accuracy
• 💾 Session Persistence - Rejoin games automatically after disconnection
• ⏱️ Timed Rounds - Race against the clock to maximize your score
• 🎨 Color-Coded Feedback - Classic Wordle-style letter hints (green/yellow/gray)
• 📱 Responsive Design - Play on any device
• 🔄 Endless Rounds - Start new games with the same players

🛠️ Tech Stack

• Phoenix Framework 1.8 - Web framework
• Phoenix LiveView 1.1 - Real-time UI without JavaScript
• Elixir - Functional programming language
• GenServer - Stateful game session management
• Tailwind CSS - Styling
• Fly.io - Deployment platform

🎮 How to Play

1. Create or Join a Session - Share the session URL with friends
2. Ready Up - Click ready when all players have joined
3. Guess Words - Type 5-letter words and press Enter
4. Use Color Hints:
   • 🟩 Green - Letter is correct and in the right position
   • 🟨 Yellow - Letter is in the word but wrong position
   • ⬜ Gray - Letter is not in the word
5. Score Points - Each correct word scores points (bonus for fewer attempts!)
6. Race the Clock - Maximize your score before time runs out

🏅 Scoring System

• Base: 1 point per correct word
• Bonuses:
  • 1 attempt: +5 bonus → 6 points total
  • 2 attempts: +3 bonus → 4 points total
  • 3 attempts: +2 bonus → 3 points total
  • 4-6 attempts: +1 bonus → 2 points total
• Failed word: 0 points

🚀 Local Development

Prerequisites

• Elixir 1.18.3 or later
• Erlang 27.1.2 or later
• Node.js (for asset compilation)

Setup

# Clone the repository
git clone <your-repo-url>
cd wordle_battle

# Install dependencies and build assets
mix setup

# Start the Phoenix server
mix phx.server

# Or start in interactive mode
iex -S mix phx.server

Now visit localhost:4000 from your browser.

Development Commands

# Run tests
mix test

# Run pre-commit checks (compile, format, test)
mix precommit

# Build assets
mix assets.build

# Run specific test file
mix test test/path/to/test.exs

# Run only failed tests
mix test --failed

🏗️ Architecture

Game State Management

The game uses a GenServer-based architecture with Phoenix LiveView:

1. WordleServer (GenServer) - Each session runs as a supervised process

   • Manages game state and phase transitions (:lobby → :playing → :game_over)
   • Handles word assignment, guess validation, and scoring
   • Broadcasts state updates via PubSub
   • Persists state across player disconnections

2. WordleLive (LiveView) - Real-time UI for players

   • Subscribes to PubSub for session updates
   • Renders game grid, virtual keyboard, and leaderboard
   • Handles user interactions

3. Dynamic Supervision - Sessions registered via Registry

   • Efficient process lookup
   • Fault-tolerant session management

Word Management

• 2,300+ answer words (common 5-letter words)
• 12,000+ valid guesses (extended dictionary)
• Per-session tracking prevents word repetition
• O(1) validation using MapSet

Player Persistence

• UUID stored in browser localStorage
• Automatic reconnection on page refresh
• Graceful handling of disconnections
• Automated cleanup of inactive sessions

📁 Project Structure

lib/
├── wordle_battle/
│   ├── application.ex          # App supervision tree
│   ├── dictionary.ex            # Word loading and validation
│   └── wordle_server.ex         # Game state GenServer
├── wordle_battle_web/
│   ├── live/
│   │   ├── wordle_live.ex       # Main game LiveView
│   │   └── lobby_live.ex        # Session creation/joining
│   ├── components/
│   │   └── core_components.ex   # Reusable UI components
│   └── router.ex                # Routes
priv/
└── dictionary/
    ├── answer_words.txt         # Curated answer list
    └── valid_guesses.txt        # All valid words

🚢 Deployment

This app is deployed on Fly.io in the Amsterdam region.

Deploy Your Own

# Install flyctl
curl -L https://fly.io/install.sh | sh

# Login to Fly.io
flyctl auth login

# Launch the app (configure as needed)
flyctl launch

# Set secrets
flyctl secrets set SECRET_KEY_BASE=$(mix phx.gen.secret)

# Deploy
flyctl deploy

Configuration

The app uses auto-scaling with a single shared-cpu-1x instance that stops when idle to minimize costs.

See fly.toml for configuration details.

🧪 Testing

Tests use Phoenix.LiveViewTest for comprehensive LiveView testing:

# Example test
test "player can submit a valid guess", %{conn: conn} do
  {:ok, view, _html} = live(conn, "/session/#{session_id}")

  view
  |> form("#guess-form", guess: %{word: "HELLO"})
  |> render_submit()

  assert has_element?(view, "[data-guess='HELLO']")
end

Run tests with: mix test

🎯 Game Mechanics

Guess Validation Algorithm

Two-pass algorithm handles duplicate letters correctly:

1. First pass: Mark exact matches (green)
2. Second pass: Mark present letters (yellow) from remaining pool
3. Remainder: Mark as wrong (gray)

State Machine

:lobby → :playing → :game_over → :lobby (new round)

• Lobby: Players join and ready up
• Playing: Active gameplay with timer
• Game Over: Display winners and final scores

Timer Implementation

• Countdown broadcasts every second via PubSub
• Auto-transition to game over at 0
• Audio notification on expiration

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

This project is open source and available under the MIT License.

🙏 Acknowledgments

• Dictionary words sourced from common Wordle word lists
• Inspired by the original Wordle by Josh Wardle
• Built with the amazing Phoenix Framework

---

Made with ❤️ using Elixir and Phoenix LiveView