🃏 Twenty-Four Arena: Speed Buzzer & Bluffing Challenge

A modern, competitive reimagining of the classic 24 card math game featuring speed-buzzer races, psychological bluffing mechanics, adaptive AI bots, exact fractional arithmetic, and zero-dependency Web Audio API synthesis.

• About the Project
• Key Features
• Game Rules & Mechanics
• Architecture & Algorithms
  • 1. Exact Fraction Arithmetic Engine (Fraction)
  • 2. Algorithmic 24 Solver (Binary Expression Trees)
  • 3. Adaptive AI Controller & Bluffing Heuristics
  • 4. Pure Synthesized Audio (Web Audio API)
• Keyboard Hotkeys
• Directory Structure
• Getting Started
• Running Unit Tests
• Deployment Guide
• License

Twenty-Four Arena draws inspiration from the classic arithmetic card game "24", where players are dealt 4 numbers (1–9) and must combine them using elementary operations (+, -, ×, ÷) to yield an exact result of 24.

However, this version introduces high-stakes social and strategic tension:

1. Speed Buzzer Race: Players race against each other and the clock to buzz in as soon as they spot a solution.
2. Psychological Bluffing: Players can hit the buzzer even without a confirmed solution—solely to avoid becoming the last player!
3. The Accuser's Dilemma: The slowest player to buzz becomes the Accuser and must pick one earlier player to prove their math on the interactive workbench within 30 seconds.
4. Life Stakes (3 ❤️): If verified, the Accuser loses 1 life. If the challenged player fails or was bluffing, the challenged player loses 1 life.
5. Impossible Hands Claim: Approximately ~20% of 4-digit combinations are mathematically impossible to solve. Observant players can buzz with an "Impossible / No Solution" claim to turn the tables!

• 🎮 Flexible Multiplayer (2–4 Players): Play locally on a single keyboard with friends or against autonomous AI opponents.
• 🤖 Adaptive Bot AI with 3 Difficulty Profiles:
  • Easy: Relaxed human-like reaction delays, occasional calculation misses.
  • Medium: Balanced reflexes, capable of tactical bluffing under time pressure.
  • Hard: Sub-second cognitive speed, detects complex fractional paths and impossible hands.
• 📐 Interactive Proof Workbench: Step-by-step calculation workbench with intermediate result cards, live calculation history pills, Undo, and Reset functionality.
• 🔊 Zero-Dependency Acoustic Synthesizer: Powered by pure Web Audio API without any external audio asset files. Features authentic brass desk bell acoustics with harmonic overtones, card snaps, buzzer errors, and victory fanfares.
• 💎 Modern Neo-Arcade Glassmorphism UI: Dark-mode aesthetic with vibrant glowing accents, fluid animations, responsive layouts, and celebration confetti particle physics.
• 🧪 Unit-Tested Math Engine: Automated test suite guaranteeing accuracy across edge cases (including non-integer intermediate values like $8 / (1 - 1/3) = 24$).

flowchart TD
    A[Start Round: Deal 4 Cards] --> B[Speed Buzzer Race: 60s Timer]
    B -->|Player Buzzes In| C{Have all players buzzed?}
    C -->|No| B
    C -->|Yes / Timer Expires| D[Slowest Player Becomes Accuser]
    D --> E[Accuser Challenges 1 Previous Player]
    E --> F[Interactive Proof Stage: 30s Timer]
    F -->|Successfully Proves 24| G[Accuser Loses 1 Life]
    F -->|Fails / Bluff Exposed| H[Challenged Player Loses 1 Life]
    G --> I{Is there a single survivor?}
    H --> I
    I -->|No| A
    I -->|Yes| J[Grand Champion Crowned]

Standard IEEE 754 floating-point arithmetic introduces rounding inaccuracies (e.g. 8 / (3 - 8/3) evaluates to 24.000000000000004 or fails strict equality checks).

The Fraction class in src/solver.js guarantees deterministic rational precision:

• Stores values as integer numerator (num) and denominator (den).
• Computes the Greatest Common Divisor (GCD) via the Euclidean algorithm to simplify fractions after every operation.
• Arithmetic methods (add, sub, mul, div) operate exclusively on integers.

