tir

race the room to the target word. pick toward it — closest meaning, biggest leap. first to reach wins. one global room, real opponents.

A fast-twitch mobile semantic word-race game. Live on the App Store; Android APK from the aaam.dev/tir landing page. Players race from a hidden current word to a visible target word by repeatedly picking 1 of 4 options related by meaning (not spelling). First to land the target triggers a 3-second photo-finish window, then a 3-second results barrier, then a new target rotates in.

Built by aaam.dev.

Platforms: iOS (App Store) · Android (APK) Stack: React Native bare (Expo dev-client, SDK 54, new arch on) + @react-native-firebase/* + Firebase Cloud Functions (Node 20, v2 onCall) + Firestore.

---

Docs for humans & agents

Doc	Use
AGENTS.md	Start here — agent entry point, repo map, data model, callable contracts, the iter11 engine, V3 Elo, placement-period, onboarding flow
BLUEPRINT.md	Full product + technical spec: loop, multiplayer, the trust-the-graph word engine, difficulty system, rewards, anti-cheat, data model, cost model, current roadmap
SETUP.md	Machine setup: Node 20, Xcode, CocoaPods, Firebase CLI, running on device, deploying functions
SHIP.md	iOS shipping recipe: Xcode + Transporter (offline path) and EAS Build + Submit (online path)
BUILD-ANDROID.md	Android APK build via EAS (preview profile)
STORE.md	App Store metadata kit: name, subtitle, keywords, screenshots, privacy answers, age-rating
docs/DEVELOPER_GUIDE.md	Architecture: client bootstrap, callable contracts, Firestore ownership, indexes
docs/DESIGN.md	Visual language: voice, palette, typography, motion tokens, components, accessibility, HUD spec
docs/APPS_AND_FEATURES.md	Living brainstorm: shipped, currently building, next up, idea parking lot
TirApp/assets/brand/BRAND.md	Brand assets: the "off-center NE" mark, halo recipe, color tokens, lockup rules, iOS 26 Icon Composer wiring
QUESTIONS.md	Original game-design Q&A — the source of every product decision

---

What's playable today

Full multi-screen app (live on the iOS App Store at 1.0.1; new builds ship to TestFlight first):

• Anonymous Firebase auth, three-stage onboarding gate (/name → /welcome 3-card tutorial → home)
• Identity capture: 30-emoji avatar grid + name picker, with one-tap randomized handle so a player can ship in one tap
• One global room (3 UID-hashed shards, normal difficulty) + private rooms (4-character short codes, four difficulties: chill / normal / hard / expert)
• 4-option semantic gameplay loop with iter11 trust-the-graph engine (~1,250 curated words, GloVe + Numberbatch embeddings, cosine-threshold-based option generation, MMR diversity, per-difficulty target injection and bridge-word levers)
• 3-second photo-finish window + 3-second results barrier with pre-computed next round so the new target lands < 500 ms after the popup hits zero
• V3 pure pairwise Elo (K=16, FIDE-style; ELO 1000 default, ELO 100 floor) — single source of truth for ranked math; private rooms are practice (no Elo, no streaks)
• 5-round placement period that hides numerical Elo until you have a sample (the math still runs from round 1)
• 8-tier league ladder (stone → grandmaster), avatar wins-today glow, win-streak chip, daily-streak progression
• Solo diminishing-returns so off-peak solo wins still tick all the counters but can't be farmed into a viable ladder climb
• Account lifecycle: "reset progress" footer affordance hits a server deleteAccount callable (Apple App Review 5.1.1(v) compliant), then re-auths anon and routes back through onboarding
• Latency budget: ≤ 700 ms perceived lag from photo-finish 0 → results popup; ≤ 500 ms from popup 0 → new target

What's NOT done yet — see AGENTS.md § 14 and docs/APPS_AND_FEATURES.md.

---

Getting started

# Mobile app
cd TirApp
npm install
cd ios && bundle install && bundle exec pod install && cd ..
npx expo run:ios --device      # or: npx expo run:android

# Cloud functions
cd ../functions
npm install && npm run build
cd ..
firebase deploy --only functions,firestore:rules,firestore:indexes

Full prerequisites + troubleshooting: SETUP.md.

Heads up: tir uses @react-native-firebase/* (native modules), so it cannot run in Expo Go. You always build a custom dev client.

---

Brand

The mark is off-center NE: a centered cyan ring with a single filled cyan dot inside at the upper-right, on a warm-near-black canvas. Same structural recipe as Hum's "candlelight resonance" wave (single shape, dual halo, sharp pass) — different primitives, different personality. The wave hums; the bullseye locks in.

Full brand spec, halo recipe, lockup rules, and iOS 26 Icon Composer wiring: TirApp/assets/brand/BRAND.md.

Locked color tokens:

• canvas #0B0B12 (shared with Hum)
• accent #00E5FF (electric cyan; outer halo shifts to #66F0FF)

---

Status

• Phase 0: gameplay loop + finish-window + Elo (single screen)
• Phase 1: multi-screen IA (Expo Router), aaam.dev brand, visual identity, motion tokens, semantic engine on precomputed neighbors
• Phase 2: trust-the-graph engine (iter11 — cosine-threshold neighbor pipeline, MMR diversity, per-difficulty levers), Goldilocks normal-difficulty tuning, network-latency reduction, precomputed next-round, 8-tier ladder, V3 pairwise Elo, placement period, account deletion, three-stage onboarding, animated Elo numeral, lightning-burst win FX, confetti shower
• Phase 3: rerolls · event feed · anti-bot · daily seed target · friends list · emoji-only chat · cosmetics shop
• Phase 4 (launched 2026-05): App Store launch (apps.apple.com/us/app/tir-word-race/id6768131124) + aaam.dev/tir/ landing page
• Phase 4 (continued): Hindi rollout · paid acquisition · cohort retention dashboards

Roadmap detail in BLUEPRINT.md § 10. Recent working-state notes in reports/.

---

Personal-studio project — not for redistribution.