CoolFace
Datasetpublic

mohmedmm/shkobba-bots

Shkobba Game - الدليل الشامل والمحدد للمشروع (AI Context & Architecture) تنبيه للذكاء الاصطناعي (AI Prompt & Context Anchor):اقرأ هذا الملف بعناية؛ فهو المرجع الحصري والشامل لهيكلية هذا المشروع، نماذج البيانات، وطريقة عمل السيرفر والواجهات، لتجنب استهلاك الـ Tokens في استكشاف الملفات مراراً. 📌 1. نبذة عن المشروع وTech Stack Flutter & Dart: الواجهة الأمامية، الحركات والرسوميات، والمنطق. PocketBase (https://bas.nbox.ly): السيرفر وقاعدة البيانات الأساسية (REST… See the full description on the dataset page: https://huggingface.co/datasets/mohmedmm/shkobba-bots.

sourceHugging Faceupdated 13d agoView on Hugging Face
0likes604downloads
Dataset Card

Shkobba Game - الدليل الشامل والمحدد للمشروع (AI Context & Architecture)

تنبيه للذكاء الاصطناعي (AI Prompt & Context Anchor): اقرأ هذا الملف بعناية؛ فهو المرجع الحصري والشامل لهيكلية هذا المشروع، نماذج البيانات، وطريقة عمل السيرفر والواجهات، لتجنب استهلاك الـ Tokens في استكشاف الملفات مراراً.

📌 1. نبذة عن المشروع وTech Stack

  • —Flutter & Dart: الواجهة الأمامية، الحركات والرسوميات، والمنطق.
  • —PocketBase (`https://bas.nbox.ly`): السيرفر وقاعدة البيانات الأساسية (REST API + Realtime SSE Subscriptions).
  • —Riverpod: إدارة الحالة المركزية (State Management).
  • —Audioplayers: تشغيل المؤثرات الصوتية (الدخول المميز، ضربات الشكبة، أصوات الإيموجي، أصوات اللعب).
  • —VideoPlayer: تشغيل فيديوهات الدخول المميز (.mp4) في شاشة اللعبة.
  • —Python CustomTkinter (`admin_panel/admin_app.py`): لوحة التحكم والإدارة الشاملة للمحتوى والمتجر واللاعبين.

📂 2. هيكلية قاعدة البيانات في PocketBase (pb_schema.json)

اسم المجموعة (Collection)الوصف والحقول الأساسية
`shkobba_users`المستخدمين: firebaseUid, uniqueId, displayName, coins, gems, cups, xp, level, rank, equippedStrike, equippedStrikeColor, equippedStrikeSound, activeEntryId, equippedAnimation, entrySound, activeBadgeId, activeRoomCardUntil, ownedStrikes, ownedEntries, ownedEmojis, ownedSounds, ownedBadges, freeNameChanges, matchHistory.
`shkobba_store`متجر العناصر: name, description, price, imageUrl, soundUrl, type, section, linkedItemId, quantity, stock, soldCount, coins, isActive, isFeatured.
`shkobba_strikes`ضربات الشكبة: name, colorHex, soundUrl, description, price, quantity, stock, isFree, isActive.
`shkobba_entries`الدخول المميز: name, url/animationUrl, soundUrl, type (video/image), price, quantity, stock, isFree, isActive.
`shkobba_emojis`الرموز التعبيرية: name, imageUrl, soundUrl, price, quantity, stock, isFree, isActive.
`shkobba_chests`صناديق الحظ: name, description, price, imageUrl, rewards (JSON), isActive.
`shkobba_matches`مباريات الأونلاين اللحظية: matchId, mode, status, hostId, playerIds, players, gameState, events, winnerId.
`shkobba_custom_rooms`الغرف الخاصة (صلاحية 3 ساعات): roomId, roomCode, hostId, pointsToWin, entryFee, prize, isVoiceEnabled, expiresAt.
`shkobba_invitations`دعوات المباريات الحية: fromUserId, toUserId, matchId, mode, status.

📂 3. الهيكلية العامة للكود (Project Files Breakdown)

🔹 1. الخدمات (lib/services/)

  • —`pocketbase_service.dart`: المحرك البرمجي الأساسي للاتصال بـ PocketBase، إدارة جلسات المستخدمين (watchActiveSession)، جلب وتحديث المستخدمين (getUserProfile, updateUser)، تفعيل المقتنيات (equipStrike, equipEntry)، تحديث المتجر (updateStoreProduct)، والمزامنة اللحظية عبر الـ SSE (watchMatch, watchActiveCustomRooms).
  • —`game_logic_service.dart`: الكود المركزي الحاكم لكل قواعد لعبة الشكبة (توزيع الكروت، الأكل، الكيشة/الحية، الميستو، حساب النقاط، والذكاء الاصطناعي للبوتات).
  • —`matchmaking_service.dart`: نظام البحث عن خصم والمطابقة التلقائية حسب الكؤوس (cups).
  • —`webrtc_voice_service.dart`: الدردشة الصوتية الحية داخل الغرف الخاصة.

🔹 2. إدارة الحالة (lib/providers/)

  • —`auth_provider.dart`: إدارة المستخدم الحالي، تدفق الـ userProfileProvider اللحظي من PocketBase، وتوابع التفعيل/إلغاء التفعيل (equipStrike, activateEntry, deactivateEntry, activateBadge).
  • —`app_data_provider.dart`: مزودي بيانات المتجر والمقتنيات (storeProductsProvider, strikesProvider, premiumEntriesProvider, emojisProvider).
  • —`game_provider.dart` & `online_game_provider.dart`: إدارة حالة دور المباراة، لعب الورق، ومزامنة أحداث اللعبة والإيموجي.

🔹 3. الشاشات والواجهات (lib/screens/)

  • —`game/game_screen.dart`: شاشة المباراة الرئيسية:
  • —تشمل نظام تحليق الورق (CardFlightOverlay) والأكل السريع (CaptureAnimationOverlay).
  • —تشمل انفجار ضربة الشكبة التفاعلية الملونة (ShkobbaStrikeOverlay).
  • —تشمل الدخول المميز البصري والصوتي في بداية المباراة (_buildEntryOverlay).
  • —مؤقت الـ 15 ثانية للعب التلقائي عند انتهاء الدور.
  • —`inventory/inventory_screen.dart`: شاشة المقتنيات:
  • —عرض المقتنيات وتفعيل أو إلغاء تفعيل حركة الدخول أو ضربة الشكبة أو الشارات، مع ضمان تفعيل عنصر واحد فقط في نفس الوقت.
  • —`store/store_screen.dart`: شاشة المتجر وشراء الصناديق والضربات وحركات الدخول مع إنقاص المخزون تلقائياً في السيرفر.
  • —`online/ranked_lobby_screen.dart`: لوبي البحث عن خصم في النمط المصنف (1v1 Ranked).
  • —`online/room_lobby_screen.dart`: لوبي إنشاء ودخول الغرف الخاصة بالكود.

🔹 4. لوحة الإدارة (admin_panel/admin_app.py)

  • —تطبيق سطح مكتب متكامل مبني بـ Python و CustomTkinter:
  • —إدارة وحذف وتعديل ضربات الشكبة والدخول المميز والرموز والمنتجات.
  • —تعديل الأسعار، الكميات المحدودة (stock/quantity)، وربط ملفات الصوت (soundUrl) وتشغيلها ومعاينتها مباشرة داخل التطبيق.
  • —إدارة المستخدمين وحظرهم وتعديل أرصدتهم.

⚙️ 4. قواعد ومحددات العمل (Critical Guidelines)

  1. 1.الاعتماد الكلي على PocketBase:
  2. 2.لا تستخدم Firebase لتخزين بيانات المستخدمين أو المتجر أو المقتنيات أو المخطط.
  3. 3.جميع عمليات التحديث والاستعلام تتم عبر PocketBaseService.
  1. 1.قواعد المقتنيات والتفعيل (Single Active Equip):
  2. 2.المستخدم يمكنه تفعيل ضربة شكبة واحدة فقط و حركة دخول مميز واحدة فقط.
  3. 3.عند النقر على "إلغاء"، يتم إفراغ الحقول (equippedStrike: '' أو activeEntryId: '') فوراً وتحديث واجهة المستخدم عبر ref.invalidate(userProfileProvider).
  1. 1.إنقاص الكمية والمخزون في المتجر:
  2. 2.عند شراء عنصر محدد الكمية، يتم إنقاص stock وزيادة soldCount وتحديث وصف المنتج في shkobba_store.