To verify whether a deal is solvable, the algorithm exhaustively evaluates all number permutations ($4! = 24$) and all operator combinations ($4^3 = 64$) across 5 distinct binary expression tree topologies:

1. ((a op b) op c) op d
2. (a op (b op c)) op d
3. (a op b) op (c op d)
4. a op ((b op c) op d)
5. a op (b op (c op d))

A total of $24 \times 64 \times 5 = 7,680$ expression branches are analyzed in under 2 milliseconds per round.

Located in src/bot.js:

• Calculates dynamic delay intervals tailored to the selected difficulty tier.
• If a valid solution exists, bots buzz based on difficulty-weighted probability distributions.
• If a deal is mathematically unsolvable, Hard bots claim no_solution, while Medium bots may execute a tactical bluff to avoid being caught in last place.
• During the proof stage, bots systematically reconstruct stored solution steps or fumble realistically if caught bluffing.

Implemented in src/audio.js, the audio engine generates sound waves directly inside the browser:

• Metallic Desk Bell: Models the natural resonant frequencies of a physical metal service bell using a fundamental sine frequency (~980 Hz) paired with 3 overtone harmonics with exponential decay curves.
• Card Snap: High-frequency transient micro-envelope.
• Buzzer Error: Distorted sawtooth waveform.
• Victory Fanfare: Ascending major arpeggio sequence (C5 – E5 – G5 – C6).

For local multiplayer on a shared keyboard, each player station is assigned a physical hotkey:

(All buzzers and workbench controls can also be triggered directly via mouse clicks or touch screens).

Twenty-Four/
├── index.html              # Main HTML markup & screen containers (Lobby, Arena, Proof)
├── package.json            # Project dependencies, scripts, and metadata
├── vite.config.js          # Vite bundler configuration
├── test-solver.js          # Unit testing suite for exact fraction & solver algorithms
├── src/
│   ├── main.js             # Application entry point
│   ├── state.js            # Centralized Reactive State Store (Observer / Pub-Sub pattern)
│   ├── solver.js           # Exact Fraction engine & 24 permutation solver
│   ├── bot.js              # Autonomous AI controller & bluffing heuristics
│   ├── audio.js            # Pure Web Audio API sound synthesizer
│   ├── confetti.js         # Canvas particle confetti celebration engine
│   ├── ui.js               # DOM manipulation & event controller
│   └── styles/
│       ├── main.css        # Theme variables, typography, reset rules
│       ├── components.css  # Buttons, cards, badges, modal overlays
│       ├── lobby.css       # Lobby configuration & player setup styles
│       ├── arena.css       # Card table, scoreboard, buzzer stations
│       └── proof.css       # Interactive proof workbench & history tags
└── dist/                   # Production-ready compiled build

• Node.js (version 18+ recommended)
• Git

1. Clone the repository:

   git clone https://github.com/DaffaArigoh/twenty-four-arena.git
   cd twenty-four-arena

2. Install dependencies:

   npm install

3. Start the local development server:

   npm run dev

4. Open your browser and navigate to: http://localhost:3000

To verify exact fractional arithmetic calculations and edge-case permutations:

npm test

Expected test output:

=== Testing Fraction Arithmetic ===
8 / (3 - 1/3) = 3 3

=== Testing Solver Cases ===
Cards: [1, 2, 3, 4] -> HasSolution: true (Expected: true) - PASS
   Sample: ((1 + 2) + 3) × 4 = 24
Cards: [3, 8, 3, 8] -> HasSolution: true (Expected: true) - PASS
   Sample: 8 ÷ (3 - (8 ÷ 3)) = 24
Cards: [1, 5, 5, 5] -> HasSolution: true (Expected: true) - PASS
   Sample: (5 - (1 ÷ 5)) × 5 = 24
...
 ALL SOLVER TESTS PASSED!

This project can be deployed instantly to any static hosting provider:

1. Log in to Vercel.
2. Click "Add New Project" and import twenty-four-arena.
3. Vercel automatically detects the Vite build configuration.
4. Click Deploy — your live application will be available in seconds.

1. Run npm run build to output the optimized static bundle into dist/.
2. Configure a GitHub Actions workflow to publish the dist/ directory to the gh-pages branch.

This project is licensed under the MIT License — see the LICENSE file for details.