رنگ‌آوا: جورچین رنگ‌ها

یک بازی کامل و فارسی از سبک Sort Puzzle برای Android که با Kotlin و Jetpack Compose ساخته شده است. رابط کاربری از ابتدا راست‌به‌چپ طراحی شده، متن‌ها و پیام‌های قابل‌مشاهده کاملاً فارسی‌اند، و هر مرحله موسیقی MIDI اختصاصی خود را دارد.

قابلیت‌های اصلی

• ۶۰ مرحله قطعی و حل‌پذیر با سختی تدریجی، ۴ تا ۱۱ رنگ و چینش‌های متنوع
• موتور استاندارد انتقال رنگ با تشخیص حرکت معتبر، پیروزی، امتیاز یک تا سه ستاره و پیشنهاد حرکت
• رابط شیشه‌ای و پس‌زمینه Aurora، انیمیشن انتخاب لوله، کانفتی پیروزی و طراحی واکنش‌گرا
• اسپلش‌اسکرین تبلیغاتی برای «استودیو رنگ‌آوا» پیش از ورود به بازی
• ۶۰ آهنگ MIDI یکتا و تولیدشده برای پروژه؛ یک آهنگ حلقه‌ای برای هر مرحله
• افکت صوتی انتخاب، انتقال، خطا و پیروزی
• ذخیره پیشرفت، مرحله بازشده، ستاره‌ها، سکه، بوسترها و تنظیمات با DataStore
• هدیه روزانه، اقتصاد سکه و خرید راهنما، بازگشت حرکت و لوله کمکی
• تبلیغ جایزه‌ای برای دریافت سکه و تبلیغ بین‌مرحله‌ای در توقف‌های طبیعی بازی
• خرید حذف دائمی تبلیغ، باندل‌های ۲۴ و ۷۲ ساعته و اشتراک VIP ماهانه
• مدیریت رضایت تبلیغاتی و گزینه‌های حریم خصوصی با Google UMP
• پشتیبانی از حذف تبلیغ برای خریدار و VIP، و بوستر نامحدود در زمان VIP یا باندل فعال
• استفاده آفلاین از خود بازی؛ فقط تبلیغات و خریدها به اینترنت نیاز دارند

فناوری‌ها و نسخه‌ها

نسخه‌های پروژه در تاریخ ۲۷ ژوئیه ۲۰۲۶ تنظیم شده‌اند:

بخش	نسخه
Android Gradle Plugin	9.2.1
Gradle	9.4.1
Kotlin	2.4.10
Compose BOM	2026.06.01
AndroidX Core	1.19.0
Activity Compose	1.13.0
Lifecycle	2.11.0
Navigation Compose	2.9.8
DataStore Preferences	1.2.1
Play Billing	9.1.0
Google Mobile Ads Next-Gen	1.3.0
Google UMP	4.0.0

تنظیمات Android: minSdk 24، targetSdk 37، compileSdk 37 و Java 17.

اجرای پروژه

۱. پوشه پروژه را در Android Studio باز کنید. ۲. JDK پروژه را روی نسخه 17 یا JDK سازگار مورد تأیید Android Studio قرار دهید. ۳. Android SDK Platform 37 و ابزارهای Build Tools پیشنهادی IDE را نصب کنید. ۴. Gradle Sync را اجرا کنید. ۵. یک شبیه‌ساز یا دستگاه Android 7.0 به بالا انتخاب و برنامه را اجرا کنید.

فرمان‌های خط فرمان:

./gradlew test
./gradlew assembleDebug
./gradlew bundleRelease

اسکریپت‌های gradlew و gradlew.bat در اولین اجرا Gradle 9.4.1 را دانلود و checksum آن را بررسی می‌کنند. Android Studio نیز فایل gradle/wrapper/gradle-wrapper.properties را می‌خواند.

ساختار پروژه

app/src/main/java/com/rangava/sort/
├── data/              ذخیره پیشرفت و اقتصاد بازی
├── domain/            موتور بازی و تولید مراحل
├── media/             پخش MIDI و افکت‌های صوتی
├── monetization/      تبلیغات، رضایت و Google Play Billing
├── ui/                ViewModel، ناوبری و صفحه‌ها
└── util/              اعداد فارسی و نمایش زمان

شخصی‌سازی برند

• نام شرکت و متن تبلیغ ابتدایی: SplashScreen.kt
• نام برنامه: app/src/main/res/values/strings.xml
• شناسه بسته: applicationId و namespace در app/build.gradle.kts
• رنگ‌ها و تم: پوشه ui/theme
• آیکن: app/src/main/res/drawable/ic_launcher_foreground.xml

