Worldly 🌍

A polished, no-build world-knowledge & cultural-awareness learning game. The goal isn't just memorising capitals — it's building global literacy: languages, religions, flags, maps, music, everyday phrases and current events, reinforced with active recall and spaced repetition so it actually sticks.

Pure HTML/CSS/vanilla-JS (ES modules). No framework, no build step, no backend, no accounts, no tracking. All progress is saved locally in your browser. Deploys as plain static files (Cloudflare Pages / any static host).

▶ Play it live: playworldly.pages.dev

Quick start

Browsers block fetch() on file://, so serve the folder over HTTP:

cd Worldly
python3 -m http.server 8000     # or:  npm start
# open http://localhost:8000

Run the engine tests (no dependencies — plain node --test):

npm test        # Node tests over the quiz, SRS, map, router, language, progress-map
                # and Pokédex logic, plus integrity checks on the real data/ files

What's inside

Quizzes

Mode	Question
Country ↔ Capital	Both directions
Country → Language / Religion	Most widely spoken language, largest religion
Country → Currency / Population	Official currency, population (comma-formatted)
World Religions	Founders, sacred texts, holidays, symbols, places of worship, origins — study all faiths or focus on one
US / Mexico / Canada States → Capitals	All 50 + all 32 + all 13
Flag Mode	Identify the country from its flag
Historic Flags	Identify the nation from a flag of the past (34 entities)
Similar Flags	Tell look-alike flags apart, with tips (12 confusion groups)
Mixed / Challenge / Daily	Everything shuffled · timed with streak multiplier · one fixed set per day
Custom Study	Choose topics, regions, length — and multiple-choice or typed answers
Review Missed	Practice exactly what you got wrong

Narrowing a session. Mixed and Custom Study share a setup panel: switch question types off (no population questions right now), and pick the parts of the world to be asked about from a checklist inside a checklist — a continent with its subregions folded underneath, so "Asia" is one tick and "just the Middle East" is two. The continent's own box is a roll-up of its children and shows an indeterminate state when only some are on. A live count says how many questions the current selection can actually produce, and the selection is remembered: /quiz/mixed/setup is where you choose, and /quiz/mixed — the hero's quick-play button and any deep link — starts a round on that selection straight away.

Interactive maps

Click-the-country (world), click-the-state (US, Mexico, Canada), plus reverse modes (a region is highlighted — name it) and flag crossovers (see a flag → click its country, or a country is highlighted → pick its flag). A Regions & Continents mode lets you pick one continent — the world map zooms into just that part of the world. Inline SVG with pan/zoom and smallest-region hit-testing so nested regions (DC, Andorra…) are always selectable.

Explore

• Language Map — the whole world colored by what it actually speaks, either by language family or by the ten most widespread languages. Tap a key entry to show only that group; tap a country to open its page.
• Say Hello — tap any country and get its greeting in the local script, with a pronunciation guide, a literal gloss, two more phrases and a note on how the greeting is actually done (bow, handshake, cheek kisses).
• Country Guides — a page for every one of the 198 countries: the greeting, fast facts, five people it is known for, the events that shaped it, a short read on its culture, three things worth bringing up and one to tread carefully around.
• Phrases — common phrases & local sayings for 16 countries, with text-to-speech pronunciation (Web Speech API, on-device).
• Music — 17 countries, 46 songs that represent them, each with a short note on why, playable via YouTube's privacy-enhanced embed.
• Crises & Events — curated, dated background on ongoing world situations in two tiers: Underreported and Major Conflicts, with links to live sources (Wikipedia, ReliefWeb, news).
• Flag Key — a browsable reference (not a quiz) of every country, US state, and Mexican state by flag and name, with live search and a region filter on each tab.
• Flag Map — the other direction: point at any country on the world map and its flag appears at the cursor. A panel under the map keeps the last country you looked at, with its capital and a link to the full guide — which is also what a tap or a Tab gives you, since hover is a mouse idea.

Pokédex (a fun corner)

