feat(profile): "set your city" gamification box → one-time 500-coin reward

- New searchable city picker (src/lib/iran-cities.ts, ~60 Iranian cities,
  fa/en search) shown as a gold reward card at the top of the profile Basic tab.
- First time a non-empty city is set, the player earns 500 coins (CITY_REWARD),
  granted server-authoritatively. Collapses to a compact summary afterwards with
  a "change city" option (no re-reward).
- Frontend: UserProfile.city + cityRewardClaimed; mock-service grants on first
  set; session/service updateProfile accept `city`; celebratory toast + sfx.
- Backend (.NET): ProfileDto.City/CityRewardClaimed (JSON blob → no migration);
  ProfileService.Update grants +500 once and writes a "city" ledger entry.
- i18n: city.* keys (fa + en).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

server/src/Hokm.Server/Profiles/ProfileModels.cs

@@ -59,6 +59,8 @@ public class ProfileDto
 
     // social
     public string Gender { get; set; } = ""; // "" | male | female | other
+    public string? City { get; set; } // selected city id (see client IRAN_CITIES)
+    public bool CityRewardClaimed { get; set; } // one-time "set your city" reward granted
     public SocialLinksDto Socials { get; set; } = new();
     public string SocialsVisibility { get; set; } = "public"; // public | friends | hidden
 

server/src/Hokm.Server/Profiles/ProfileService.cs

@@ -69,9 +69,27 @@ public class ProfileService
         if (patch.TryGetProperty("socialsVisibility", out var sv) && sv.ValueKind == JsonValueKind.String) p.SocialsVisibility = sv.GetString()!;
         if (patch.TryGetProperty("socials", out var so) && so.ValueKind == JsonValueKind.Object)
             p.Socials = JsonSerializer.Deserialize<SocialLinksDto>(so.GetRawText(), JsonOpts.Default) ?? p.Socials;
-        return await Save(p);
+        // One-time "set your city" reward: first non-empty city → +500 coins.
+        var cityRewarded = false;
+        if (patch.TryGetProperty("city", out var ci) && ci.ValueKind == JsonValueKind.String)
+        {
+            var city = ci.GetString();
+            p.City = city;
+            if (!string.IsNullOrWhiteSpace(city) && !p.CityRewardClaimed)
+            {
+                p.CityRewardClaimed = true;
+                p.Coins += CityReward;
+                cityRewarded = true;
+            }
+        }
+        await Save(p);
+        if (cityRewarded) await Ledger(uid, "city", CityReward, "profile-city");
+        return p;
     }
 
