From bd5626534b5284e0f067e30b7b9028cf4023d30e Mon Sep 17 00:00:00 2001 From: tiennm99 Date: Fri, 24 Apr 2026 23:30:11 +0700 Subject: [PATCH] feat(loldle): add emoji and quote champion-guessing modules Ship two new loldle-family modules mirroring loldle.net's non-classic modes. Text-only MVP (ability/splash phases stay deferred). - loldle-emoji: 5 guesses, emoji-sequence clue. Pool derived algorithmically from classic's champions.json metadata (species/region/resource mapping table) since loldle.net's bundle has no static emoji pool. - loldle-quote: 6 guesses, lore-blurb clue. Pool seeded from Data Dragon champion title + first lore sentence; champion name redacted to ___. - scripts/fetch-ddragon-data.js: single generator for both JSONs. - src/util/normalize-name.js: shared lookup helper; loldle/lookup.js refactored to import it. 35 new tests (484 total passing). Lint clean. --- README.md | 2 + package.json | 1 + .../phase-01-shared-helpers.md | 187 +++++ .../phase-02-emoji-module.md | 173 +++++ .../phase-03-quote-module.md | 147 ++++ .../phase-04-ability-module.md | 155 ++++ .../phase-05-splash-module.md | 143 ++++ .../phase-06-tests-docs.md | 167 +++++ plans/260424-2215-loldle-new-modes/plan.md | 116 +++ ...260424-2215-loldle-ability-splash-modes.md | 357 +++++++++ ...24-2215-loldle-emoji-and-modes-overview.md | 179 +++++ ...esearcher-260424-2215-loldle-quote-mode.md | 278 +++++++ scripts/fetch-ddragon-data.js | 239 ++++++ src/modules/index.js | 2 + src/modules/loldle-emoji/README.md | 31 + src/modules/loldle-emoji/emojis.json | 690 ++++++++++++++++++ src/modules/loldle-emoji/handlers.js | 146 ++++ src/modules/loldle-emoji/index.js | 40 + src/modules/loldle-emoji/lookup.js | 17 + src/modules/loldle-emoji/render.js | 14 + src/modules/loldle-emoji/state.js | 56 ++ src/modules/loldle-quote/README.md | 42 ++ src/modules/loldle-quote/handlers.js | 137 ++++ src/modules/loldle-quote/index.js | 40 + src/modules/loldle-quote/lookup.js | 17 + src/modules/loldle-quote/quotes.json | 690 ++++++++++++++++++ src/modules/loldle-quote/render.js | 16 + src/modules/loldle-quote/state.js | 49 ++ src/modules/loldle/lookup.js | 6 +- src/util/normalize-name.js | 16 + tests/modules/loldle-emoji/handlers.test.js | 93 +++ tests/modules/loldle-emoji/lookup.test.js | 34 + tests/modules/loldle-emoji/render.test.js | 23 + tests/modules/loldle-emoji/state.test.js | 60 ++ tests/modules/loldle-quote/handlers.test.js | 69 ++ tests/modules/loldle-quote/lookup.test.js | 25 + tests/modules/loldle-quote/render.test.js | 22 + tests/modules/loldle-quote/state.test.js | 39 + tests/util/normalize-name.test.js | 21 + wrangler.toml | 2 +- 40 files changed, 4535 insertions(+), 6 deletions(-) create mode 100644 plans/260424-2215-loldle-new-modes/phase-01-shared-helpers.md create mode 100644 plans/260424-2215-loldle-new-modes/phase-02-emoji-module.md create mode 100644 plans/260424-2215-loldle-new-modes/phase-03-quote-module.md create mode 100644 plans/260424-2215-loldle-new-modes/phase-04-ability-module.md create mode 100644 plans/260424-2215-loldle-new-modes/phase-05-splash-module.md create mode 100644 plans/260424-2215-loldle-new-modes/phase-06-tests-docs.md create mode 100644 plans/260424-2215-loldle-new-modes/plan.md create mode 100644 plans/reports/researcher-260424-2215-loldle-ability-splash-modes.md create mode 100644 plans/reports/researcher-260424-2215-loldle-emoji-and-modes-overview.md create mode 100644 plans/reports/researcher-260424-2215-loldle-quote-mode.md create mode 100644 scripts/fetch-ddragon-data.js create mode 100644 src/modules/loldle-emoji/README.md create mode 100644 src/modules/loldle-emoji/emojis.json create mode 100644 src/modules/loldle-emoji/handlers.js create mode 100644 src/modules/loldle-emoji/index.js create mode 100644 src/modules/loldle-emoji/lookup.js create mode 100644 src/modules/loldle-emoji/render.js create mode 100644 src/modules/loldle-emoji/state.js create mode 100644 src/modules/loldle-quote/README.md create mode 100644 src/modules/loldle-quote/handlers.js create mode 100644 src/modules/loldle-quote/index.js create mode 100644 src/modules/loldle-quote/lookup.js create mode 100644 src/modules/loldle-quote/quotes.json create mode 100644 src/modules/loldle-quote/render.js create mode 100644 src/modules/loldle-quote/state.js create mode 100644 src/util/normalize-name.js create mode 100644 tests/modules/loldle-emoji/handlers.test.js create mode 100644 tests/modules/loldle-emoji/lookup.test.js create mode 100644 tests/modules/loldle-emoji/render.test.js create mode 100644 tests/modules/loldle-emoji/state.test.js create mode 100644 tests/modules/loldle-quote/handlers.test.js create mode 100644 tests/modules/loldle-quote/lookup.test.js create mode 100644 tests/modules/loldle-quote/render.test.js create mode 100644 tests/modules/loldle-quote/state.test.js create mode 100644 tests/util/normalize-name.test.js diff --git a/README.md b/README.md index 43b9621..5d5f545 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,8 @@ src/ │ │ └── 0001_trades.sql │ ├── wordle/ # 5-letter guessing game (KV storage, 14k-word dict) │ ├── loldle/ # classic-mode LoL champion guessing (KV storage) +│ ├── loldle-emoji/ # emoji-clue LoL champion guessing (KV storage) +│ ├── loldle-quote/ # lore-blurb LoL champion guessing (KV storage) │ └── misc/ # stub (KV storage) └── util/ └── escape-html.js diff --git a/package.json b/package.json index 5b754b1..9232658 100644 --- a/package.json +++ b/package.json @@ -13,6 +13,7 @@ "build:wordle-data": "node scripts/build-wordle-data.js", "build:semantle-words": "node scripts/build-semantle-words.js", "scrape:loldle-data": "node scripts/scrape-loldle-data.js", + "fetch:ddragon-data": "node scripts/fetch-ddragon-data.js", "deploy": "npm run build && wrangler deploy && npm run db:migrate && npm run register", "db:migrate": "node scripts/migrate.js", "register": "node --env-file-if-exists=.env.deploy scripts/register.js", diff --git a/plans/260424-2215-loldle-new-modes/phase-01-shared-helpers.md b/plans/260424-2215-loldle-new-modes/phase-01-shared-helpers.md new file mode 100644 index 0000000..be46a4c --- /dev/null +++ b/plans/260424-2215-loldle-new-modes/phase-01-shared-helpers.md @@ -0,0 +1,187 @@ +# Phase 01 — Shared scrape + lookup helpers + +## Context + +- [Research: overview + emoji](../reports/researcher-260424-2215-loldle-emoji-and-modes-overview.md) +- [Research: quote](../reports/researcher-260424-2215-loldle-quote-mode.md) +- [Research: ability + splash](../reports/researcher-260424-2215-loldle-ability-splash-modes.md) +- Existing: `scripts/scrape-loldle-data.js`, `src/modules/loldle/lookup.js` + +## Overview + +**Priority:** P0 (blocks 02–05). +**Status:** pending. + +Lay a minimal shared foundation so the four new modules don't each +re-implement champion-name normalization or re-scrape loldle.net five times. + +## Key insights + +- **Bundle check (2026-04-24):** loldle.net's bundle contains classic + attributes only — **zero emoji code points, zero per-champion quote + strings**. Daily answers are fetched encrypted from + `cache.loldle.net/cache.json` and decrypted with AES key `D5XCtTOObw`, + but the cache only holds the single daily rotation, not a full + champion→emoji / champion→quote pool. +- **Pivot (DEVIATION from plan as written):** Emoji sequences are derived + **algorithmically** from classic's existing `champions.json` metadata + (species/regions/positions/resource) via a small mapping table — no new + fetch, no brittle scrape. Quote text uses DDragon's `title` + + first-sentence `lore` blurb. Both data sources are stable and official. +- Data Dragon is the right source for ability/splash — official, stable, no + brittle regex. Scripts hit DDragon once per patch (fortnightly) and cache + to JSON. Bot imports JSON directly. +- `lookup.js`'s `findChampion` stays coupled to the champion-record shape. + Don't hoist it; only hoist the tiny `normalize(s)` helper. + +## Requirements + +**Functional** +- Extended scraper emits three JSONs (keeps `champions.json` plus adds + `emojis.json`, `quotes.json`). +- New DDragon script emits `abilities.json` + `splashes.json`. +- Shared `normalize(s)` helper in `src/util/` for case/space/punctuation- + insensitive matching across all modes. + +**Non-functional** +- Single loldle.net fetch per scrape run (no re-download for each mode). +- DDragon fetch uses `GET /api/versions.json` → latest → one + `champion.json` per champion OR one aggregated `en_US/champion.json` + (list) + per-champion fetches as needed. Prefer aggregated list first, + drill into per-champion only for `skins[]`. +- Scripts idempotent, safe to re-run, short-circuit on "no change". + +## Architecture + +``` +scripts/ +├── scrape-loldle-data.js (EXISTING, extended) +│ └── writes: src/modules/loldle/champions.json +│ + src/modules/loldle-emoji/emojis.json +│ + src/modules/loldle-quote/quotes.json +└── fetch-ddragon-data.js (NEW) + └── writes: src/modules/loldle-ability/abilities.json + + src/modules/loldle-splash/splashes.json + +src/util/ +└── normalize-name.js (NEW, ~10 LOC) + +src/modules/{loldle-emoji,loldle-quote,loldle-ability,loldle-splash}/ + └── (created in phases 02–05) +``` + +## Related code files + +**Modify** +- `scripts/scrape-loldle-data.js` — add extraction for emoji + quote fields. + Regex must accommodate loldle.net's current bundle shape (inspect before + touching; existing regex is the template). +- `.github/workflows/scrape-loldle-data.yml` — no change needed; the + extended scraper writes more files, the workflow's `git diff` check + catches them automatically. + +**Create** +- `scripts/fetch-ddragon-data.js` — fetch DDragon, extract ability + skin + metadata, write two JSONs. +- `src/util/normalize-name.js` — single export `normalize(s)`. +- `src/modules/loldle-emoji/` (empty folder, populated in 02). +- `src/modules/loldle-quote/` (empty folder, populated in 03). +- `src/modules/loldle-ability/` (empty folder, populated in 04). +- `src/modules/loldle-splash/` (empty folder, populated in 05). + +**Delete:** none. + +## Implementation steps + +1. **Create `src/util/normalize-name.js`**: + ```js + export const normalize = (s) => + String(s || "").toLowerCase().replace(/[^a-z0-9]/g, ""); + ``` + Update `src/modules/loldle/lookup.js` to import it (keeps behaviour, + removes the inline duplicate). Run `npm test` — classic loldle tests + must still pass. + +2. **Inspect the live loldle.net bundle** for emoji + quote fields: + ```bash + node -e " + const html = await (await fetch('https://loldle.net/emoji')).text(); + const m = html.match(/js\/index\.[^\"]+\.js/); + const js = await (await fetch('https://loldle.net/' + m[0])).text(); + console.log(js.match(/emoji[s]?:\s*[\"\[][^\n]{0,200}/g)?.slice(0,3)); + console.log(js.match(/quote[s]?:\s*[\"\[][^\n]{0,200}/g)?.slice(0,3)); + " + ``` + Document the ACTUAL shape in this file. Update regex accordingly. + +3. **Extend `scrape-loldle-data.js`**: + - Reuse the single bundle fetch already there. + - Add two new regex passes extracting `championName → emoji` pairs and + `championName → quote` pairs. + - Write `src/modules/loldle-emoji/emojis.json` and + `src/modules/loldle-quote/quotes.json`. Sort by championName. + - Fail LOUDLY if either new regex hits zero matches (prevents silent + schema drift on loldle.net's next bundle). + +4. **Create `scripts/fetch-ddragon-data.js`**: + ``` + GET /api/versions.json → take versions[0] + GET /cdn//data/en_US/champion.json → summary (all champions) + for each championKey: + GET /cdn//data/en_US/champion/.json → full (spells, passive, skins) + write abilities.json: + [{ championName, abilities: [{ slot:"P"|"Q"|"W"|"E"|"R", name, icon:"" }] }] + write splashes.json: + [{ championName, skins: [{ id:0, name:"Classic", url:"" }, ...] }] + ``` + Use `ddragon.leagueoflegends.com`. Parallelize per-champion fetches with + a concurrency cap (10). Cache to a local `.ddragon-cache/` ignored by + git so re-runs within the same patch are instant. + Add npm script: `"fetch:ddragon-data": "node scripts/fetch-ddragon-data.js"`. + +5. **Run both scripts locally**, commit the resulting JSONs. Verify sizes + reasonable (emojis.json < 50 KB; quotes.json < 100 KB; abilities.json + < 500 KB; splashes.json < 300 KB). If abilities.json balloons past 1 MB, + drop fields (keep only slot + icon URL + ability name). + +6. **Run `npm test` + `npm run lint`** — no regressions in classic loldle. + +## Todo + +- [ ] Create `src/util/normalize-name.js` +- [ ] Refactor `src/modules/loldle/lookup.js` to import `normalize` +- [ ] Inspect loldle.net bundle; document emoji + quote regex shape here +- [ ] Extend `scripts/scrape-loldle-data.js` (emoji + quote extraction) +- [ ] Create `scripts/fetch-ddragon-data.js` +- [ ] Add `fetch:ddragon-data` npm script +- [ ] Run both scripts, commit generated JSONs +- [ ] Create 4 empty module folders (placeholders for phases 02–05) +- [ ] `npm test` + `npm run lint` clean + +## Success criteria + +- `npm run scrape:loldle-data` writes 3 JSONs (champions + emojis + + quotes), all non-empty, all sorted by championName. +- `npm run fetch:ddragon-data` writes 2 JSONs with full CDN URLs. +- Classic loldle tests unchanged, still pass. +- No lint warnings. +- Four empty module folders exist, ready for phases 02–05. + +## Risks + +| Risk | Mitigation | +|------|-----------| +| loldle.net bundle schema drifts between now and scrape | Extraction fails loud, re-inspect and update regex | +| DDragon ability icon URL requires version path; version shifts mid-day | Cache URLs with version baked in; fetch script refreshes on demand | +| Per-champion DDragon fetches (165 requests) hit rate limits | Concurrency cap 10; no published DDragon rate limits but be polite | +| abilities.json > 1 MB bloats Workers bundle | Strip fields, keep only slot + icon URL + name | + +## Security + +- No secrets introduced. +- DDragon and loldle.net are public endpoints; no auth. +- Scripts write only to `src/modules/**/*.json` (no directory traversal). + +## Next steps + +Phases 02–05 can start **in parallel** once this phase completes. diff --git a/plans/260424-2215-loldle-new-modes/phase-02-emoji-module.md b/plans/260424-2215-loldle-new-modes/phase-02-emoji-module.md new file mode 100644 index 0000000..8eec3aa --- /dev/null +++ b/plans/260424-2215-loldle-new-modes/phase-02-emoji-module.md @@ -0,0 +1,173 @@ +# Phase 02 — Emoji module (`loldle-emoji`) + +## Context + +- [Research: overview + emoji](../reports/researcher-260424-2215-loldle-emoji-and-modes-overview.md) +- Template: `src/modules/loldle/` (classic) +- Dependency: phase 01 (`emojis.json` written by scraper, `normalize` helper). + +## Overview + +**Priority:** P1 (ship first — simplest mode). +**Status:** pending. + +Guess the champion from an emoji clue. All text-rendered — Telegram renders +emojis natively. No images, no audio, no DDragon. + +## Key insights + +- Emoji sequences are handcrafted by loldle.net (not algorithmic). We only + have what they ship — can't compute our own. +- Progressive reveal on loldle.net works by "unlock one emoji per wrong + guess". On Telegram, we keep it simpler: **show all emojis upfront, fewer + guesses**. Saves edit-message roundtrips. +- Reuse classic's `stats:` shape verbatim. + +## Requirements + +**Functional** +- `/loldle_emoji` → show current round or start fresh; submit a guess if + `` arg provided. +- `/loldle_emoji_giveup` → reveal answer, record loss. +- `/loldle_emoji_stats` → show per-subject play stats. +- 5 guesses per round. +- Subject = user (DM) or chat (group), same rule as classic. +- Champion name lookup identical to classic (case/space/punctuation- + insensitive, unique-prefix fallback). + +**Non-functional** +- Pure KV storage (no D1). Auto-prefixed key `loldle-emoji:game:`. +- Round state: `{ target, guesses, startedAt }` — same shape as classic. +- Champion pool comes from `emojis.json` (phase 01). Only champions with a + non-empty emoji string are eligible. + +## Architecture + +``` +src/modules/loldle-emoji/ +├── index.js # { name, commands, init } export +├── handlers.js # handleEmoji, handleGiveup, handleStats +├── state.js # loadGame/saveGame/clearGame/loadStats/recordResult +├── lookup.js # findChampion over emojis.json (thin wrapper, uses util/normalize-name.js) +├── render.js # board render: emoji block + guesses list +├── emojis.json # [{ championName, emojis:"🦊✨💫" }, ...] (generated) +└── README.md # usage + data source notes +``` + +## Related code files + +**Modify** +- `src/modules/index.js` — add `"loldle-emoji"` to static import map. +- `wrangler.toml` `[vars].MODULES` — append `,loldle-emoji`. +- `.env.deploy` (local) — append `,loldle-emoji` to MODULES. + +**Create** +- Six files listed in Architecture above. + +**Delete:** none. + +## Implementation steps + +1. **Copy `src/modules/loldle/state.js`** → `src/modules/loldle-emoji/state.js`. + Change `MAX_GUESSES = 5`. No other changes needed; same KV shape. + +2. **Create `lookup.js`**: + ```js + import { normalize } from "../../util/normalize-name.js"; + export function findChampion(pool, input) { + const q = normalize(input); + if (!q) return null; + const exact = pool.find((c) => normalize(c.championName) === q); + if (exact) return exact; + const prefix = pool.filter((c) => + normalize(c.championName).startsWith(q)); + return prefix.length === 1 ? prefix[0] : null; + } + ``` + +3. **Create `render.js`** — render the current board: + ``` + 🎭 + + Guesses (/): + • ❌ + • ❌ + ``` + HTML-escape every champion name via `src/util/escape-html.js`. + +4. **Create `handlers.js`** modelled on `loldle/handlers.js`: + - Same subject resolution (`getSubject`). + - Same arg parsing. + - `pickRandomChampion()` picks from `emojisData` (skip champions with + empty emoji string, if any). + - Win / loss / giveup messages reuse classic's tone; swap "classic" → + "emoji" in copy. No stickers for v1 (YAGNI — can add later). + - On win: "🎉 Got it! — solved in Nx/5" + stats update + KV clear. + - On loss: "❌ Answer was " + stats update + KV clear. + +5. **Create `index.js`**: + ```js + import { handleGiveup, handleEmoji, handleStats } from "./handlers.js"; + let db = null; + export default { + name: "loldle-emoji", + init: async ({ db: store }) => { db = store; }, + commands: [ + { name: "loldle_emoji", visibility: "public", + description: "Emoji loldle — guess the champion from emojis", + handler: (ctx) => handleEmoji(ctx, db) }, + { name: "loldle_emoji_giveup", visibility: "public", + description: "Reveal the current emoji answer", + handler: (ctx) => handleGiveup(ctx, db) }, + { name: "loldle_emoji_stats", visibility: "public", + description: "Show your emoji stats (wins, streak)", + handler: (ctx) => handleStats(ctx, db) }, + ], + }; + ``` + +6. **Register** — add to `src/modules/index.js` import map, MODULES env. + +7. **Write minimal README.md** — commands table, KV prefix, data source + note ("regenerated by `npm run scrape:loldle-data`"). + +8. **Run `npm run dev`**, point a test bot at it, verify: + - `/loldle_emoji` shows emojis + empty board. + - `/loldle_emoji Ahri` (assuming Ahri is the answer) wins. + - `/loldle_emoji_giveup` reveals answer. + - `/loldle_emoji_stats` reports play counts. + +## Todo + +- [ ] Create folder + 6 files per Architecture +- [ ] Copy state.js from classic, lower MAX_GUESSES to 5 +- [ ] Import normalize helper from util +- [ ] Render board with HTML-escape +- [ ] Handlers ported from classic, tone tweaked +- [ ] Register in `src/modules/index.js` + MODULES env +- [ ] Write README +- [ ] Local smoke-test (`npm run dev` + test bot) + +## Success criteria + +- Module loads at `installDispatcher` without conflicts. +- `/loldle_emoji` runs end-to-end against loldle.net data. +- Stats persist across rounds, isolated from classic loldle. + +## Risks + +| Risk | Mitigation | +|------|-----------| +| `emojis.json` missing some champions | Pool is whatever loldle.net provides; guard null at render time | +| Emoji rendering differs across Telegram clients | Use standard Unicode emojis (loldle.net already does); no skin-tone variants | +| Player confusion vs classic (two loldle-like commands) | Distinct command name + distinct welcome copy | + +## Security + +- Input passes through `normalize` (strips non-alphanum) before comparison. +- HTML escape all user-submitted and champion-name text in reply. + +## Next steps + +Phase 06 covers tests. Phase 03 (quote) can be built in parallel — same +template. diff --git a/plans/260424-2215-loldle-new-modes/phase-03-quote-module.md b/plans/260424-2215-loldle-new-modes/phase-03-quote-module.md new file mode 100644 index 0000000..81c0aac --- /dev/null +++ b/plans/260424-2215-loldle-new-modes/phase-03-quote-module.md @@ -0,0 +1,147 @@ +# Phase 03 — Quote module (`loldle-quote`) + +## Context + +- [Research: quote mode](../reports/researcher-260424-2215-loldle-quote-mode.md) +- Template: `src/modules/loldle-emoji/` (phase 02) and `src/modules/loldle/`. +- Dependency: phase 01 (`quotes.json` written, `normalize` helper). + +## Overview + +**Priority:** P1 (ship in parallel with emoji). +**Status:** pending. + +Guess the champion from a voice-line text. Text-only for MVP — audio is +explicitly out of scope (bandwidth, CDN rehost TOS risk, storage overhead +per research doc §4). + +## Key insights + +- Quote mode on loldle.net: **binary right/wrong, 6 guesses, audio hint + unlocks after all fails**. We drop audio; keep 6 guesses. +- Quotes can be ambiguous ("For glory!" — Garen, Galio, Jarman...). Fewer + clues than classic; that's OK — the mode IS meant to be hard. +- Pool: ~150 champions with quotes (per research). Every champion in + `quotes.json` must have non-empty `quote` string — filter at load time. + +## Requirements + +**Functional** +- `/loldle_quote` → show current quote or start fresh; submit a guess if arg. +- `/loldle_quote_giveup` → reveal, record loss. +- `/loldle_quote_stats` → per-subject stats. +- 6 guesses. +- Same subject resolution (user id DM / chat id group). + +**Non-functional** +- Pure KV. Prefix: `loldle-quote:`. +- Same round state shape as classic and emoji. +- HTML-escape the quote text before putting it inside `…` so + apostrophes / `<` in a quote don't break render. + +## Architecture + +``` +src/modules/loldle-quote/ +├── index.js +├── handlers.js +├── state.js # MAX_GUESSES = 6 +├── lookup.js # (near-copy of emoji's) +├── render.js # quote block + guesses list +├── quotes.json # [{ championName, quote:"..." }, ...] (generated) +└── README.md +``` + +## Related code files + +**Modify** +- `src/modules/index.js` — register `"loldle-quote"`. +- `wrangler.toml` `[vars].MODULES` + `.env.deploy` — append. + +**Create** +- Seven files listed in Architecture above. + +## Implementation steps + +1. **Copy `loldle-emoji/` as scaffold.** It's 95% the same shape. + +2. **Swap payload:** `emojis.json` → `quotes.json`. `emojis` string field + → `quote` string field. + +3. **`state.js`** — `MAX_GUESSES = 6`. + +4. **`render.js`** — show quote as italic block: + ``` + 🎭 "The true face of desire." + + Guesses (n/6): + • Ahri ❌ + ``` + HTML-escape the quote BEFORE wrapping it in ``. HTML-escape each + champion name. + +5. **`handlers.js`** — port emoji handlers with copy tweaked: + - Welcome line: "🎭 Guess the champion from this quote." + - Win: "🎉 Nailed it! ." + - Loss: "❌ Answer: ." + - No stickers for v1. + +6. **`lookup.js`** — identical to emoji's, change import path. + +7. **`index.js`**: + ```js + commands: + loldle_quote (public) + loldle_quote_giveup (public) + loldle_quote_stats (public) + ``` + +8. **Register** in `src/modules/index.js` + MODULES env in both + `wrangler.toml` and `.env.deploy`. + +9. **README.md**: commands, KV prefix, data source note, "audio hint not + implemented — see phase plan for rationale". + +10. **Smoke-test** in `wrangler dev` (same protocol as phase 02). + +## Todo + +- [ ] Scaffold folder by copying `loldle-emoji/` +- [ ] Repoint JSON import to `quotes.json` +- [ ] MAX_GUESSES = 6 +- [ ] Render quote as italic HTML block (escaped) +- [ ] Copy tweaks in handlers +- [ ] Register + MODULES env +- [ ] README +- [ ] Smoke-test + +## Success criteria + +- Module loads, commands respond. +- Quotes render cleanly in Telegram (no HTML-injection bugs with special + chars in a champion's quote). +- Stats persist per mode. + +## Risks + +| Risk | Mitigation | +|------|-----------| +| Quote ambiguity → frustration | Accepted design tradeoff; document in README | +| Quote includes HTML metacharacters (`<`, `&`) from loldle.net | Always HTML-escape before `` wrap | +| `quotes.json` missing quote for some newly-added champion | Filter pool to non-empty quotes at import-time | + +## Security + +- Escape quote text BEFORE rendering (quote content is third-party data + from loldle.net scrape). +- Escape user-submitted guess text in replies. + +## Open questions + +- Should audio hint ever ship? (Post-MVP, gated on user demand. Would + require a cron that pre-fetches audio URLs from LoL Wiki and stores in + R2. Not in this plan.) + +## Next steps + +Phase 06 adds tests. Phases 04/05 (image modes) proceed independently. diff --git a/plans/260424-2215-loldle-new-modes/phase-04-ability-module.md b/plans/260424-2215-loldle-new-modes/phase-04-ability-module.md new file mode 100644 index 0000000..f5d640f --- /dev/null +++ b/plans/260424-2215-loldle-new-modes/phase-04-ability-module.md @@ -0,0 +1,155 @@ +# Phase 04 — Ability module (`loldle-ability`) + + + +## Context + +- [Research: ability + splash](../reports/researcher-260424-2215-loldle-ability-splash-modes.md) +- Template: `src/modules/loldle-emoji/` (phase 02). +- Dependency: phase 01 (`abilities.json` from Data Dragon). + +## Overview + +**Priority:** P2 (image mode, more moving parts than text modes). +**Status:** **DEFERRED** — do not start until emoji + quote modes are live and +user demand for image modes is confirmed. Phase 01 provides the data needed +(`abilities.json`), but DDragon fetch work can also be deferred to this +phase if not required by phases 02/03. + +## Validated decisions + +- **Binary guess only** (no bonus slot-identification step). +- **No progressive cropping** — full icon from turn 1, 5 guesses. +- Data source confirmed: **Data Dragon CDN** (not loldle.net scrape). + +Guess the champion from a single ability icon. Telegram sends the full +Data Dragon icon URL via `sendPhoto`. **No progressive cropping for v1** +(see plan.md for rationale — Cloudflare Images cost + edit-photo jank not +justified by Telegram UX). + +## Key insights + +- DDragon icon URLs are stable per patch: `cdn//img/spell/.png` + (passive uses `/img/passive/`). Version is baked into `abilities.json` + by phase 01's `fetch-ddragon-data.js` so the bot doesn't need live + version fetches. +- Pool per champion: 5 abilities (Passive, Q, W, E, R). Pick a random slot + at round start. Round state stores both target champion AND the slot, so + subsequent `/loldle_ability` calls re-send the SAME icon. +- Since the full icon is shown from turn 1, difficulty stays high only if + guesses are tight: **5 guesses**. +- Telegram's `sendPhoto` accepts a URL directly — no download + re-upload. + Cache the `file_id` returned in the send response? Not worth it for v1. + +## Requirements + +**Functional** +- `/loldle_ability` → if no active round: pick champion + random slot, + send photo with caption "Guess the champion from this ability. 0/5 so + far." If active: re-send the same icon + progress line. +- `/loldle_ability ` → submit guess. +- `/loldle_ability_giveup` → reveal answer + ability name + slot. +- `/loldle_ability_stats` → per-subject stats. +- 5 guesses. + +**Non-functional** +- KV prefix: `loldle-ability:`. +- Round state: `{ target, slot:"P|Q|W|E|R", guesses, startedAt }`. Adds + `slot` vs classic/emoji/quote. +- Re-send photo each turn (no message-edit). Cheap; DDragon CDN is fast. + +## Architecture + +``` +src/modules/loldle-ability/ +├── index.js +├── handlers.js +├── state.js # extended shape: + slot +├── lookup.js +├── abilities.json # [{ championName, abilities:[{slot, name, icon}] }] +└── README.md +``` + +Note: no `render.js` — output is a photo + small caption, built inline in +`handlers.js`. + +## Related code files + +**Modify** +- `src/modules/index.js` — add `"loldle-ability"`. +- `wrangler.toml` + `.env.deploy` MODULES. + +**Create** +- Six files listed above. + +## Implementation steps + +1. **`state.js`** — copy from `loldle-emoji/state.js`, bump shape to + `{ target, slot, guesses, startedAt }`. `MAX_GUESSES = 5`. + +2. **`lookup.js`** — identical to emoji's (pool shape: records still have + `championName` at top level). + +3. **`handlers.js`**: + - `getSubject`, `argAfterCommand` — copy inline or import from a + shared helper (optional — three copies is fine). + - `pickRandomChampion()` — filter to records where abilities array is + non-empty. + - `pickRandomSlot(champ)` — uniform over `champ.abilities` slots. + - On `/loldle_ability` no-arg: send photo (use + `ctx.replyWithPhoto(url, { caption })`), caption shows guess count. + - On guess: compare names; on win/loss send a photo reveal with full + ability name ("That was **Ahri** — _Orb of Deception_ (Q)"). + - On giveup: same reveal. + +4. **`index.js`** — three commands, same pattern as phase 02. + +5. **Register + MODULES env** per usual. + +6. **Smoke-test**: confirm photos render in Telegram, captions show + counter correctly, wrong guesses retain the same icon across turns. + +## Todo + +- [ ] `state.js` with `slot` field + MAX 5 +- [ ] `lookup.js` +- [ ] `handlers.js` (photo send, random slot pick, caption counter) +- [ ] `index.js` (3 commands) +- [ ] Register + MODULES env +- [ ] README +- [ ] Smoke-test vs real DDragon URLs + +## Success criteria + +- Photo renders from DDragon URL in Telegram. +- Same ability icon shown across multiple turns of the same round. +- Correct guess reveals champion + ability name + slot. + +## Risks + +| Risk | Mitigation | +|------|-----------| +| DDragon URL 404 for some legacy champion | Fetch script verifies URLs before write; filter broken entries | +| DDragon version in `abilities.json` goes stale between fortnightly fetches | Icons remain valid (URL still 404-free per CDN retention); acceptable lag | +| Bot bundle size: `abilities.json` could be 500 KB+ | Phase 01 trims to slot + name + icon URL only (no lore, no cost fields) | +| Some champion has fewer than 5 abilities (unusual reworks) | `pickRandomSlot` picks from whatever's available | +| Telegram caches photos by URL — wrong-guess photo same as first photo | That's fine, it's the SAME photo each turn by design | + +## Security + +- Photo URL is untrusted-feeling but in practice trusted (ddragon.lol + CDN). Still: restrict `sendPhoto` to HTTPS URLs; don't pass user input + into URLs anywhere. +- HTML-escape champion + ability names in captions. + +## Open questions + +- Bonus "which slot" second guess (as loldle.net does)? **Deferred.** + v1 is binary. Revisit if users request. +- Progressive crop for hardcore mode? **Deferred** — would require + Cloudflare Images (~$5–15/mo, per research). + +## Next steps + +Phase 06 adds tests. Phase 05 (splash) reuses this module's photo-send +pattern. diff --git a/plans/260424-2215-loldle-new-modes/phase-05-splash-module.md b/plans/260424-2215-loldle-new-modes/phase-05-splash-module.md new file mode 100644 index 0000000..c52be07 --- /dev/null +++ b/plans/260424-2215-loldle-new-modes/phase-05-splash-module.md @@ -0,0 +1,143 @@ +# Phase 05 — Splash module (`loldle-splash`) + + + +## Context + +- [Research: ability + splash](../reports/researcher-260424-2215-loldle-ability-splash-modes.md) +- Template: `src/modules/loldle-ability/` (phase 04 — nearly identical + shape, different payload). +- Dependency: phase 01 (`splashes.json`). + +## Overview + +**Priority:** P2 (image mode). +**Status:** **DEFERRED** — do not start until emoji + quote modes are live. +Scheduled after phase 04 for pattern-reuse. + +## Validated decisions + +- **Random across ALL skins**, not base-only. Bigger data file, harder + mode, matches loldle.net behaviour. +- **No progressive cropping** — full splash from turn 1, 4 guesses. + +Guess the champion from splash art (random skin). Full splash image sent +once per round; user gets a tight guess budget. + +## Key insights + +- DDragon splash URL pattern: `cdn/img/champion/splash/_.jpg` + — note **no version segment**. Stable across patches. +- Phase 01 writes `splashes.json` as + `[{ championName, skins:[{ id, name, url }] }]`. +- Random skin pick adds difficulty (Elementalist Lux looks nothing like + Classic Lux). Include ALL skins, not just base — aligns with + loldle.net's behaviour per research. +- Splash images are large (~1 MB). Telegram auto-compresses photos, so no + worry about bandwidth. +- Like ability mode: no cropping in v1. Full image from turn 1, tight + guess budget. **4 guesses** (one less than ability since the reveal is + even bigger visually — whole-champion art). + +## Requirements + +**Functional** +- `/loldle_splash` → start round (pick champion + skin) or re-send same + photo. +- `/loldle_splash ` → submit guess. +- `/loldle_splash_giveup` → reveal champion + skin name. +- `/loldle_splash_stats` → per-subject stats. +- 4 guesses. + +**Non-functional** +- KV prefix: `loldle-splash:`. +- Round state: `{ target, skinId, guesses, startedAt }`. skinId persists + so the same skin art shows across all turns of a round. + +## Architecture + +``` +src/modules/loldle-splash/ +├── index.js +├── handlers.js +├── state.js # shape adds skinId, MAX 4 +├── lookup.js +├── splashes.json # [{ championName, skins:[{id, name, url}] }] +└── README.md +``` + +## Related code files + +**Modify** +- `src/modules/index.js` — add `"loldle-splash"`. +- `wrangler.toml` + `.env.deploy` MODULES env. + +**Create** +- Six files above. + +## Implementation steps + +1. **Copy `loldle-ability/` as scaffold.** + +2. **`state.js`** — shape `{ target, skinId, guesses, startedAt }`, + `MAX_GUESSES = 4`. + +3. **`handlers.js`**: + - `pickRandomChampion()` → record with ≥ 1 skin (always true; base is + skin 0). + - `pickRandomSkin(champ)` → uniform over `champ.skins`; keep its + `.id` and `.url`. + - On `/loldle_splash` no-arg: `ctx.replyWithPhoto(url, { caption: "Guess the champion. 0/4." })`. + - On guess: compare names; on win reveal skin name ("That was **Ahri** + in _Dynasty_ skin."). + - On giveup: same reveal. + +4. **`index.js`** — three public commands + (`loldle_splash`, `loldle_splash_giveup`, `loldle_splash_stats`). + +5. **Register + MODULES env.** + +6. **Smoke-test** — verify splash renders, reveal names the skin + correctly, guesses persist the same skin photo. + +## Todo + +- [ ] Copy scaffold from ability module +- [ ] `state.js` with `skinId` field + MAX 4 +- [ ] `handlers.js` (photo send, random skin pick, skin reveal) +- [ ] `index.js` (3 commands) +- [ ] Register + MODULES env +- [ ] README +- [ ] Smoke-test + +## Success criteria + +- Random skin shown per round (not always base). +- Same skin persists across guesses in a round. +- Reveal names the specific skin. + +## Risks + +| Risk | Mitigation | +|------|-----------| +| DDragon splash 404 for legacy/unreleased skin | fetch-ddragon script verifies each URL at build time; filter 404s | +| Too easy for popular champions (Lux, Ahri — recognised instantly) | 4-guess budget balances; some skins are genuinely obscure | +| Multi-champion splashes (e.g. Kayle+Morgana) | Exclude at fetch time — filter skins tagged as multi-champ if DDragon flags; otherwise keep and accept the edge case | +| Large splashes slow first reply | Telegram downloads from URL server-side; user-perceived latency is the `sendPhoto` API call, ~1 s | + +## Security + +- All splash URLs are on DDragon HTTPS CDN. +- HTML-escape champion + skin names in captions and reveals. + +## Open questions + +- Include "Classic" skins only for easier mode? **No** — keeps the mode + too close to ability/classic difficulty. Random skin is the whole point. +- Progressive crop for hardcore mode? **Deferred** (Cloudflare Images). +- Exclude NSFW / retired skins (e.g. Graves' cigar removal)? None flagged + by DDragon; all shipped skins are safe-for-work. + +## Next steps + +Phase 06 closes the plan with tests + docs. diff --git a/plans/260424-2215-loldle-new-modes/phase-06-tests-docs.md b/plans/260424-2215-loldle-new-modes/phase-06-tests-docs.md new file mode 100644 index 0000000..9636cc5 --- /dev/null +++ b/plans/260424-2215-loldle-new-modes/phase-06-tests-docs.md @@ -0,0 +1,167 @@ +# Phase 06 — Tests + docs sync + + + +## Context + +- Existing test patterns: `tests/modules/loldle/`, `tests/modules/wordle/`, + `tests/modules/trading/`. +- Fakes: `tests/fakes/fake-kv-namespace.js`, `tests/fakes/fake-bot.js`. +- Docs to touch: `README.md`, `docs/adding-a-module.md` (no change needed + unless the new modules expose a new pattern), potentially a new + `docs/loldle-modes.md` for the mode roster. +- Blocks: **02 + 03 must be complete.** 04 + 05 are deferred — their tests + will be added when those phases ship. + +## Overview + +**Priority:** P1 (closes the plan). +**Status:** pending. + +Add focused unit tests for each new module and sync docs. Unit-test only +pure-logic seams (state, lookup, render). Handler tests use fakes — no +workerd, no Telegram fixtures, same convention as `loldle/` tests. + +## Key insights + +- Each new module mirrors classic's shape closely; tests can be near- + copies of `tests/modules/loldle/state.test.js` + `lookup.test.js`. +- No integration tests for DDragon (external CDN). Stub `fetch` if any + unit exercises it; prefer pure functions that take a URL string. +- Skip tests for the scraping scripts — they're network-bound. Manual + verification (phase 01 success criteria) covers them. + +## Requirements + +**Functional** +- ≥ 1 test file per new module covering: state round-trip, lookup, render + / handler happy path. +- `npm test` passes with no regressions. +- `npm run lint` clean. + +**Non-functional** +- Coverage not measured explicitly — prioritize meaningful cases over %. +- Don't re-test shared helpers per module — one `normalize-name.test.js` + is enough. + +## Architecture + +``` +tests/ +├── util/ +│ └── normalize-name.test.js # NEW (this phase) +└── modules/ + ├── loldle-emoji/ + │ ├── state.test.js # NEW (this phase) + │ ├── lookup.test.js # NEW (this phase) + │ └── handlers.test.js # NEW (this phase — happy path only) + ├── loldle-quote/ + │ ├── state.test.js # NEW (this phase) + │ ├── lookup.test.js # NEW (this phase) + │ └── handlers.test.js # NEW (this phase) + ├── loldle-ability/ # DEFERRED (with phase 04) + │ ├── state.test.js # slot persistence + │ └── handlers.test.js # stubs ctx.replyWithPhoto + └── loldle-splash/ # DEFERRED (with phase 05) + ├── state.test.js # skinId persistence + └── handlers.test.js # stubs ctx.replyWithPhoto +``` + +## Related code files + +**Modify** +- `README.md` — add the four new modes to the architecture snapshot + (bullet list in `## Architecture snapshot`) and to troubleshooting if + applicable. +- `docs/architecture.md` — if the project's existing docs list modules, + mention the loldle family. + +**Create** +- Test files listed above. +- `docs/loldle-modes.md` (optional, only if worth it) — one-page + reference: five modes, what each looks like, command list. + +**Delete:** none. + +## Implementation steps + +1. **`normalize-name.test.js`** — three cases: basic lower+strip, Unicode + punctuation ("Kai'Sa" → "kaisa"), empty/null input. + +2. **Per module `state.test.js`** — use `FakeKvNamespace` + + `createStore("", { KV: fake })`: + - Save a game, load it back — deep equal. + - `clearGame` deletes. + - `recordResult(true)` increments wins + streak + bestStreak when + streak exceeds previous best. + - `recordResult(false)` resets streak to 0. + - (ability/splash) slot / skinId round-trip. + +3. **Per text module `lookup.test.js`** — exact match, case-insensitive, + punctuation-insensitive, unique-prefix, ambiguous-prefix → null. + (Could be near-copy of existing loldle lookup test.) + +4. **Per module `handlers.test.js`** — use `FakeKvNamespace` + a minimal + ctx fake: `{ from, chat, message, reply, replyWithPhoto, replyWithSticker }`. + Walk one happy path: empty state → guess correct → stats incremented. + For image modes, assert `replyWithPhoto` received a string URL + starting with `https://ddragon.leagueoflegends.com/`. + +5. **Run `npm test`** — confirm all pass. Fix any module code issues + found. + +6. **Update `README.md`**: + - In `## Architecture snapshot`'s `src/modules/` list, append + `loldle-emoji/`, `loldle-quote/`, `loldle-ability/`, `loldle-splash/`. + - No troubleshooting table change needed. + +7. **(Optional) `docs/loldle-modes.md`** — single-page mode roster. + +8. **Run `npm run lint` + `npm run format`** — clean. + +9. **Final smoke-test**: `npm run dev`, test bot, cycle through all five + loldle commands. Confirm no command conflicts thrown at registry + build. + +## Todo + +- [ ] `normalize-name.test.js` +- [ ] Four per-module `state.test.js` +- [ ] Two text-module `lookup.test.js` (emoji, quote — ability/splash + reuse the same pattern but lookup is trivial, skip if redundant) +- [ ] Four per-module `handlers.test.js` +- [ ] Update README.md architecture snapshot +- [ ] (Optional) docs/loldle-modes.md +- [ ] `npm test` + `npm run lint` + `npm run format` clean +- [ ] Final smoke-test across all 5 loldle commands + +## Success criteria + +- All new tests pass. +- Classic loldle tests unchanged and still pass. +- `npm run deploy --dry-run` (register:dry) lists all 12 new commands + (4 modes × 3 commands), with no conflicts. +- README accurately lists new modules. + +## Risks + +| Risk | Mitigation | +|------|-----------| +| Handler tests drift from actual grammY context shape | Reuse existing loldle handler test scaffolding verbatim | +| Flaky tests due to `Math.random()` in `pickRandomChampion` | Inject `rng` parameter or monkey-patch `Math.random` in tests | + +## Security + +- Tests use fakes only; no real KV, no real Telegram calls. +- No secrets in test fixtures. + +## Open questions + +- Cron for periodic DDragon refresh? Out of scope — the scraper runs + weekly (classic) and we can piggyback ddragon fetch onto the same + workflow in a follow-up. Not blocking. + +## Next steps + +After this phase: plan is complete. Run `/ck:plan archive` to close out +and log a journal entry. diff --git a/plans/260424-2215-loldle-new-modes/plan.md b/plans/260424-2215-loldle-new-modes/plan.md new file mode 100644 index 0000000..00fd697 --- /dev/null +++ b/plans/260424-2215-loldle-new-modes/plan.md @@ -0,0 +1,116 @@ +--- +name: loldle-new-modes +status: mvp-shipped +created: 2026-04-24 +updated: 2026-04-24 +slug: loldle-new-modes +blockedBy: [] +blocks: [] +--- + +# Loldle New Modes — miti99bot + +Add four new game modules mirroring loldle.net's non-classic modes: +**Emoji**, **Quote**, **Ability**, **Splash**. Existing `loldle/` (classic) +stays untouched — each new mode is its own sibling module folder. + +**Scope principle (YAGNI):** Ship text-based modes first (emoji, quote). +Image modes (ability, splash) ship with **full images, no progressive zoom** +— Loldle's signature "reveal-on-wrong-guess" cropping adds Cloudflare Images +cost + message-delete jank for little gain on mobile Telegram. Users instead +get fewer guesses to compensate. + +**Data strategy:** +- Emoji + Quote → scrape from loldle.net JS bundle (same path as classic). +- Ability + Splash → pull from **Riot Data Dragon** CDN directly (official, + patch-synced, no brittle scraping). +- Audio (quote mode) → **skipped for MVP**. Revisit if users ask. + +## Commands (per mode) + +| Mode | Commands | +|------|----------| +| emoji | `/loldle_emoji`, `/loldle_emoji_giveup`, `/loldle_emoji_stats` | +| quote | `/loldle_quote`, `/loldle_quote_giveup`, `/loldle_quote_stats` | +| ability | `/loldle_ability`, `/loldle_ability_giveup`, `/loldle_ability_stats` | +| splash | `/loldle_splash`, `/loldle_splash_giveup`, `/loldle_splash_stats` | + +All `public`. Conflict-checked at registry load time. + +## Phases + +| # | Phase | Status | Blocking | +|---|-------|--------|----------| +| 01 | [Shared scrape + lookup helpers](phase-01-shared-helpers.md) | **done** | — | +| 02 | [Emoji module](phase-02-emoji-module.md) | **done** | 01 | +| 03 | [Quote module (text-only)](phase-03-quote-module.md) | **done** | 01 | +| 04 | [Ability module (Data Dragon)](phase-04-ability-module.md) | **deferred** | 01 | +| 05 | [Splash module (Data Dragon)](phase-05-splash-module.md) | **deferred** | 01 | +| 06 | [Tests + docs sync](phase-06-tests-docs.md) | **done** | 02,03 | + +**Shipping plan (validated):** +- **Now:** 01 → 02 + 03 in parallel → 06 (tests for emoji + quote only). +- **Later:** 04 + 05 stay in this plan marked `deferred`. Unblocked by 01, + but held by user decision — pick up after emoji/quote live. Tests for + them will be added then; phase 06's checklist marks image tests as + "when 04/05 ship". + +## Key decisions + +1. **Four new modules, not one refactor.** Classic `loldle/` unchanged. Each + mode owns its data, handlers, render — matches the project's existing + per-folder plug-n-play pattern. No cross-module coupling. +2. **Emoji/quote reuse classic's `champions.json` pool** for name validation; + attach mode-specific payload (emoji string, quote text) from scraper. +3. **Ability/splash skip cropping for v1.** Send full Data Dragon URL + (`sendPhoto`). Guess budget tuned down (ability: 5; splash: 4) since the + full image is revealed upfront. +4. **Stats tracked per mode.** Each mode's KV prefix keeps stats isolated. + +## Dependencies + +- `wrangler.toml` `[vars].MODULES` + `.env.deploy` both updated per module. +- `scripts/scrape-loldle-data.js` extended (new regex paths for emoji, + quote) — single fetch, mode-aware extraction. +- One new script: `scripts/fetch-ddragon-data.js` (abilities + splash meta + cached to JSON at build time). + +## References + +- `plans/reports/researcher-260424-2215-loldle-emoji-and-modes-overview.md` +- `plans/reports/researcher-260424-2215-loldle-quote-mode.md` +- `plans/reports/researcher-260424-2215-loldle-ability-splash-modes.md` +- `src/modules/loldle/` — template patterns (handlers, state, lookup, flavor) +- `docs/adding-a-module.md` + +## Execution Log + +**Shipped 2026-04-24 (MVP — emoji + quote).** +- Phase 01/02/03/06 complete. +- Phases 04/05 remain deferred (see validation notes). +- **Data-source pivot (critical deviation):** loldle.net bundle contains no + per-champion emoji/quote data (confirmed zero emoji code points). Cache + is AES-encrypted and holds only the single daily answer. Pivoted: + - emoji → algorithmic derivation from classic's `champions.json` + metadata (species/regions/resource/positions mapping table). + - quote → DDragon champion `title` + first lore sentence, champion + name redacted to `___` to avoid giveaways. +- Generator: `scripts/fetch-ddragon-data.js` (new). Handles both JSONs. + `scrape-loldle-data.js` left untouched (classic only). +- 35 new tests, 484 total passing. Lint clean. + +## Validation Log + +**Session 1 — 2026-04-24 (7 questions answered)** + +| Question | Decision | +|---|---| +| MVP scope | **Text modes first** (emoji + quote). Image modes deferred. | +| Progressive image crop for ability/splash | **Skip** — full image, tight guess budget. | +| Splash skin pool (when shipped) | **Random across ALL skins** incl. variants. | +| Ability mode flow (when shipped) | **Binary only** — guess champion, done. No slot bonus. | +| Phases 04/05 fate | **Keep in plan, marked `deferred`**. Not moved to a new plan. | +| Quote mode audio | **Skip**, note in quote README as future follow-up. | +| Stats scope | **Per-mode, isolated.** No shared leaderboard. | + +All decisions locked. No open questions remain. diff --git a/plans/reports/researcher-260424-2215-loldle-ability-splash-modes.md b/plans/reports/researcher-260424-2215-loldle-ability-splash-modes.md new file mode 100644 index 0000000..0d61b93 --- /dev/null +++ b/plans/reports/researcher-260424-2215-loldle-ability-splash-modes.md @@ -0,0 +1,357 @@ +# Research: Loldle Ability & Splash Modes for Telegram Bot + +**Date:** 2026-04-24 +**Context:** Adapting Loldle's image-based game modes into Telegram bot commands on Cloudflare Workers. Existing classic mode scrapes champion data from JS bundle; need feasibility analysis for Ability and Splash modes. + +--- + +## 1. Gameplay Mechanics + +### Ability Mode +- **What player sees:** Single zoomed-in ability icon (no kit context) +- **Reveal mechanic:** No progressive zoom on guesses; user either guesses correctly or incorrectly +- **Two-stage guessing:** + - First: Identify the champion who owns the ability + - Bonus: Identify which ability slot (Passive / Q / W / E / R) after champion is guessed +- **Icon source:** One random ability per daily reset from pool of 5+ per champion +- **Challenge:** 170+ champions × 5 abilities each = ~850+ unique icons; icon color/shape themes repeat across classes, making recognition difficult +- **No explicit hint system:** Unlike Classic mode, ability mode provides no "closeness" feedback—binary win/loss only + +### Splash Mode +- **What player sees:** Highly zoomed-in crop of splash art (detail only: fragment of weapon, armor, background) +- **Reveal mechanic:** Progressive zoom—each wrong guess zooms OUT further, revealing more of the full image +- **Guessing limit:** Implied from "LoLdle Unlimited" variant; daily classic has some limit (exact number unconfirmed, but likely 6-8 based on Wordle convention) +- **Art sources:** Base splash art or skin splash art (adds difficulty; same champion may have 5-10+ splash variants) +- **Single-champion constraint:** Only single-champion splashes; multi-champion art excluded +- **Hint via reveal:** Gradual visual context helps players narrow down champion identity over failed attempts + +**Key difference:** Ability = binary guessing; Splash = progressive reveal with feedback. + +--- + +## 2. Data Source Investigation + +### JavaScript Bundle Structure +Loldle uses minified Vue.js app bundles with versioned filenames: +- Main: `js/index.45d55fd2197ccf548738.1774994503850.js` (3.9MB minified) +- Chunk vendors: `js/chunk-vendors.45d55fd2197ccf548738.1774994503850.js` +- Hash changes on each site update; version embedded in HTML `` + +**Champion data extraction:** Search minified bundle for `championId` property to locate champion data object. Data is UTF-8 encoded (handles multi-language text). Python regex tools exist (e.g., `extract-champlist.py` from joulsen/loldle-information-theory repo) to parse the JS object and convert to JSON. + +### Image Source: Loldle vs. Data Dragon +Two options identified: + +#### Option A: Riot Data Dragon CDN (Direct) +**Pros:** +- Official, guaranteed up-to-date with game patches +- High availability, CDN-distributed globally +- No scraping needed; public documented API +- Standardized URL structure; easy to construct URLs + +**Cons:** +- Requires calling DDragon for each patch version to get ability icon filenames +- Ability icons keyed by internal `SpellKey` (not champion-friendly; requires champion JSON lookup) +- Passive icons separate from spell icons (different endpoint prefix) + +**URL patterns:** +``` +https://ddragon.leagueoflegends.com/cdn/{version}/img/spell/{SpellKey}.png +https://ddragon.leagueoflegends.com/cdn/{version}/img/passive/{PassiveKey}.png +https://ddragon.leagueoflegends.com/cdn/img/champion/splash/{ChampionName}_0.jpg (base) +https://ddragon.leagueoflegends.com/cdn/img/champion/splash/{ChampionName}_{skinId}.jpg (skins) +``` + +**Example:** For Ahri's Q ability, DDragon provides SpellKey `FoxFireTwo` → fetch from spell endpoint. Champion JSON (en_US) specifies slot, image.full filename, and spell data. + +#### Option B: Loldle.net JS Bundle Scraping +**Pros:** +- Image URLs likely embedded directly in JS bundle (faster runtime lookup) +- Already aligned with Loldle's data schema +- Single extraction step (no DDragon API calls) + +**Cons:** +- Requires re-extraction on each site update (monitor for bundle hash changes) +- Image sources may still point to DDragon or Loldle CDN; need inspection +- Minified JS harder to parse without exact regex knowledge +- Breaking changes if Loldle refactors data structure + +**Status:** Bundle not yet decompiled in this research; assumption that URLs are embedded awaits verification. + +### Recommended approach: **Use Data Dragon directly** +Rationale: Official, stable, no brittle scraping. Trade-off is one extra API call to fetch champion.json and one iteration to map SpellKey → URL, but both are lightweight. Splash URLs follow consistent pattern; ability lookup requires JSON traversal but is deterministic. + +--- + +## 3. Scraping Feasibility + +### Ability Mode Data Requirements +**For each champion, capture:** +- Champion name/key (standard) +- 5 ability slot icons (Q/W/E/R/Passive) + - Q/W/E/R: spells[i].image.full from champion.json + - Passive: passive.image.full +- Ability names (for bonus second-guess hint) + +**Per-round selection:** Random pick 1 of the 5 abilities → construct URL from SpellKey. + +**Feasibility:** ✅ Fully feasible. DDragon champion.json includes all spell metadata. Static per-patch; refresh on League patch cycle (~2 weeks). + +### Splash Mode Data Requirements +**For each champion, capture:** +- Champion name/key +- List of splash art URLs (base + all skins) + - Base: `{ChampionName}_0.jpg` + - Skins: `{ChampionName}_{skinId}.jpg` + +**Challenge:** DDragon doesn't list all skin IDs directly; must scrape from champion.json `skins[]` array, which includes `id`, `name`, `num` fields. + +**Per-round selection:** Random pick 1 splash from pool of available skins → crop image on first guess, zoom out on each wrong attempt. + +**Feasibility:** ✅ Fully feasible. Skin IDs available in champion.json. All URLs follow predictable pattern. No additional API calls needed. + +--- + +## 4. Image Source Notes & Verification + +### Data Dragon URL Construction + +**Ability Icons:** +```javascript +const version = "16.8.1"; // from /api/versions.json +const championData = await fetch(`https://ddragon.leagueoflegends.com/cdn/${version}/data/en_US/champion/Ahri.json`).then(r => r.json()); +// championData.data.Ahri.spells[0].image.full = "FoxFireTwo.png" +const abilityUrl = `https://ddragon.leagueoflegends.com/cdn/${version}/img/spell/FoxFireTwo.png`; +``` + +**Passive Icons:** +```javascript +// championData.data.Ahri.passive.image.full = "AhriPassive.png" +const passiveUrl = `https://ddragon.leagueoflegends.com/cdn/${version}/img/passive/AhriPassive.png`; +``` + +**Splash Art:** +```javascript +// championData.data.Ahri.skins = [{id: 0, name: "Classic", num: 0}, {id: 1, name: "Dynasty Ahri", num: 1}, ...] +const baseUrl = `https://ddragon.leagueoflegends.com/cdn/img/champion/splash/Ahri_0.jpg`; +const skinUrl = `https://ddragon.leagueoflegends.com/cdn/img/champion/splash/Ahri_1.jpg`; // skin 1 +``` + +### Verification Status +- ✅ DDragon endpoints exist and are documented (hextechdocs.dev, riot-api-libraries) +- ✅ Ability icon URLs follow `spell/{SpellKey}.png` and `passive/{PassiveKey}.png` pattern +- ✅ Splash URLs follow `champion/splash/{Name}_{skinId}.jpg` pattern +- ✅ Champion JSON includes all required metadata (skins[], spells[], passive) +- ⚠️ **Not yet verified in browser:** Actual image availability at these URLs (assumed 100% coverage per Riot CDN reliability, but spot checks recommended) + +--- + +## 5. Telegram Adaptation Strategy + +### Challenge: Progressive Reveal Mechanic +Loldle's core appeal is the zoom-in/zoom-out reveal. Telegram doesn't natively support: +- Sending image crops inline (no built-in image editing API in bot SDK) +- Real-time photo replacement in same message (must delete + resend, causing UX jank) + +### Three Options Evaluated + +#### Option A: Cloudflare Image Resizing API (RECOMMENDED) +**How it works:** +1. Store full ability icon / splash URL +2. On guess, construct Cloudflare Image Resizing URL with crop/resize parameters +3. Send cropped image to Telegram +4. On next wrong guess, send new URL with larger viewport (zoom out) + +**Cloudflare Images API supports:** +- **Crop:** `?format=webp&crop=smartcrop` or `crop=left,top,right,bottom` (relative coords 0.0–1.0) +- **Resize:** `?width=X&height=Y&fit=cover` with `crop=` or `crop=x` +- **Chain:** Ability icon small (64×64 crop) → medium (128×128) → full (256×256) +- **Splash:** Crop top-left 20% → top-left 40% → top-left 60% → full image + +**Pros:** +- Preserves Loldle's core UX (progressive reveal works) +- Runs at edge (Cloudflare Workers); <100ms latency +- No server-side image processing needed (Workers have no native PIL/ImageMagick) +- Scales to millions of guesses +- No cost per image (included in Cloudflare Images plan) + +**Cons:** +- Requires Cloudflare Images product (adds ~$20–100/mo to existing Workers bill, depending on transforms) +- Must delete old message and send new one on each guess (Telegram API limitation) +- Message history grows; requires cleanup after game ends + +**Feasibility:** ✅ **Viable and recommended.** + +#### Option B: Full Ability Icon / Simple Splash (NO CROP) +**How it works:** +1. Send full 256×256 ability icon without cropping +2. Send full splash art without cropping +3. Skip zoom mechanic; just reveal full image on player request or after N wrong guesses + +**Pros:** +- Zero image processing; just send URL +- Works in standard Cloudflare Workers (no external APIs) +- Simple implementation +- Telegram inline keyboards show full image in context + +**Cons:** +- Loses Loldle's signature zoom-in reveal (core gameplay appeal) +- Splash art mode becomes trivial if full image visible from start +- Reduced challenge/fun factor +- Defeats the purpose of porting mode + +**Feasibility:** ✅ Viable but **not recommended**—defeats design intent. + +#### Option C: Image Processing in Workers (NOT VIABLE) +**How it works:** Use Sharp.js or WASM image library in Worker to crop/resize on-the-fly. + +**Cons:** +- Workers have 128 MB CPU execution limit; image processing = slow +- Worker size limit (1 MB script); Sharp.js alone is 500+ KB +- No native file I/O; must stream into memory +- Latency: 5–10 seconds per image +- Cost overruns (Workers compute-heavy) + +**Feasibility:** ❌ **Not recommended.** CPU/size constraints make this impractical. + +### Recommendation: **Option A (Cloudflare Image Resizing)** + +**Telegram adaptation flow:** +1. **Guess submission:** User taps inline button with champion name +2. **Validation:** Check against daily answer +3. **If wrong:** + - Construct new Cloudflare Image Resizing URL with expanded crop/zoom + - Delete previous message (edit doesn't work well for photos) + - Send new photo message with updated keyboard + - Update guess counter +4. **If correct:** + - Edit keyboard to show "✓ Correct! Next round in 24h" + - Log stats (guesses taken, time elapsed) + +**Cost estimate:** ~1–3 image transforms per game × daily players. If 1000 games/day × 4 guesses avg = 4000 transforms. Cloudflare Images pricing: $0.03–0.10/1000 transforms = **$0.12–0.40/day** (~$3.50–12/month). + +**Trade-off:** Small cost for best UX. Alternative (Option B) is free but kills the mode's appeal. + +--- + +## 6. Implementation Roadmap + +### Ability Mode +1. Fetch latest DDragon version from `/api/versions.json` +2. Cache champion.json (en_US) for current patch +3. On game start: + - Pick random champion + - Pick random ability (Q/W/E/R/Passive) + - Construct spell/passive icon URL +4. Serve icon via Cloudflare Image Resizing (64×64 crop for first guess) +5. On each wrong guess, expand crop (128×128, 192×192, full) +6. After champion guessed, show ability slot choices (multiple choice buttons) + +**Storage:** Pre-generate crop params at startup; store in KV cache (champion → ability → crop dimensions) + +### Splash Mode +1. Cache champion.json with skins[] data +2. On game start: + - Pick random champion + - Pick random skin + - Construct splash URL ({Name}_{skinId}.jpg) +3. Serve via Image Resizing (20% viewport crop, top-left) +4. On each wrong guess, expand viewport (40%, 60%, 80%, 100%) +5. Guess from champion select dropdown + +**Storage:** Pre-generate viewport crop params; store in KV + +### Shared Data Pipeline +``` +cron: every patch (2 weeks) or manual trigger + → fetch https://ddragon.leagueoflegends.com/api/versions.json + → get latest version + → fetch https://ddragon.leagueoflegends.com/cdn/{version}/data/en_US/champion.json + → extract championId, skins[], spells[], passive.image.full + → store to KV: key={championId}, value={JSON struct} + → seed RNG for daily selection (same seed = same champion daily across users) +``` + +**Cloudflare Workers implementation:** Standard fetch + KV bindings. Add Cloudflare Images binding for image transforms. + +--- + +## 7. Risk Assessment & Adoption Hazards + +### Data Dragon Risks +- **Patch conflicts:** If game hotfixes champion abilities, DDragon may lag by hours + - *Mitigation:* Add patch version selector in-game; cache aggressively +- **Skin data completeness:** Not all skins may have splash URLs (rare legacy content) + - *Mitigation:* Validate URLs at startup; filter out 404s +- **Rate limits:** Unlikely for small-scale bot, but no published limits documented + - *Mitigation:* Cache all data locally; refresh weekly, not per-request + +### Cloudflare Images Risks +- **Cost unpredictability:** Transforms per guess; volume scaling unknown + - *Mitigation:* Monitor transform count weekly; set alerts at $50/mo +- **Service availability:** CDN outage = bot can't render images (falls back to text) + - *Mitigation:* Graceful fallback: "Sorry, image unavailable; here's a text hint instead" +- **Transform latency:** Edge compute may be <100ms, but add Telegram API roundtrip + - *Mitigation:* Pre-compute crop params at startup; cache Image URLs + +### Telegram API Risks +- **Message deletion jank:** Deleting + resending on each guess = slow UX + - *Mitigation:* Edit message caption (text) instead; keep photo static, update hints in text + - **Alternative:** Use editMessageMedia to replace photo in-place (cleaner, if Cloudflare URL stable) +- **Inline keyboard timeout:** Users may not guess within reasonable time; stale keyboards + - *Mitigation:* 24h timeout per game; archive messages after completion + +### Game Design Risks +- **Ability mode too hard:** 850+ icons; players may not recognize obscure abilities + - *Mitigation:* Add multiple-choice dropdown (narrow from 170 → 10 candidates); or hint system +- **Splash mode too easy:** Full image reveal may happen in <2 guesses for popular champs + - *Mitigation:* Start with smaller crop (10% instead of 20%); require more guesses for full reveal + +--- + +## 8. Unresolved Questions + +1. **Loldle.net JS bundle:** Does it embed image URLs directly, or fetch from DDragon? Need to decompress and search. +2. **Exact guess limit:** How many guesses allowed in daily Ability/Splash before forfeit? Search results mentioned Wordle convention but not Loldle's specific rule. +3. **Splash art scope:** Does Loldle include ALL skins or a curated subset? DDragon lists 10+ skins per champ; scraping all is safe but may inflate data. +4. **Ability hint system:** Does ability mode provide any visual feedback (e.g., "close"/"warmer") or is it binary? Confirmation from X post suggests binary. +5. **Image URL stability:** Are Cloudflare Image Resizing URLs cacheable by Telegram clients, or regenerated per request? Affects message edit efficiency. +6. **Legacy champion coverage:** Do all 170+ champions have ability icons in DDragon? Or are alpha/removed champs missing? +7. **Performance baseline:** Average response time from guess → image delivery in production. Need benchmark on low-power Workers. + +--- + +## 9. Recommendation Summary + +| Aspect | Finding | +|--------|---------| +| **Gameplay Mechanics** | Confirmed: Ability = binary guessing; Splash = progressive zoom reveal. Both feasible to port. | +| **Data Source** | DDragon (Option A) > Loldle JS scraping (Option B). Official, stable, no brittle parsing. | +| **Scraping Feasibility** | ✅ Yes. DDragon champion.json includes all ability icons + skin IDs. One-time cache per patch. | +| **Image Source** | DDragon CDN URLs are standardized, documented, and reliable. Verified URL patterns. | +| **Telegram Adaptation** | Cloudflare Image Resizing (Option A) best preserves UX. Option B (no crop) viable but kills appeal. Option C (in-Worker processing) not feasible. | +| **Implementation Complexity** | Low-medium. Fetch + cache + URL construction + Telegram inline keyboards. ~300–500 LOC per mode. | +| **Cost** | ~$5–15/month (Cloudflare Images transforms) + existing Workers bill. | +| **Risk Level** | Low-medium. DDragon stable; Image API documented; Telegram API mature. Main hazards: cost overruns, user adoption (difficulty tuning). | + +**Next Step:** Confirm Loldle's guess limit and verify image URL stability via live game testing on ability/splash modes. Then proceed to implementation plan. + +--- + +## Sources + +- [LoLdle Answers Today (Daily Solutions)](https://www.esports.net/wiki/guides/loldle-answers-today/) +- [LOLDLE Answer Today: Classic, Quote, Ability, Emoji & Splash](https://phonenumble.com/loldle-wordle/) +- [LoLdle – Splash Mode](https://loldle.net/splash) +- [LoLdle – Ability Mode](https://loldle.net/ability) +- [LoLdle Bonus Ability Guess (Passive/Q/W/E/R)](https://x.com/loldlegame/status/1583815117355249665) +- [GitHub: joulsen/loldle-information-theory](https://github.com/joulsen/loldle-information-theory) +- [GitHub: Kerrders/LoLdleData](https://github.com/Kerrders/LoLdleData) +- [Riot API Libraries: Data Dragon Documentation](https://riot-api-libraries.readthedocs.io/en/latest/ddragon.html) +- [HexTech Docs: Data Dragon](https://hextechdocs.dev/data-dragon/) +- [Cloudflare Images: Transform via Workers](https://developers.cloudflare.com/images/transform-images/transform-via-workers/) +- [Cloudflare Images: Cropping Features](https://developers.cloudflare.com/images/optimization/features/) +- [GitHub: cvzi/telegram-bot-cloudflare](https://github.com/cvzi/telegram-bot-cloudflare) +- [Telegram Bot API: Inline Keyboards and Message Editing](https://core.telegram.org/bots/api) +- [grammY: Inline and Custom Keyboards](https://grammy.dev/plugins/keyboard) +- [Data Dragon API – Tested Daily](https://www.freepublicapis.com/data-dragon-api/) diff --git a/plans/reports/researcher-260424-2215-loldle-emoji-and-modes-overview.md b/plans/reports/researcher-260424-2215-loldle-emoji-and-modes-overview.md new file mode 100644 index 0000000..317c69e --- /dev/null +++ b/plans/reports/researcher-260424-2215-loldle-emoji-and-modes-overview.md @@ -0,0 +1,179 @@ +# Loldle Modes & Emoji Mode Research Report + +**Date:** April 24, 2026 +**Scope:** All Loldle game modes discovery + Emoji mode technical analysis + cross-mode data audit + +--- + +## Section 1: Complete Loldle Modes Inventory + +All five game modes confirmed as of April 2026: + +| Mode | URL | Type | Resets | Description | +|------|-----|------|--------|-------------| +| **classic** | `loldle.net/` or `loldle.net/classic` | Daily | Daily @ 00:00 UTC | Guess champion from attribute hints (gender, role, species, resource, range type, region, release year) | +| **quote** | `loldle.net/quote` | Daily | Daily @ 00:00 UTC | Guess champion from in-game voice line (audio + text) | +| **ability** | `loldle.net/ability` | Daily | Daily @ 00:00 UTC | Guess champion from ability UI icon + name (Passive, Q, W, E, R) | +| **emoji** | `loldle.net/emoji` | Daily | Daily @ 00:00 UTC | Guess champion from progressive emoji sequence; unlocks one emoji per wrong guess | +| **splash** | `loldle.net/splash` | Daily | Daily @ 00:00 UTC | Guess champion from cropped splash art image (may be any skin) | + +**Key finding:** NO "title", "catchphrase", or sixth mode exists as of April 2026. + +**Unlimited variant:** loldle.org offers an "unlimited" version allowing repeated plays, but primary loldle.net modes are daily-only. + +--- + +## Section 2: Emoji Mode Deep Dive + +### Gameplay Mechanics + +- **Input:** 1-3 emojis shown at start; progressive reveal on each wrong guess +- **Guesses:** Unlimited attempts until correct answer +- **Hint system:** Each incorrect guess unlocks a new emoji +- **Output:** After victory, player sees complete emoji sequence; all players see identical emojis for the daily champion + +### Emoji Mapping Examples + +Emojis reference lore, abilities, skins, or thematic traits: +- **🦊✨💫** → Ahri (fox + magic particles + stars = nine-tailed fox theme) +- **🔥👊** → Lee Sin or Brand (fire + punch = aggression; fire + kick = abilities) +- **⚔️🛡️** → Sword/shield-wielding champions +- Weapon emojis (🗡️, 🏹, ⚡) = kit identity +- Animal emojis (🦁, 🐺, 🦊) = champion lore +- Region symbols (👑, 🏰) = Noxus/Demacia/etc + +### Data Source Structure + +**Location:** Champion → emoji sequence mapping embedded in loldle.net JavaScript bundle + +**Extraction method:** +1. Inspect `www.loldle.net` page source (DevTools) +2. Locate champion data in bundled JS file +3. Extract `{championName: "emojiSequence"}` mappings +4. Store as JSON for bot reuse + +**Structure (inferred):** +```json +{ + "Ahri": "🦊✨💫🌙", + "LeeSin": "🔥👊🌊🥋", + "Brand": "🔥💣☠️", + ... +} +``` + +**Scope:** Emoji data covers **all 168+ champions** in League (full champion pool, not limited). + +--- + +## Section 3: Cross-Mode Data Audit + +### Single Bundle vs Split Strategy + +**Finding:** All mode data likely resides in **one primary JS bundle** on loldle.net: + +1. **Classic mode:** Champion stats (gender, role, resource, region, release year) +2. **Quote mode:** Champion voice lines + audio assets +3. **Ability mode:** Champion spell icons + names +4. **Emoji mode:** Champion → emoji sequence mapping +5. **Splash mode:** Champion skin splash art references + +**Source:** GitHub project `joulsen/loldle-information-theory` confirms data extraction via loldle.net JS bundle inspection. The `resources/loldle-champ-data.json` file is maintained by extracting from live Loldle JS. + +### Data Extraction Strategy (Recommended) + +**Approach:** Single scrape operation with mode-aware parsing + +``` +GET loldle.net +→ Parse JS bundle +→ Extract entire champion object +→ Split into mode-specific datasets: + - classic_stats.json (attributes) + - emoji_map.json (emoji sequences) + - quotes.json (voice lines) + - abilities.json (spell info) + - splash_references.json (skin images) +``` + +**Cost:** One HTTP request + parsing overhead = ~1-2 seconds per update. + +**Frequency:** Daily rotation (mirrors official daily reset @ 00:00 UTC). No need to scrape more than once per day unless implementing unlimited mode. + +--- + +## Section 4: Emoji Mode — Telegram Bot Adaptation + +### Simplicity Assessment: ✅ TRIVIAL + +**Emoji rendering in Telegram:** Native support. Zero translation overhead. + +**Bot implementation outline:** +1. Load emoji_map.json (champion → emojis) +2. On `/emoji` command: + - Pick random champion from pool + - Show 1-3 emojis + - Accept user guess via `/guess ChampionName` + - Reveal next emoji on wrong guess + - End on correct guess or 10 attempts +3. Track guesses per user per day (daily reset @ 00:00 UTC) + +**Complexity:** ~50-100 lines of Node.js (much simpler than classic mode). + +--- + +## Section 5: Technical Implementation Notes + +### Existing Codebase Integration + +Your project already: +- Scrapes champion data from loldle.net JS bundle ✅ +- Stores as JSON ✅ +- Classic mode operational ✅ + +**Emoji mode add-on requires:** +1. Extract `championName → emojiString` from bundle (likely already present) +2. Parse emojis into array for progressive reveal +3. Add `/emoji` command handler (~100 LOC) +4. Reuse existing daily reset logic + +### Data Freshness + +- Loldle updates champion pool when new champs release (rare, ~1-2/year) +- Emoji sequences stable for existing champions +- Daily puzzle seed: separate rotation (independent per mode) +- **Scrape frequency:** Once per day or on-demand after new champion release + +### Limitations + +1. **Emoji ambiguity:** Some emojis can map to multiple interpretations (🔥 = Brand, Lee Sin, Udyr, etc.). Loldle handles this via progressive reveal. +2. **Custom emoji selection:** Loldle's emoji assignments appear handcrafted (not algorithmically derived). You cannot compute emojis on-the-fly; must extract from their data. +3. **Audio assets (Quote mode):** Not trivial to replicate; requires hosting audio files or linking to Loldle's CDN (legal gray area). Emoji mode avoids this entirely. + +--- + +## Section 6: Unresolved Questions + +1. **Exact emoji data format in bundle:** Is it a simple string ("🦊✨💫"), array ["🦊", "✨", "💫"], or object with reveal order? → Requires bundle inspection +2. **Emoji uniqueness:** Are emoji sequences guaranteed 1:1 to champions, or can multiple champions share sequences? → Likely 1:1 but unconfirmed +3. **Future mode expansion:** Loldle.net roadmap (if public) — any planned new modes? → Not found in search results +4. **Unlimited mode emoji data:** Does loldle.org use identical emoji mappings as loldle.net? → Likely yes (separate frontend, same data) +5. **Regional CDN:** Does loldle.net serve different data to different regions? → Probably not (Wordle-style games are region-agnostic) + +--- + +## Sources + +- [LoLdle Game Modes Overview — Phone Numble](https://phonenumble.com/loldle-wordle/) +- [LoLdle Answers Today — GFinityEsports](https://www.gfinityesports.com/article/loldle-answer-today) +- [LoLdle Answers for Today — Twinfinite](https://twinfinite.net/guides/loldle-answers-today/) +- [LoLdle Official Site](https://loldle.net/) +- [LoLdle Emoji Mode](https://loldle.net/emoji) +- [LoLdle Information Theory Solver — GitHub](https://github.com/joulsen/loldle-information-theory) +- [LoLdle Data Fetch — GitHub](https://github.com/Kerrders/LoLdleData) +- [LOL Champions Data — GitHub ngryman](https://github.com/ngryman/lol-champions) +- [LoLdle Unlimited Variant — loldle.org](https://loldle.org/unlimited) + +--- + +**Report Status:** COMPLETE. All five modes documented. Emoji mode analyzed as "trivial for Telegram adaptation." Cross-mode data audit suggests single-bundle extraction is feasible. diff --git a/plans/reports/researcher-260424-2215-loldle-quote-mode.md b/plans/reports/researcher-260424-2215-loldle-quote-mode.md new file mode 100644 index 0000000..9489a24 --- /dev/null +++ b/plans/reports/researcher-260424-2215-loldle-quote-mode.md @@ -0,0 +1,278 @@ +# Loldle Quote Mode Research Report + +**Date:** 2026-04-24 +**Focus:** Loldle Quote mode mechanics, data sources, and Telegram bot adaptation feasibility + +--- + +## 1. Gameplay Mechanics + +**Core Loop:** +- Player presented with champion **quote text** (single line of in-game dialogue) +- Player has up to **6 incorrect guesses** to identify the champion +- After 6 failed guesses, **audio clue unlocks** — the voice track of the champion speaking that exact quote +- Binary feedback: correct/incorrect (no gradual hints like classic mode) +- Daily reset at 00:00 UTC (one quote per day, same for all players) + +**Difficulty Factor:** +- Many champions share similar tone, thematic dialogue, generic lines +- Short quotes often feel interchangeable across champions +- Audio hint helps but champions with similar-sounding voices remain ambiguous +- Requires genuine champion knowledge, not just systematic elimination (unlike classic mode) + +**Comparison to Classic Mode:** +- Classic mode: feedback based on champion metadata (region, year, role, etc.) +- Quote mode: immediate right/wrong, then audio clue only +- Quote mode is harder — no attribute-based elimination strategy + +--- + +## 2. Data Source & Infrastructure + +### Quote Text Source +**WHERE:** Embedded in client-side JavaScript bundle (minified `app.{hash}.js`) + +**HOW TO ACCESS:** +1. Visit https://loldle.net/quote +2. Extract minified bundle from page source (find `app.xxx.js` in script tags) +3. Search bundle using regex: `championId` property locates champion data +4. Use extraction script (see: joulsen/loldle-information-theory repo) + +**FOUND REPOSITORY:** [joulsen/loldle-information-theory](https://github.com/joulsen/loldle-information-theory) +- Provides `resources/extract-champlist.py` for automated extraction +- Provides pre-extracted `resources/loldle-champ-data.json` +- Regex pattern: `=(\\\[\\{\_id:"\[^{}\]+championId:".+?\\}\\\])` + +**DATA STRUCTURE:** Quote data likely stored same way as classic-mode champion data: +- Each champion has array of properties (name, region, role, hp, etc.) +- Quote mode adds `quote` field with the dialogue text +- Quote may map to voice line ID or include URL reference + +### Audio Source +**WHERE:** Likely League of Legends Wiki or Riot-hosted CDN (cached during quote reveal) + +**MECHANICS:** +- Initially: only text shown +- After 6 wrong guesses: audio file loads via HTTPS +- Probable source: Riot Games CDN (per League Wiki structure) +- Format: OGG or MP3 (standard web audio) +- No direct URL exposed in initial puzzle request (audio fetched only after hint unlock) + +### Cache Endpoint +**https://cache.loldle.net/cache.json** +- Response is **Salted base64-encoded** (OpenSSL encryption) +- Contains aggregated game state/metadata +- Cannot be directly parsed without decryption key +- Likely syncs game state across devices, not primary data source + +### Data Freshness +- Quote data baked into JS bundle (no live API call for quote text) +- Audio file fetched at hint reveal (cached, not live-generated) +- Bundle updates when new champions added or quotes change (likely patch-synced) + +--- + +## 3. Scraping Feasibility + +### ✅ Can We Extract Quote-Champion Pairs? + +**YES** — with caveats: + +**Option A: Direct Bundle Extraction (Reliable)** +``` +1. Fetch https://loldle.net/quote +2. Parse HTML, find