All 1025 Pokémon, browsable by generation with search and a type filter, plus seven practice modes (Who's That Pokémon?, typing, dex entries, generation, evolution, base stats, type matchups). Identify one correctly and it is registered to your dex; get it right three times running and it is mastered. Dex completion drives a trainer rank that tops out at Pokémon Master, so it is earned only by actually knowing them.

Practice can be scoped to a set — one generation, one type, or only the species you have not registered yet or have missed before — so "learn every Kanto Pokémon" is a project with a number that moves. The scope lives in the URL (/pokedex/quiz/poke_who?gen=1), so a filtered session survives a reload, a bookmark and the Back button, and Practice again repeats the same set.

It is deliberately a separate sandbox: progress lives under its own worldly_pokedex_v1 key and never touches your Worldly XP, level, streak, achievements or the leaderboard. Data and sprites are bundled locally, so it needs no network and adds nothing to the CSP.

Learning design

• Every answer teaches something: fun fact + Learn More links (Wikipedia, CIA World Factbook, culture guide) on every question.
• Spaced repetition: a Leitner-box scheme (js/srs.js) makes forgotten and missed items resurface far more often; mastered items get occasional refreshes.
• Weak-area tracking: per-category and per-region accuracy, most-missed list, one-tap review of your weak spots.
• Gamification that rewards learning: XP with a level curve, streaks, 23 achievements, and a local leaderboard.

Architecture

No build tooling — the browser loads ES modules directly. Game rules are pure functions, testable in plain Node, independent of the DOM.

Worldly/
├── index.html              # shell: app bar, nav, #app mount, toasts, bottom tab bar
├── css/
│   ├── styles.css          # design tokens, @font-face, base type, utilities, themes
│   ├── components.css      # the kit: buttons, cards, chips, meters, map widget
│   └── screens.css         # per-screen composition
├── js/
│   ├── data.js             # loads JSON datasets; flag URLs; lazy map loading
│   ├── state.js            # localStorage profile: XP, streaks, stats, SRS, achievements
│   ├── srs.js              # pure Leitner spaced-repetition picker
│   ├── quiz.js             # pure question-generation engine (all MCQ/typed modes)
│   ├── maps.js             # pure question engine for click-the-map modes
│   ├── languages.js        # pure bucketing/paint logic for the language choropleth
│   ├── culture.js          # pure lookup helpers for the country guide pages
│   ├── progressmap.js      # pure: which countries you know, derived from the SRS boxes
│   ├── mapview.js          # the one DOM-coupled map widget (pan/zoom/hit-test)
│   ├── achievements.js     # achievement evaluation against the profile
│   ├── pokedex.js          # pure question engine for the Pokédex practice modes
│   ├── pokestate.js        # Pokédex progress (its own localStorage key)
│   ├── pokedexview.js      # the Pokédex screens (helpers injected by main.js)
│   ├── icons.js            # the drawn SVG icon set used by the chrome
│   ├── router.js           # tiny History-API router (screen-agnostic; matchPath is unit-tested)
│   └── main.js             # controller: route table, rendering, quiz session
├── data/*.json             # countries, states, flags, religions, phrases, music, crises,
│                           # greetings (all 256 map regions), pokemon
├── data/culture/*.json     # per-country deep dives, one file per region
├── assets/maps/*.svg       # bundled world/US/Mexico/Canada maps (@svg-maps, CC BY / CC BY-NC)
├── assets/pokemon/*.png    # 1025 bundled sprites (~1.1 MB) — generated, see scripts/
├── assets/fonts/*.woff2    # Archivo variable (OFL) — self-hosted; the CSP allows no font CDN
├── scripts/build-pokedex.mjs  # dev-only: regenerates the dex data + sprites from PokéAPI
├── tests/*.test.mjs        # 181 Node tests for quiz.js, srs.js, maps.js, router.js, pokedex.js…
├── tests/e2e/*.spec.js     # 45 Playwright specs (screens, quiz, flag key, routing)
├── _headers                # Cloudflare Pages security + caching headers
└── robots.txt, sitemap.xml, site.webmanifest, LICENSE

Routing. Every screen has a real URL (/, /flags, /leaderboard, /quiz/:mode, /map/:mode, /crises/:slug, …) via the History API, so Back / Forward, bookmarks and deep links work. On Cloudflare Pages this needs no config beyond not shipping a top-level 404.html: Pages then serves the app shell for any unmatched path (SPA fallback), with Functions (/api/*) and real static assets still matched first. Unknown paths render an in-app 404 tagged noindex. Because asset URLs must resolve from multi-segment routes, all asset/fetch paths are root-absolute (a <base> tag would collide with the CSP's base-uri 'none').

Design system

The look is "deep chart & brass" — the vernacular of a bathymetric survey chart and the brass instruments you would read one with. Deep water is the ground, land and progress are struck in brass, and the latitude/longitude graticule is the structural device: it draws the section rules, the ticks on every progress bar, and the faint grid the cards sit on.

• One typeface. Archivo, as a variable font carrying both wght (100–900) and wdth (62–125). Width is the expressive axis: headlines run wide, reading text sits at 100%, dense data labels compress to ~78%. Self-hosted in assets/fonts/ because the CSP is default-src 'self' — a font CDN is blocked outright. Non-Latin scripts (the greetings screens) fall through to the OS stack by unicode-range, so no webfont ships for them.
• Three accents, and no more. Brass acts (buttons, XP, progress), jade means correct, coral means wrong, and a separate ice-cyan is reserved for focus rings so they stay visible on brass controls. Everything else is a neutral — which is what leaves room for 198 flags and an eleven-hue language map.
• Color that carries information. A six-hue continent key runs across region badges, the dashboard's continent bars and the country pages, so the same continent is the same color wherever it appears. The Language Map's eleven-slot categorical palette is separate and unchanged.
• Progress you can see. The home hero and the Statistics screen paint the world map with the countries you actually know, derived in progressmap.js from the Leitner boxes the profile already stores — no new tracking, and true of every profile that has ever existed.
• Motion once. One orchestrated moment (the hero map's wash-in); everything else moves only in answer to something you did. All of it is dropped under prefers-reduced-motion.

Why vanilla / no-build? Longevity and portability — nothing to npm install, no transpiler to age out, deploys anywhere static. The separation of pure logic (quiz.js, srs.js, maps.js) from rendering (main.js, mapview.js) keeps the core unit-testable.

Data model

countries.json records carry name, iso2, capital, region, subregion, population, language, religion, currency, funFact, history, wiki (+ optional note for contested facts). history is a one-sentence founding/independence note (who from, and when) shown alongside the fun fact on the reveal screen. Flags render from flagcdn.com by ISO code; historic flags from Wikimedia Commons. The player profile lives in localStorage under worldly_profile_v1.

Deployment (Cloudflare)

The live site (playworldly.pages.dev) is a Cloudflare Pages project. Merging to main deploys it — .github/workflows/deploy.yml runs the engine tests and then uploads the tree, so the commit CI tested is always the commit serving traffic. Nothing else should publish.

Rollback is "Retry deployment" on any earlier entry in the Cloudflare Pages dashboard; each deployment records the commit it came from.

The workflow needs two repository secrets — CLOUDFLARE_API_TOKEN (with the Cloudflare Pages: Edit permission) and CLOUDFLARE_ACCOUNT_ID. To deploy by hand in an emergency, npm run deploy.

(A separate, legacy Cloudflare Worker is still git-connected for historical reasons — its "Workers Builds" check on GitHub is unrelated to the live site and safe to ignore.) Caching + security headers (strict CSP, no unsafe-inline) ship in _headers; a service worker (sw.js) provides offline resilience and caches flags after first sight.

Data sources, accuracy & privacy

Facts are curated from public reference data (Wikipedia, CIA World Factbook). "Primary language" and "largest religion" are deliberate simplifications — the single most common answer for quiz purposes, not the full picture. Contested facts carry an inline note (e.g. Jerusalem's disputed status). Historic flags are shown for educational context only. Crises summaries are dated, curated background — not live reporting.

Privacy: progress is stored only in your browser; no accounts. Anonymous usage analytics via Microsoft Clarity (which screens/modes get used — never names, answers or saved progress). Music uses YouTube's privacy-enhanced (nocookie) embed.

Corrections welcome — everything lives in data/*.json and needs no code changes to extend.

Extending it

• Add a country / state / song / crisis: append an object to the relevant JSON file — it joins every relevant mode automatically.
• Add an achievement: add a definition to achievements.json; new types need one case in progressFor() (js/achievements.js).
• Add a quiz mode: an entry in MODES + a case in makeQuestion() (js/quiz.js), then a card in MODE_CARDS (js/main.js).
• Regenerate the Pokédex: node scripts/build-pokedex.mjs rewrites data/pokemon.json, data/pokemon_types.json and assets/pokemon/*.png from PokéAPI. It caches responses under scripts/.cache/, so a re-run is cheap and an interrupted run resumes.

Credits

Map SVGs adapted from @svg-maps (world/Mexico/Canada: CC BY 4.0 · USA: CC BY-NC 4.0) · flags by flagcdn.com · historic flag images from Wikimedia Commons · facts from Wikipedia & the CIA World Factbook · music via embedded YouTube (all rights remain with the artists and labels) · Pokédex data and sprites from PokéAPI. Pokémon and Pokémon character names are trademarks of Nintendo, Creatures Inc. and GAME FREAK Inc.; the Pokédex is an unofficial, non-commercial fan feature, not affiliated with or endorsed by them.

License

MIT — see LICENSE.