Usurp: The Kingdom (prototype)

A medieval status ladder. Rank is set only by lifetime spend, from Peasant up to King or Queen.

This is a prototype. All purchases are simulated. No real money moves, and the Founding Houses are fictional lore, not real users.

What's in it

• The Realm: one leaderboard sorted by lifetime spend, with titles painted onto bands
• The Rank Ladder: seat counts and entry floors per title
• Noble Houses: the brand sponsorship layer (simulated)
• Royal Decrees: 140 character broadcasts, free allowance by rank
• Court Games: dice, trivia and a joust bracket, cosmetic badges only
• The Charter: why this stays a status product and not a wager

Files

• app.js, home.js, styles.css, home.css, icon.svg: the Kingdom art from usurp-kingdom (living map, Court cutaway, crests, banners, rank insignia), unchanged
• realm.js, realm.css: the Realm game layer (ladder, leaderboard, decrees, houses, court games) built on that art
• realm.html: the single page that ties them together (the game prototype; moved off the homepage on 20 Oct 2026, noindex)

Running it

It's a static site with no build step. Open it in a browser, or deploy the folder to any static host. Progress is saved in the visitor's own browser (localStorage), so every visitor gets their own realm.

Not legal advice

A real Terms of Service and legal review are needed before any real money moves, including for the US market and India's Online Gaming Act (2025).

Homepage and emblems (20 Oct 2026)

• index.html is the Crest Studio homepage, generated by tools/build.py (home()): six crests for the visitor's last name, sample files from img/home/ (rebuild them with tools/home_assets.py), the emblem strip, gift and Logo Kit sections.
• crest-core.js is the one crest engine for the Studio, tools, share images and e-cards. Its 50 emblems are generated into the ART table by node tools/emblems/assemble.js from the drawings in tools/emblems/ (original art plus CC0 charges from Armoria).

Crest Studio traffic pages (added 20 Oct 2026)

Crest Studio (crest.html) is the only real paid product. These free pages exist to bring search and AI-answer traffic to it:

• Use-case pages: family-crest-maker.html, dnd-coat-of-arms-generator.html, wedding-crest.html, clan-logo-maker.html, school-house-crests.html
• Free tools: latin-motto-generator.html (motto-gen.js), fantasy-house-name-generator.html (house-gen.js), heraldry-symbols-and-meanings.html, coat-of-arms-template.html (files in templates/)
• crest-core.js is a copy of the Studio's crest art for these pages. Keep it in step with crest-studio.js.
• Studio links: /crest.html?d=CODE opens a design, ?motto= and ?name= fill just that field. /crest redirects to the Studio (vercel.json).
• Studio "Save a free preview image" gives an 800 px watermarked PNG that credits usurp.games, so shared previews bring people back.
• The $9 package (after payment): 4000 px PNG, 1200 px PNG, SVG, certificate of arms (US Letter 300 dpi, blazon + meaning + optional gift line), 1080 px profile picture, phone wallpaper. Blazon and meaning come from crest-core.js (blazon, meaning, tinctureNote), which crest.html also loads.
• $29 Crest Logo Kit (Dodo product pdt_0Nq8R4zhafrgCTZA1HYkj): everything in the $9 set plus transparent logos, shield-only mark, favicons, app icons, Discord icon, X/LinkedIn/YouTube banners and a brand sheet, zipped in the browser with JSZip. api/verify.js returns plan: kit|crest from Dodo's own product cart, so a $9 payment never unlocks the kit. Landing page: crest-logo-maker.html.
• family-crest-generator.html (family-gen.js): six crests seeded by a last name, shareable as ?name=.
• New guide pages are specs in tools/usecases.py (rules at the top of that file). Topic ideas waiting to be built are in tools/backlog.md.

Rebuild after editing content (tools/ is not deployed, see .vercelignore):

python3 tools/build.py     # pages, sitemap.xml, llms.txt
python3 tools/assets.py    # templates/ and og/ share images (needs Playwright)
python3 tools/indexnow.py  # after deploy: tell Bing, Yandex and others about every URL

Medieval games and ad slots (21 Oct 2026)

