MojAbble

01 Architecture Overview

Six files (five JS modules + one data file), one global namespace (window.MojAbble), loaded via plain <script> tags in dependency order. Dictionary loaded async at boot.

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');
}

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 localStorage-backed leaderboards persist across sessions: a top-10 score list and a top-10 rarest-words hall of fame. Both display on the start screen and game-over screen.

localStorage Keys

Data Structures

Each entry is a JSON object stored in an array:

// mojabble_scores entry
{
  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:  "4/11/2026"    // date string
}

// mojabble_rare entry
{
  w:   "QUARTZ",      // word (uppercase)
  r:   82,            // rarity score (baseScore + lengthBonus)
  d:   "normal",      // difficulty
  dt:  "4/11/2026"    // date string
}

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.

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.