+    /// <summary>One-time coin reward for setting your city (mirrors client CITY_REWARD).</summary>
+    public const int CityReward = 500;
+
     public async Task<ProfileDto> UpgradePlan(string uid)
     {
         var p = await GetOrCreate(uid, null);

src/components/screens/ProfileScreen.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { motion } from "framer-motion";
-import { Check, ChevronLeft, Crown, Eye, EyeOff, Lock, LogOut, Pencil, Star, Upload, Users, Volume2 } from "lucide-react";
+import { Check, ChevronLeft, Crown, Eye, EyeOff, Gift, Lock, LogOut, MapPin, Pencil, Search, Star, Upload, Users, Volume2 } from "lucide-react";
 import { useRef, useState } from "react";
 import { ScreenHeader, ScreenShell } from "@/components/online/ScreenHeader";
 import { RankBadge } from "@/components/online/RankBadge";
@@ -16,12 +16,16 @@ import {
   ACHIEVEMENTS,
   CARD_BACKS,
   CARD_FRONTS,
+  CITY_REWARD,
   TITLES,
   achievementProgress,
   ownedAvatarIds,
   ownedCardBackIds,
   ownedCardFrontIds,
 } from "@/lib/online/gamification";
+import { IRAN_CITIES, cityById, searchCities, type City } from "@/lib/iran-cities";
+import { pushNotification } from "@/lib/notification-store";
+import { sound } from "@/lib/sound";
 
 /** Level required before a player can upload a custom profile photo. */
 const PHOTO_UPLOAD_MIN_LEVEL = 25;
@@ -95,6 +99,11 @@ export function ProfileScreen() {
       {/* ===== Basic: player card + stats/achievements ===== */}
       {tab === "basic" && (
         <div className="grid gap-4 items-start landscape:grid-cols-[minmax(0,340px)_minmax(0,1fr)]">
+          {/* one-time "set your city" reward */}
+          <div className="landscape:col-span-2">
+            <CityRewardCard />
+          </div>
+
           {/* player card */}
           <motion.div
             initial={{ opacity: 0, y: 16 }}
@@ -507,6 +516,155 @@ function SocialSettings() {
   );
 }
 
+/**
+ * One-time gamification box: pick your city from a searchable list and earn a
+ * 500-coin reward (granted server-side the first time a city is set). Once
+ * claimed it collapses to a compact summary with an option to change city.
+ */
+function CityRewardCard() {
+  const { t, locale } = useI18n();
+  const profile = useSessionStore((s) => s.profile);
+  const updateProfile = useSessionStore((s) => s.updateProfile);
+
+  const claimed = !!profile?.cityRewardClaimed;
+  const currentCity = cityById(profile?.city);
+  const [editing, setEditing] = useState(!claimed);
+  const [query, setQuery] = useState("");
+  const [pickedId, setPickedId] = useState<string | null>(profile?.city ?? null);
+  const [saving, setSaving] = useState(false);
+
+  const results = query.trim() ? searchCities(query, 40) : IRAN_CITIES.slice(0, 40);
+  const picked = cityById(pickedId ?? undefined);
+  const cityName = (c?: City) => (c ? (locale === "fa" ? c.fa : c.en) : "");
+
+  const choose = (c: City) => {
+    setPickedId(c.id);
+    setQuery(cityName(c));
+  };
+
+  const save = async () => {
+    if (!pickedId || saving) return;
+    const firstClaim = !claimed;
+    setSaving(true);
+    try {
+      await updateProfile({ city: pickedId });
+    } finally {
+      setSaving(false);
+    }
+    setEditing(false);
+    if (firstClaim) {
+      sound.play("award");
+      pushNotification({
+        kind: "system",
+        titleFa: `+${CITY_REWARD.toLocaleString("fa")} سکه دریافت شد! 🎉`,
+        titleEn: `+${CITY_REWARD} coins earned! 🎉`,
+        bodyFa: "شهر شما ثبت شد.",
+        bodyEn: "Your city has been saved.",
+        icon: "📍",
+      });
+    }
+  };
+
+  // ---- Claimed + collapsed: compact summary ----
+  if (claimed && !editing) {
+    return (
+      <div className="panel rounded-2xl p-3.5 flex items-center gap-3">
+        <span className="grid size-10 place-items-center rounded-xl bg-teal-500/15 text-teal-300 shrink-0">
+          <MapPin className="size-5" />
+        </span>
+        <div className="flex-1 min-w-0">
+          <div className="text-sm font-bold text-cream truncate">{cityName(currentCity) || t("city.unknown")}</div>
+          <div className="text-[11px] text-teal-300">{t("city.claimed")}</div>
+        </div>
+        <button
+          onClick={() => {
+            setEditing(true);
+            setQuery(cityName(currentCity));
+          }}
+          className="text-xs font-bold text-gold-300 hover:text-gold-200 px-2 py-1 rounded-lg"
+        >
+          {t("city.change")}
+        </button>
+      </div>
+    );
+  }
+
+  // ---- Editing / unclaimed: reward prompt + searchable picker ----
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 10 }}
+      animate={{ opacity: 1, y: 0 }}
+      className="rounded-3xl p-4 relative overflow-hidden border border-gold-500/30 bg-gradient-to-br from-gold-500/10 to-navy-900/40"
+    >
+      {!claimed && (
+        <div className="flex items-center gap-3 mb-3">
+          <motion.span
+            initial={{ scale: 0, rotate: -15 }}
+            animate={{ scale: 1, rotate: 0 }}
+            transition={{ type: "spring", stiffness: 240, delay: 0.05 }}
+            className="grid size-11 place-items-center rounded-2xl btn-gold shrink-0"
+          >
+            <Gift className="size-5" />
+          </motion.span>
+          <div className="min-w-0">
+            <div className="text-sm font-black text-cream">{t("city.rewardTitle")}</div>
+            <div className="text-[11px] text-gold-300 font-bold">
+              {t("city.rewardSub").replace("{n}", CITY_REWARD.toLocaleString(locale === "fa" ? "fa" : "en"))}
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* searchable city combobox */}
+      <div className="relative">
+        <Search className="absolute top-1/2 -translate-y-1/2 ltr:left-3 rtl:right-3 size-4 text-cream/40 pointer-events-none" />
+        <input
+          value={query}
+          onChange={(e) => {
+            setQuery(e.target.value);
+            setPickedId(null);
+          }}
+          placeholder={t("city.search")}
+          className="w-full rounded-xl bg-navy-900/70 gold-border ltr:pl-9 rtl:pr-9 px-3 py-2.5 text-sm text-cream placeholder:text-cream/30 outline-none focus:ring-2 focus:ring-gold-500/40"
+        />
+      </div>
+
+      {/* results — only while there's no committed pick yet */}
+      {!picked && (
+        <div className="mt-2 max-h-44 overflow-y-auto rounded-xl bg-navy-900/50 divide-y divide-navy-800/60">
+          {results.length === 0 && (
+            <div className="px-3 py-3 text-xs text-cream/40 text-center">{t("city.none")}</div>
+          )}
+          {results.map((c) => (
+            <button
+              key={c.id}
+              onClick={() => choose(c)}
+              className="w-full text-start px-3 py-2 text-sm text-cream/85 hover:bg-navy-800/70 flex items-center gap-2"
+            >
+              <MapPin className="size-3.5 text-cream/40 shrink-0" />
+              {cityName(c)}
+            </button>
+          ))}
+        </div>
+      )}
+
+      {/* confirm / claim */}
+      {picked && (
+        <button
+          onClick={save}
+          disabled={saving}
+          className="press-3d btn-gold w-full rounded-xl py-3 mt-3 font-black text-sm flex items-center justify-center gap-2 disabled:opacity-60"
+        >
+          <MapPin className="size-4" />
+          {claimed
+            ? t("city.saveCity").replace("{city}", cityName(picked))
+            : t("city.claim").replace("{n}", CITY_REWARD.toLocaleString(locale === "fa" ? "fa" : "en"))}
+        </button>
+      )}
+    </motion.div>
+  );
+}
+
 function SoundSettings() {
   const { t } = useI18n();
   const { sfx, toggleSfx } = useSoundStore();

src/lib/i18n.tsx

@@ -152,6 +152,15 @@ const fa: Dict = {
   "chat.placeholder": "پیام بنویسید…",
   "chat.send": "ارسال",
   "chat.emoji": "ایموجی",
+  "city.rewardTitle": "شهرت را انتخاب کن!",
+  "city.rewardSub": "{n} سکه هدیه بگیر",
+  "city.search": "جستجوی شهر…",
+  "city.none": "شهری پیدا نشد",
+  "city.claim": "ثبت و دریافت {n} سکه",
+  "city.saveCity": "ذخیره: {city}",
+  "city.claimed": "جایزهٔ شهر دریافت شد ✓",
+  "city.change": "تغییر",
+  "city.unknown": "نامشخص",
   "chat.empty": "گفتگو را شروع کنید",
   "friends.message": "پیام",
 
@@ -503,6 +512,15 @@ const en: Dict = {
   "chat.placeholder": "Type a message…",
   "chat.send": "Send",
   "chat.emoji": "Emoji",
+  "city.rewardTitle": "Set your city!",
+  "city.rewardSub": "Earn {n} coins",
+  "city.search": "Search city…",
+  "city.none": "No city found",
+  "city.claim": "Save & get {n} coins",
+  "city.saveCity": "Save: {city}",
+  "city.claimed": "City reward claimed ✓",
+  "city.change": "Change",
+  "city.unknown": "Unknown",
   "chat.empty": "Start the conversation",
   "friends.message": "Message",
 

src/lib/iran-cities.ts

@@ -0,0 +1,89 @@
+// Major Iranian cities for the profile "set your city" picker.
+// `id` is a stable slug; `fa`/`en` are display names (search matches either).
+
+export interface City {
+  id: string;
+  fa: string;
+  en: string;
+}
+
+export const IRAN_CITIES: City[] = [
+  { id: "tehran", fa: "تهران", en: "Tehran" },
+  { id: "mashhad", fa: "مشهد", en: "Mashhad" },
+  { id: "isfahan", fa: "اصفهان", en: "Isfahan" },
+  { id: "karaj", fa: "کرج", en: "Karaj" },
+  { id: "shiraz", fa: "شیراز", en: "Shiraz" },
+  { id: "tabriz", fa: "تبریز", en: "Tabriz" },
+  { id: "qom", fa: "قم", en: "Qom" },
+  { id: "ahvaz", fa: "اهواز", en: "Ahvaz" },
+  { id: "kermanshah", fa: "کرمانشاه", en: "Kermanshah" },
+  { id: "urmia", fa: "ارومیه", en: "Urmia" },
+  { id: "rasht", fa: "رشت", en: "Rasht" },
+  { id: "zahedan", fa: "زاهدان", en: "Zahedan" },
+  { id: "hamedan", fa: "همدان", en: "Hamedan" },
+  { id: "kerman", fa: "کرمان", en: "Kerman" },
+  { id: "yazd", fa: "یزد", en: "Yazd" },
+  { id: "ardabil", fa: "اردبیل", en: "Ardabil" },
+  { id: "bandar-abbas", fa: "بندرعباس", en: "Bandar Abbas" },
+  { id: "arak", fa: "اراک", en: "Arak" },
+  { id: "eslamshahr", fa: "اسلام‌شهر", en: "Eslamshahr" },
+  { id: "zanjan", fa: "زنجان", en: "Zanjan" },
+  { id: "sanandaj", fa: "سنندج", en: "Sanandaj" },
+  { id: "qazvin", fa: "قزوین", en: "Qazvin" },
+  { id: "khorramabad", fa: "خرم‌آباد", en: "Khorramabad" },
+  { id: "gorgan", fa: "گرگان", en: "Gorgan" },
+  { id: "sari", fa: "ساری", en: "Sari" },
+  { id: "shahriar", fa: "شهریار", en: "Shahriar" },
+  { id: "dezful", fa: "دزفول", en: "Dezful" },
+  { id: "kashan", fa: "کاشان", en: "Kashan" },
+  { id: "bojnurd", fa: "بجنورد", en: "Bojnurd" },
+  { id: "birjand", fa: "بیرجند", en: "Birjand" },
+  { id: "bushehr", fa: "بوشهر", en: "Bushehr" },
+  { id: "qaemshahr", fa: "قائم‌شهر", en: "Qaemshahr" },
+  { id: "babol", fa: "بابل", en: "Babol" },
+  { id: "amol", fa: "آمل", en: "Amol" },
+  { id: "khoy", fa: "خوی", en: "Khoy" },
+  { id: "sabzevar", fa: "سبزوار", en: "Sabzevar" },
+  { id: "neyshabur", fa: "نیشابور", en: "Neyshabur" },
+  { id: "najafabad", fa: "نجف‌آباد", en: "Najafabad" },
+  { id: "varamin", fa: "ورامین", en: "Varamin" },
+  { id: "bandar-anzali", fa: "بندر انزلی", en: "Bandar-e Anzali" },
+  { id: "yasuj", fa: "یاسوج", en: "Yasuj" },
+  { id: "ilam", fa: "ایلام", en: "Ilam" },
+  { id: "marvdasht", fa: "مرودشت", en: "Marvdasht" },
+  { id: "saveh", fa: "ساوه", en: "Saveh" },
+  { id: "bukan", fa: "بوکان", en: "Bukan" },
+  { id: "shahrekord", fa: "شهرکرد", en: "Shahrekord" },
+  { id: "maragheh", fa: "مراغه", en: "Maragheh" },
+  { id: "semnan", fa: "سمنان", en: "Semnan" },
+  { id: "gonbad-kavus", fa: "گنبد کاووس", en: "Gonbad-e Kavus" },
+  { id: "saqqez", fa: "سقز", en: "Saqqez" },
+  { id: "bandar-mahshahr", fa: "بندر ماهشهر", en: "Bandar-e Mahshahr" },
+  { id: "abadan", fa: "آبادان", en: "Abadan" },
+  { id: "khorramshahr", fa: "خرمشهر", en: "Khorramshahr" },
+  { id: "borujerd", fa: "بروجرد", en: "Borujerd" },
+  { id: "miandoab", fa: "میاندوآب", en: "Miandoab" },
+  { id: "marand", fa: "مرند", en: "Marand" },
+  { id: "torbat-heydarieh", fa: "تربت حیدریه", en: "Torbat-e Heydarieh" },
+  { id: "jiroft", fa: "جیرفت", en: "Jiroft" },
+  { id: "rafsanjan", fa: "رفسنجان", en: "Rafsanjan" },
+  { id: "sirjan", fa: "سیرجان", en: "Sirjan" },
+  { id: "kish", fa: "کیش", en: "Kish" },
+  { id: "qeshm", fa: "قشم", en: "Qeshm" },
+  { id: "other", fa: "سایر شهرها", en: "Other" },
+];
+
+const BY_ID: Record<string, City> = Object.fromEntries(IRAN_CITIES.map((c) => [c.id, c]));
+
+export function cityById(id?: string | null): City | undefined {
+  return id ? BY_ID[id] : undefined;
+}
+
+/** Case/diacritic-insensitive filter on either Persian or English name. */
+export function searchCities(query: string, limit = 30): City[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return IRAN_CITIES.slice(0, limit);
+  return IRAN_CITIES.filter(
+    (c) => c.fa.includes(q) || c.en.toLowerCase().includes(q) || c.id.includes(q),
+  ).slice(0, limit);
+}

src/lib/online/gamification.ts

@@ -803,3 +803,8 @@ export const DAILY_REWARDS = [100, 150, 200, 300, 400, 600, 1500];
 export function dailyRewardFor(day: number): number {
   return DAILY_REWARDS[Math.min(day, DAILY_REWARDS.length) - 1] ?? 100;
 }
+
+/* ----------------------- Profile-completion reward ----------------------- */
+
+/** One-time coin reward for setting your city on the profile. */
+export const CITY_REWARD = 500;

src/lib/online/mock-service.ts

@@ -6,6 +6,7 @@ import {
   ACHIEVEMENTS,
   CARD_BACKS,
   CARD_FRONTS,
+  CITY_REWARD,
   REACTION_PACKS,
   STICKER_PACKS,
   TITLES,
@@ -362,7 +363,13 @@ export class MockOnlineService implements OnlineService {
 
   async updateProfile(patch: Parameters<OnlineService["updateProfile"]>[0]) {
     const p = await this.getProfile();
-    this.profile = { ...p, ...patch };
+    const next = { ...p, ...patch };
+    // One-time reward: first time the player sets a (non-empty) city → +500 coins.
+    if (patch.city && patch.city.trim() && !p.cityRewardClaimed) {
+      next.coins = p.coins + CITY_REWARD;
+      next.cityRewardClaimed = true;
+    }
+    this.profile = next;
     this.saveProfile();
     return this.profile;
   }

src/lib/online/service.ts

@@ -56,7 +56,7 @@ export interface OnlineService {
       Pick<
         UserProfile,
         | "displayName" | "avatar" | "avatarImage" | "title" | "cardFront" | "cardBack"
-        | "gender" | "socials" | "socialsVisibility"
+        | "gender" | "city" | "socials" | "socialsVisibility"
       >
     >
   ): Promise<UserProfile>;

src/lib/online/types.ts

@@ -83,6 +83,8 @@ export interface UserProfile {
 
   // social
   gender?: Gender;
+  city?: string; // selected city id (see IRAN_CITIES)
+  cityRewardClaimed?: boolean; // true once the one-time "set your city" reward was granted
   socials?: SocialLinks;
   socialsVisibility?: SocialVisibility; // default "public"
 

src/lib/session-store.ts

@@ -26,7 +26,7 @@ interface SessionStore {
       Pick<
         UserProfile,
         | "displayName" | "avatar" | "avatarImage" | "title" | "cardFront" | "cardBack"
-        | "gender" | "socials" | "socialsVisibility"
+        | "gender" | "city" | "socials" | "socialsVisibility"
       >
     >
   ) => Promise<void>;