پس از تغییر applicationId، نام بسته فایل‌های Kotlin و مسیر پوشه‌ها را نیز با ابزار Refactor در Android Studio تغییر دهید.

راه‌اندازی AdMob

پروژه عمداً با شناسه‌های آزمایشی رسمی گوگل تحویل شده است تا هنگام توسعه کلیک نامعتبر روی تبلیغ واقعی ایجاد نشود.

مواردی که پیش از انتشار باید جایگزین شوند:

• TEST_APP_ID در RewardedAdManager.kt
• مقدار com.google.android.gms.ads.APPLICATION_ID در AndroidManifest.xml
• TEST_REWARDED_ID با شناسه تبلیغ Rewarded واقعی
• TEST_INTERSTITIAL_ID با شناسه Interstitial واقعی

در پنل AdMob بخش Privacy & messaging یک پیام رضایت ایجاد کنید. برنامه در هر اجرا وضعیت UMP را تازه‌سازی می‌کند و تبلیغ را فقط پس از مجازشدن درخواست تبلیغ مقداردهی اولیه می‌کند.

تعریف محصولات Google Play Console

شناسه‌ها باید دقیقاً با کد یکسان باشند:

شناسه	نوع	رفتار
remove_ads	محصول درون‌برنامه‌ای غیرمصرفی	حذف دائمی تبلیغات اجباری
starter_bundle_24h	محصول درون‌برنامه‌ای مصرفی	۷۰۰ سکه، بوسترها و دسترسی نامحدود ۲۴ ساعته
mega_bundle_72h	محصول درون‌برنامه‌ای مصرفی	۲۵۰۰ سکه، بوسترها و دسترسی نامحدود ۷۲ ساعته
vip_monthly	اشتراک	بدون تبلیغ و بوستر نامحدود ماهانه

برای اشتراک vip_monthly یک Base Plan ماهانه فعال بسازید. قیمت‌ها را در Play Console تعریف کنید؛ رابط بازی قیمت محلی دریافت‌شده از گوگل‌پلی را نمایش می‌دهد.

الزام امنیتی برای انتشار تجاری

کد کلاینت مسیر کامل نمایش محصول، خرید، بازیابی خرید، مصرف محصول و تأیید دریافت را پیاده‌سازی می‌کند؛ اما برای پول واقعی، اعتبارسنجی خرید نباید فقط روی دستگاه انجام شود. در نسخه انتشار:

• Purchase Token را به سرور امن خود ارسال کنید.
• خرید را با Google Play Developer API اعتبارسنجی کنید.
• اعطای محتوا را idempotent و وابسته به شناسه تراکنش کنید.
• وضعیت تمدید، لغو، بازپرداخت، grace period و انقضای VIP را با Real-time Developer Notifications همگام کنید.
• کلیدهای سرویس و اطلاعات حساس را هرگز داخل APK قرار ندهید.

قرارداد پیشنهادی بک‌اند در docs/BACKEND_API_FA.md آمده است.

موسیقی و دارایی‌ها

فایل‌های level_01.mid تا level_60.mid برای همین پروژه تولید شده‌اند و محتوای موسیقایی شخص ثالث در آن‌ها استفاده نشده است. چهار فایل WAV نیز افکت‌های ساده تولیدشده برای پروژه‌اند. Android از پخش فایل‌های MIDI نوع 0 و 1 پشتیبانی می‌کند و فایل‌های این پروژه Type 0 هستند.

آزمون‌ها و کنترل کیفیت انجام‌شده

• کامپایل مستقل کد دامنه با kotlinc
• بررسی ۶۰ مرحله: حل‌نشده در شروع، حداکثر ظرفیت چهار، چهار واحد از هر رنگ
• بررسی یکتابودن hash هر ۶۰ فایل MIDI و صحت header نوع 0
• بررسی سلامت چهار WAV
• Parse همه فایل‌های XML
• تست‌های واحد موتور در GameEngineTest.kt

ساخت کامل APK در این محیط تحویل انجام نشده است، چون Android SDK و مخزن وابستگی‌های Gradle در محیط اجرا در دسترس نبود. پروژه برای Sync و Build در Android Studio آماده شده است و پیش از انتشار باید روی حداقل یک دستگاه واقعی و چند اندازه صفحه آزمایش شود.

فایل‌های تکمیلی

• docs/PUBLISHING_CHECKLIST_FA.md: فهرست انتشار
• docs/BACKEND_API_FA.md: قرارداد پیشنهادی اعتبارسنجی خرید
• docs/PRIVACY_POLICY_TEMPLATE_FA.md: قالب سیاست حریم خصوصی
• ASSETS_NOTICE_FA.txt: توضیح دارایی‌های صوتی