• /games/ hub plus four games: games/archery.html, games/joust.html, games/castle-defense.html, games/sword-duel.html. Pages come from tools/build.py (GAMES list). Each game is one canvas drawn in code, no image files: games/engine.js (shared: canvas, input, synthesized sound, overlays, best scores, sharing, the player's Crest Studio arms, ad slots, play tracking) and one script per game.
• Thumbnails and share images: python3 tools/game_shots.py after the build (plays each game and photographs it).
• Ads are off until configured: set ADS at the top of tools/build.py (AdSense publisher ID and a display ad unit ID), rebuild, deploy. That also writes ads.txt and the google-adsense-account meta tag. Set h5: True only after Google approves the account for H5 Games Ads (between-round interstitials via adBreak). Until then the banner slot shows a Crest Studio house ad, and every third round break (at most every two minutes) shows a skippable Crest Studio card. A directly sold banner goes in ADS['sponsor'].
• Play tracking: Microsoft Clarity custom events play_<game>, round_<game>, finish_<game>, share_<game>, crest_click_<game>, plus the session tag game. Optional GA4 events if ADS['ga'] is set.
• Local test hook: on localhost each game exposes window.__ug.st() (its state) and window.__ugFreeze.
• Speed: fonts are self-hosted in fonts/ (SIL OFL, licences included) and cached for a year; game scripts and games/games.css are referenced with ?v=<content hash> by tools/build.py and cached for a year (vercel.json). After editing any file in games/, rerun python3 tools/build.py so the pages point at the new version.
• Ads are robust to ad blockers and empty slots: a blocked or unfilled banner shows the house ad, and a between-round break that does not start within 2.5 s simply continues the game. Verified with Google's own test ads (test: True with H5 on shows Google's sample interstitial at the round break).

Embeddable games (21 Oct 2026)

• /embed/<id>.html (archery, joust, castle, duel): just the game, for other sites' iframes. Built by embed_page() in tools/build.py. No analytics, no ad network, no cookies (Microsoft says Clarity must not run on sites aimed at under-18s, and embeds will land on class pages). <base target="_blank"> opens every link in a new tab; links to usurp.games carry ?from=embed or ?from=embed-<game> so click-throughs show up in Clarity on our own pages. noindex, with a canonical to the real game page. The engine's embed mode (window.USURP_EMBED) never scrolls the host page and shares the game's canonical URL.
• The snippet (embed_code()): an iframe 480 x 724 (height falls back to the attribute if a CMS strips the CSS) plus a plain text credit link under it, which is the part search engines count as a backlink.
• Where people get it: a "Put this game on your website" box on each game page, and /games/embed.html (live preview, copy buttons, how-to for WordPress, Blogger, Google Sites, Wix, Squarespace, FAQ). Clarity event embed_copy_<game>.

More games, ad slots and portal builds (21 Oct 2026)

• Three more games: games/trebuchet-game.html (Siege: ten castles with real physics from Matter.js 0.20, MIT, self-hosted at games/vendor/matter.min.js), games/viking-chess.html (Hnefatafl: Brandubh 7x7 and Tablut 9x9, either side vs the computer at three strengths, or two players), games/nine-mens-morris.html (three strengths, or two players). The board-game computer players are alpha-beta searches with a time budget (think() in tafl.js and morris.js).
• Ad slots: two rails beside every game on screens 1180 px and wider (left: more games; right: Crest Studio), and one slot after the FAQ on every guide page (house content: the games). With ADS set in tools/build.py, the game pages fill them through games/engine.js and the guide pages through /ads.js; both fall back to the house content when no ad comes.
• Portal builds: python3 tools/portal.py /some/dir writes upload-ready CrazyGames zips (SDK v3, ads only at natural breaks, no links out), three covers per game and UPLOAD-KIT.md. Output goes outside the site (dist/ is git-ignored).

Play counter and stats page (21 Oct 2026)

• games/engine.js sends a tiny POST to /api/play?g=<game>&e=play|finish when a game starts or ends on usurp.games (never in embeds or portal builds). In Siege every castle started counts as a play.
• api/play.js adds 1 to two Redis hashes: plays:<ISO week> and plays:all (fields like tafl:play). It stores nothing about the player. POST only, our own pages only (Origin/Referer check), known games only.
• api/stats.js returns the last 12 weeks and all-time totals as JSON (cached 5 minutes); stats.html (built by stats_page() in tools/build.py, noindex, disallowed in robots.txt) shows them as tables.
• Storage: the free Upstash Redis database from the Vercel Marketplace, connected to this project. The functions read KV_REST_API_URL/KV_REST_API_TOKEN or UPSTASH_REDIS_REST_URL/UPSTASH_REDIS_REST_TOKEN. Until one is connected, pings are accepted and dropped, and the stats page says it is not connected.

