MojAbble

01 Architecture Overview

Six files (five JS modules + one data file) plus a PHP leaderboard backend, one global namespace (window.MojAbble), loaded via plain <script> tags in dependency order. Dictionary loaded async at boot. Global high scores persisted server-side via flat JSON files.

02 File Map

Each file's role, contents, and size. Zero external dependencies.

03 Game State Machine

Three states, driven by the Game.state property in main.js.

04 Data Flow Pipeline

From player click to screen pixels — the full action-response cycle.

05 Tile Lifecycle

Every tile goes through a sequence of states from board initialization to removal.

Free Tile Detection

A tile is free when two conditions are met:

06 Board Layout — Classic Pyramid

76 tiles across 4 layers. The Layouts.classic() function returns position arrays; adding new layouts is a single new function.

07 Scoring System

Scrabble letter values, length bonuses, and a combo multiplier that rewards consecutive valid words.

Letter Values

Length Bonuses

Combo System

Stuck Mechanics

Three escape valves prevent dead-end boards, each with a strategic cost:

08 Letter Bag Design

Three difficulty-tuned letter pools govern tile generation, each designed around English letter frequency, digraph availability, and word-formation probability for a 68-tile board.

Design Principles

The letter bag is the single most important factor in whether a board feels playable. Three constraints guide every distribution:

The Three Bags

Difficulty Profiles

Shuffle Mechanics

Shuffle redistributes letters across all remaining tiles (not just free ones), preserving the session's letter pool exactly. This is critical: the 68 letters drawn at game start are the only letters for the entire session. Shuffle changes where letters sit, not which letters exist.

Free tiles receive an animated flip effect (spiraling outward from center). Blocked tiles change silently underneath. This means a shuffle can surface previously buried vowels or push frustration letters deeper into the stack - it is genuinely strategic, not just cosmetic.

Sampling & Validation

Letters are drawn without replacement from the difficulty pool until the pool is exhausted, then it refills. For a 68-tile board from a 90-tile pool, ~76% of the pool is used per pass, meaning letter ratios closely track pool weights.

After sampling, a vowel floor check runs: if the vowel count falls below the difficulty minimum (40%/35%/25%), random consonants are replaced with weighted vowels (E > A > I > O > U bias) until the floor is met. This prevents unplayable consonant-heavy boards while keeping each difficulty's character intact.

Why These Numbers

09 Content Moderation

MojAbble filters offensive words from the dictionary at load time using a hashed blocklist. The source code never contains readable slurs - only opaque FNV-1a hashes.

Why Hashing

Storing a plain-text list of slurs in source creates problems: it shows up in code search, triggers CI profanity scanners, and makes the repo itself carry offensive content. Hashing avoids all of this. The approach matches industry practice used by GitHub, Discord, and commercial word games - blocked terms are stored as irreversible hashes so source code stays clean while filtering remains effective.

The FNV-1a Hash

FNV-1a (Fowler-Noll-Vo, variant 1a) is a fast, non-cryptographic hash function. For each input string it produces a 32-bit integer, displayed as an 8-character hex string (e.g., a4705559). Across the 57 blocked words, there are zero collisions - every word maps to a unique hash. The function runs in O(n) time where n is word length, adding negligible overhead to dictionary loading.

function _fnv1a(s) {
  let h = 0x811c9dc5;          // FNV offset basis
  for (let i = 0; i < s.length; i++) {
    h ^= s.charCodeAt(i);     // XOR with byte
    h = Math.imul(h, 0x01000193); // multiply by FNV prime
  }
  return (h >>> 0).toString(16).padStart(8, '0');
}

// words.js - loadDictionary()
const words = text.split(/\r?\n/)
  .filter(w => w.length >= 3 && !_isBlocked(w));
VALID_WORDS = new Set(words);   // 267,627 words, O(1) lookup

function _isBlocked(word) {
  return _BLOCKED.has(_fnv1a(word));
  // _BLOCKED = Set of 57 hex strings (no plaintext slurs)
}

Filtering Pipeline

Policy Decisions

Adding New Blocked Words

To block a new word: compute its FNV-1a hash (run _fnv1a('word') in a browser console), then add the resulting 8-character hex string to the _BLOCKED Set in words.js. No other changes needed - the filtering pipeline picks it up automatically on next dictionary load.

10 Scoreboards & Persistence

Two-tier leaderboard system: a global server-side leaderboard shared by all visitors and a local localStorage leaderboard for personal records. Both track top scores and rarest words. Players enter a name (persisted in localStorage) that appears on the global board.

Global Leaderboard (Server)

Powered by scores.php, a single-file PHP backend using flat JSON storage in a _scores/ directory. No database, no accounts. Score submission happens automatically on game over; the global board is fetched on page load and after each game.

Protections: rate limiting (1 submission per 5 seconds per IP), score range validation (1 - 999,999), name sanitization (alphanumeric, max 16 chars), flock-based file concurrency. The server is best-effort - if unreachable, the game functions normally with local scores only.

Local Leaderboard (localStorage)

Board Tab UI

Both the start screen and game-over screen show a Global / Local tab switcher above the scoreboards. Global is the default view. Tabs swap which dataset renders into the existing score and rare-word lists.

Data Structures

Server and local entries share a similar shape. Select a tab to view each format:

// mojabble_scores entry (localStorage + server)
{
  n:   "Player",       // player name
  s:   1250,           // final score (rounded)
  w:   14,             // words found
  bw:  "QUARTZ",       // best word (uppercase)
  bws: 82,             // best word score
  mc:  5,              // max combo reached
  d:   "normal",       // difficulty
  dt:  "2026-05-19",   // date string
  ts:  1716134400      // unix timestamp (server only)
}

// mojabble_rare entry (localStorage + server)
{
  w:   "QUARTZ",       // word (uppercase)
  r:   82,             // rarity score (baseScore + lengthBonus)
  n:   "Player",       // who found it (server only)
  d:   "normal",       // difficulty
  dt:  "2026-05-19"    // date string
}

// GET scores.php?action=scores
// Response:
{
  scores: [ ... ],     // top 50 score entries
  rare:   [ ... ]      // top 50 rare word entries
}

// POST scores.php?action=submit
// Request body:
{
  n:  "Player",        // player name (max 16 chars)
  s:  1250,            // score (1 - 999,999)
  w:  14,              // words found (1 - 500)
  bw: "QUARTZ",        // best word
  bws: 82,             // best word score
  mc: 5,               // max combo (0 - 200)
  d:  "normal",        // difficulty (easy|normal|hard)
  rw: "QUIXOTIC",      // session's rarest word (optional)
  rr: 85               // rarest word score (optional)
}
// Response: { ok: true, rank: 3 }

Rarity Scoring

A word's rarity score is baseScore + lengthBonus (before combo multiplier). This means rarity reflects intrinsic word difficulty - rare letters and long words - not streak bonuses. The rarest words list only stores unique words; submitting the same word twice does not create a duplicate entry. The session's best rare word is submitted to the server along with the final score.

Word Stats Toast

After every valid word, a toast panel slides in showing three pieces of information:

The toast auto-dismisses after 6 seconds. Each new word submission cancels the previous timer and replaces the toast content immediately.

11 Effects & Juice Pipeline

Every player action triggers layered feedback across visual, audio, and UI channels. The Effects class in render.js manages particles and screen effects; main.js orchestrates timing.

Particle System Details

12 Render Pipeline

Single <canvas>, 2D context, DPR-aware. The game loop runs at ~60fps via requestAnimationFrame.

13 Audio System

100% procedural via Web Audio API — no audio files. AudioContext is lazy-initialized on first user interaction to comply with autoplay policies.

14 Class Reference

All classes live under window.MojAbble. Seven classes, one constants object, one validator.

15 Path to Scale

Architecture decisions that make future expansion straightforward.

17 Changelog

Notable updates to MojAbble, most recent first.