Analytics (26 Oct 2026)

• Every public page loads Microsoft Clarity and Vercel Web Analytics (/_vercel/insights/script.js, cookieless) by default. One inline snippet loads both: TRACK in tools/build.py, copied into the hand-written pages (crest.html, realm.html, api/card.js). Change it in all four places.
• Opt-out: "Privacy choices" in the footer links to /privacy.html#analytics. Turning off takes a confirm step; turning back on is one click. The choice is localStorage['ug-analytics'] = 'off' in that browser: the snippet then loads neither tag, sets window.UG_NOTRACK, and UG.track in games/engine.js sends nothing (no Clarity events, no play counter). Turning off also deletes Clarity's first-party cookies (_clck, _clsk).
• In the UK, EEA and Switzerland, Clarity itself runs without cookies unless it gets a consent signal (Microsoft enforces this since 31 Oct 2025); we send none.
• The embeddable games under /embed/ deliberately load no analytics, because the embed page promises site owners none.

Daily content system (27 Oct 2026)

• .agents/product-marketing.md: product, audience, competitors and brand voice. Every marketing skill reads it first.
• .claude/skills/: the marketingskills pack (MIT, Corey Haines) plus dailypublish.
• content/10-day-plan.md: what goes out each day, per channel. /dailypublish <day> researches, drafts and audits that day's pieces into content/day<N>/ (copy, images, reels, research with sources, audit checklist). Nothing is posted automatically.
• tools/social_media.py: renders on-brand images (grid, single crest) and 9:16 crest-reveal MP4s with the site's own crest engine.
• .mcp.json: research connectors for Claude Code (Exa, Firecrawl, Context.dev, Apify). Each signs in with OAuth on first use (/mcp).
• content/ is in .vercelignore, so content work never changes the live site.

The Usurper, accounts and the installable app (29 Oct 2026)

• games/the-usurper.html (games/usurper.js): a medieval social deduction game for 4 to 10. Loyal knights do tasks; heavy tasks need several knights heaving at once and their strengths add up; one or two hidden Usurpers strike, sabotage (torches, postern gate) and can fake a heave. Councils (alarm or bell) talk with quick chat and vote.
• Multiplayer with no game server: the host's browser runs the match (and the computer knights) and the others connect peer to peer over WebRTC. games/vendor/peerjs.min.js (PeerJS 1.5.5, MIT) finds peers through the free PeerJS cloud broker (0.peerjs.com) and its TURN relays. Room ids are usurpgames-v1-<CODE>; Quick match tries public rooms pub-1 to pub-6 (join if open, host if free). Private rooms allow free text chat (filtered); public rooms are quick chat only. "Play now" runs the same host code locally against bots with no network. If the PeerJS cloud ever becomes unreliable, run our own PeerServer (npm peer) and pass host/port to new Peer.
• Local test hooks (localhost only): window.__us (state, ff(seconds) fast-forwards the host simulation).
• Accounts are optional (games/account.js, api/save.js): guest play by default; "Save my progress" makes a random 20-character save code in the browser, which is the login (no email or password). Progress (Usurper rank and stats, best scores, player name, Crest Studio design) is stored under a SHA-256 of the code, in Upstash Redis when connected, otherwise a private Vercel Blob store (BLOB_READ_WRITE_TOKEN). With neither, the UI says cloud save is not on yet and everything keeps working on the device. Saves are throttled (Blob's free tier allows 2,000 writes a month).
• Ads: ADS['sponsor']['name'] also goes on the Great Hall banners in The Usurper, and the sponsor image shows in its lobby. ADS['meta'] is an optional Meta Pixel ID (for measuring Meta ad campaigns only; update privacy.html first).
• Installable app: manifest.webmanifest, sw.js (network-first pages, cache-first versioned files), icons in img/app/ from node tools/app_icons.js. The games hub shows "Install the games as an app" when the browser offers it. This is also the base for the Play Store build (Trusted Web Activity); see the launch kit in the project docs.