انتهيت من لعبتك الأولى، وصدرتها للويب والجوال كما شرحنا في مقال التصدير، وبدأ أصدقاؤك يلعبونها، ثم جاءت الطلبات التي لا تستطيع اللعبة وحدها أن تحققها: لاعب غير جواله ويريد تقدمه القديم، وآخر يسأل لماذا لا توجد قائمة بأفضل اللاعبين هذا الأسبوع، وثالث يريد أن يلعب جولة ضد شخص لا يعرفه. وأول ما يخطر لأغلب المطورين أن يحفظوا الدرجة في ملف داخل اللعبة، ثم يرسلوها إلى قاعدة بيانات سحابية تكتب فيها اللعبة مباشرة، وبعد أسبوع واحد تجد في رأس القائمة لاعباً جمع تسعمئة ألف تمرة في دقيقة واحدة، لأن كل ما تثق فيه اللعبة يستطيع اللاعب أن يغيره على جهازه. وهنا تحتاج ما يسمى خلفية الألعاب Game Backend: خدمة على السيرفر تملك الحسابات والبيانات والدرجات، وتقرر هي ما يقبل وما يرفض.
وفي هذا المقال سوف نبني هذه الخلفية لنسخة صغيرة من لعبة «جني التمر» التي بنيناها في مسار الألعاب، باستخدام Nakama، وهو سيرفر مفتوح المصدر للألعاب تشغله على سيرفرك، ومعه قاعدة بيانات PostgreSQL، وكل ذلك في Docker. وكل استجابة في المقال خرجت من المختبر نفسه، من طلبات REST حقيقية ومن لاعبين حقيقيين في Godot 4.7.2 دون شاشة.
وسوف نناقش في هذا المقال ما يلي:
- ماذا تحتاج اللعبة من الخلفية، وما الفرق بينها وبين سيرفر اللعب Game Server.
- الخيارات المتاحة، ولماذا اخترنا Nakama لهذا المقال، وكيف يعمل من الداخل.
- الحسابات Accounts: الدخول بمعرف الجهاز وبالبريد، والتوكن ومدته، وربط أكثر من طريقة دخول بحساب واحد.
- التخزين Storage: الصلاحيات، والإصدارات Versions، وما يحدث عندما يحفظ جهازان في الوقت نفسه.
- المتصدرون Leaderboards: لماذا لا تقبل الدرجة من اللعبة، وفحصها في السيرفر، والترتيب، وإعادة التعيين الأسبوعية.
- المطابقة Matchmaker ومباراة يملكها السيرفر Authoritative Match بلغة Lua، ولاعب صادق ضد لاعب يغش.
- الحدود الموجودة في إعدادات Nakama وما يحدث عند تجاوزها، وانتهاء الجلسة وتجديدها.
- القياس: زمن كل طلب، والذاكرة والمعالج مع 100 و200 و400 لاعب، وماذا يحدث إذا توقفت قاعدة البيانات.
- أخطاء شائعة، وقائمة فحص قبل الإنتاج.
ماذا تحتاج اللعبة من الخلفية Game Backend؟
الخلفية هي كل ما تحتاجه اللعبة من السيرفر ولا يتعلق بحركة اللاعبين لحظة بلحظة، وأغلب الألعاب الجماعية والفردية التي فيها حسابات تحتاج القائمة نفسها تقريباً:
- الحسابات Accounts: هوية ثابتة للاعب لا تضيع إذا حذف اللعبة، وطرق دخول متعددة له، من الجهاز إلى البريد إلى حسابات Google وApple وSteam.
- التخزين Storage: الحفظ Save Game والإعدادات والمخزون، على السيرفر لا على الجهاز، حتى ينتقل مع اللاعب.
- المتصدرون Leaderboards والبطولات Tournaments: قوائم مرتبة تتجدد كل يوم أو أسبوع، وهي أكثر ما يحاول اللاعبون الغش فيه.
- المطابقة Matchmaking: جمع لاعبين متقاربين في جولة واحدة.
- اللعب اللحظي Realtime: قناة مفتوحة بين اللاعب والسيرفر لرسائل الجولة والدردشة والإشعارات.
- الاقتصاد Economy: العملة داخل اللعبة والمشتريات والتحقق منها مع المتاجر.
وقد يتساءل البعض: أليس هذا هو سيرفر اللعبة نفسه؟ والإجابة أنهما شيئان مختلفان غالباً. فسيرفر اللعب المخصص Dedicated Server يشغل محاكاة الجولة بستين خطوة في الثانية، ويعرف موقع كل لاعب وكل رصاصة، ويعيش ما دامت الجولة. وأما الخلفية فتعيش دائماً، وتتعامل مع طلبات قصيرة، وتحفظ في قاعدة بيانات. ولعبة تصويب كبيرة تستخدم الاثنين معاً: الخلفية تسجل الدخول وتطابق اللاعبين وتحجز لهم سيرفر لعب، وسيرفر اللعب يدير الجولة ثم يرسل النتيجة إلى الخلفية. وأما لعبة بسيطة بجولات قصيرة مثل لعبتنا، فيكفيها أن تدير الخلفية نفسها الجولة كما سنرى. وشبكات اللعب الجماعي وتشغيل سيرفرات اللعب لها مقالاتها في هذه المرحلة:
دليلاللعب الجماعي Multiplayer: السيرفر صاحب القرار والتأخيرنبني في Godot 4 سيرفراً مخصصاً صاحب قرار وكلاينتات آلية، ثم نضيف التأخير والارتعاش والفقدان ونقيس كيف يخفي التنبؤ والمطابقة والاستيفاء أثرها عن اللاعب.
دليلخوادم الألعاب المخصصة Dedicated Servers على سيرفركنصدر سيرفر لعبة Godot بقالب التصدير ونغلفه في Docker، ونقيسه مع 64 لاعباً آلياً، ونجعله يحفظ ويفرغ مبارياته عند الإيقاف ونحدثه دون طرد أحد، ثم نقارنه بسيرفر Luanti ونعرف متى تحتاج Agones.
دليلمكافحة الغش Anti-Cheat في الألعاب: ما يمكن وما لا يمكننكتب كلاينتات تغش في لعبتنا الجماعية بأبسط الطرق، ونوقف كل غش منها بفحص على السيرفر ونقيس أثره على اللاعب الأمين، ثم نشرح ما لا يراه السيرفر وثمن مكافحة الغش في النواة.الخيارات Options: تبني بنفسك أم خدمة مدارة أم Nakama؟
قبل أن نختار، هذه الطرق الثلاث التي تراها في المشاريع:
- تبنيها بنفسك: واجهة API بأي لغة، وقاعدة بيانات، وجداول للحسابات والدرجات. وهذا ممكن تماماً لمن عنده خبرة Backend، ولكنك سوف تكتب بنفسك تسجيل الدخول وتخزين كلمات المرور والتوكن والتجديد والترتيب وإعادة التعيين والمطابقة والقناة اللحظية، وكل واحد منها له أخطاؤه المعروفة.
- خدمة مدارة: مثل PlayFab من Microsoft وEpic Online Services. لا تدير أي سيرفر، وتدفع بحسب الاستخدام أو تحصل عليها مجاناً ضمن شروط، ولكن بياناتك وقواعدك عند غيرك، وتغيير المزود لاحقاً مكلف.
- سيرفر جاهز مفتوح المصدر تشغله أنت: وهنا يأتي Nakama من شركة Heroic Labs، برخصة Apache 2.0، وفيه كل القائمة السابقة جاهزة، ومعه مكتبات عميل لـ Godot وUnity وUnreal والويب، وتستطيع أن تضيف منطقك الخاص بلغة Lua أو TypeScript أو Go.
واخترنا Nakama لهذا المقال لأنه يعمل على سيرفرك في Container واحد بجانب قاعدة البيانات، فتتحكم في البيانات وفي التكلفة، ولأن له مكتبة رسمية لـ Godot، المحرك الذي نستخدمه في مسار الألعاب. ولكن الأفكار في المقال، من التوكن القصير إلى المتصدرين الذين لا يكتب فيهم إلا السيرفر، هي نفسها في أي خلفية تختارها.
كيف يعمل Nakama من الداخل Architecture؟
Nakama برنامج واحد مكتوب بلغة Go، يفتح منافذ للاعبين ومنافذ للإدارة، ويحفظ كل شيء في قاعدة بيانات PostgreSQL أو CockroachDB، ويشغل بداخله الكود الذي تكتبه أنت. والشكل التالي يبين مكانه:

والأجزاء التي سوف نستخدمها في المختبر هي:
- واجهة HTTP على المنفذ 7350: طلبات REST عادية للدخول والحساب والتخزين والمتصدرين والدوال RPC، وعلى المسار
/wsفي المنفذ نفسه قناة WebSocket للعب اللحظي والمطابقة، وشرحنا الفرق بين الطلب العادي والقناة المفتوحة في مقال التواصل اللحظي. - لوحة الإدارة Console على المنفذ 7351: صفحة ويب تتصفح منها الحسابات والتخزين والمتصدرين، وهي للمشرف وحده.
- بيئة التشغيل Server Runtime: ملفات Lua أو TypeScript أو مكتبة Go تضعها في مجلد
modules، فيحملها Nakama عند التشغيل، وفيها تسجل الدوال RPC، والخطافات Hooks قبل أي طلب أو بعده، ومنطق المباريات. - قاعدة البيانات: Nakama ينشئ جداوله بنفسه بالأمر
migrate up، ولا تحتاج أن تكتب أي SQL.
وأهم فكرة في هذا الرسم أن كود السيرفر يعمل داخل Nakama، فعندما يطلب اللاعب «سجل درجتي»، فالذي يقرر هو كودك على السيرفر، لا كود اللعبة على جهاز اللاعب.
المختبر: Nakama 3.42 وPostgreSQL في Docker
استخدمنا الإصدار Nakama 3.42.0 الصادر في 3 نوفمبر 2026، وهو آخر إصدار عند كتابة المقال، والـ Image الرسمي heroiclabs/nakama:3.42.0 حجمه قرابة 60 ميجابايت مضغوطاً، ومعه postgres:16-alpine. ويشرح دليل التثبيت بـ Docker ملف Compose كاملاً، واستخدمنا الأمر نفسه الذي فيه داخل سكربت صغير، لأن المختبر يحتاج أن يعيد تشغيل Nakama وحده أكثر من مرة:
docker network create gm3-nk-net
docker run -d --name gm3-nk-pg --network gm3-nk-net -e POSTGRES_PASSWORD=labpass -e POSTGRES_DB=nakama \
-v gm3-nk-pgdata:/var/lib/postgresql/data gm3-nk-postgres:16-alpine
DB="postgres:labpass@gm3-nk-pg:5432/nakama"
docker run -d --name gm3-nk-nakama --network gm3-nk-net -p 127.0.0.1:27350:7350 -p 127.0.0.1:27351:7351 \
-v "$W/nakama:/nakama/data" -v "$W/nakama/${MODULES:-modules}:/nakama/data/modules" --entrypoint /bin/sh gm3-nk-nakama:3.42.0 -ecx \
"/nakama/nakama migrate up --database.address $DB && exec /nakama/nakama --config /nakama/data/local.yml --database.address $DB"في الأوامر أعلاه لاحظ التالي:
- أمران في Container واحد:
migrate upينشئ جداول القاعدة أو يحدثها، ثمexecيشغل السيرفر نفسه، وهذا ما يفعله ملف Compose الرسمي، فكل ترقية لـ Nakama تحدث القاعدة تلقائياً عند التشغيل. - المنافذ على
127.0.0.1فقط: حتى لا تفتح لوحة الإدارة للشبكة كلها، وفي الإنتاج يكون أمام المنفذ 7350 وحده Reverse Proxy مع TLS. - مجلد
modulesقابل للتبديل: المتغيرMODULESيسمح لنا بتشغيل نسختين من كود السيرفر، الأولى فيmodules-v1والمصححة فيmodules، وسوف ترى لماذا.
والإعدادات في ملف local.yml، وكل مفتاح فيه موثق في صفحة الإعدادات:
# Nakama 3.42 lab config (every key is documented on the configuration page; the rest stay at their defaults)
name: gm3-nk-nakama
logger:
level: INFO
session:
token_expiry_sec: 60 # default 60: a short-lived session token...
refresh_token_expiry_sec: 3600 # ...and a longer refresh token to get a new one
encryption_key: "lab-session-key-change-me"
refresh_encryption_key: "lab-refresh-key-change-me"
socket:
server_key: "lab-server-key" # the key every client sends; it is not a secret
max_message_size_bytes: 4096 # default
runtime:
http_key: "lab-http-key" # for server-to-server RPC calls without a user session
console:
username: admin
password: "lab-console-Pass1"
matchmaker:
max_tickets: 3 # default 3 per session
interval_sec: 2 # default 15; short so the lab does not waitفي الإعداد أعلاه لاحظ التالي:
encryption_key: المفتاح الذي يوقع به Nakama التوكن، فمن يعرفه يستطيع أن يصنع توكن لأي لاعب. والقيمة الافتراضية معروفة للجميع، فغيرها قبل أي شيء.server_key: ليس سراً، فهو داخل كل نسخة من اللعبة، ويستخدم فقط لطلبات الدخول قبل أن يكون للاعب توكن، فلا تبن عليه أي حماية.interval_sec: 2: كل كم ثانية يحاول الباحث عن الخصوم أن يكون مباراة، والافتراضي 15 ثانية، وقصرناه حتى لا ينتظر المختبر.
وعند التشغيل طبع Nakama هذه الأسطر، وحذفنا منها الوقت واسم الملف:
{"level":"info","msg":"Applying database migrations","limit":-1}
{"level":"info","msg":"Successfully applied migration","count":20}
{"level":"warn","msg":"WARNING: insecure default parameter value, change this for production!","param":"console.username"}
{"level":"warn","msg":"WARNING: insecure default parameter value, change this for production!","param":"console.signing_key"}
{"level":"info","msg":"Found runtime modules","count":2,"modules":["harvest.lua","main.lua"]}
{"level":"info","msg":"Registered Lua runtime RPC function invocation","id":"submit_score"}
{"level":"info","msg":"Registered Lua runtime Matchmaker Matched function invocation"}
{"level":"info","msg":"Leaderboard scheduler update","end_active_ts":-1,"end_active_count":0,"expiry_ts":1795305600,"expiry_count":1}
{"level":"info","msg":"Starting API server for gRPC requests","port":7349}
{"level":"info","msg":"Starting API server gateway for HTTP requests","port":7350}
{"level":"info","msg":"Starting Console server for gRPC requests","port":7348}
{"level":"info","msg":"Starting Console server gateway for HTTP requests","port":7351}
{"level":"info","msg":"Startup done"}والقراءة كما يلي:
- 20 ترحيلاً Migration: القاعدة كانت فارغة، فأنشأ Nakama جداوله كلها في نصف ثانية.
- تحذيران: اسم مستخدم لوحة الإدارة ما زال
admin، ومفتاح توقيع جلساتهاconsole.signing_keyما زال الافتراضي، وNakama يقول ذلك صراحة في كل تشغيل، فلا تتجاهله في الإنتاج. - ملفان من Lua ودالة RPC وخطاف للمطابقة: كودنا الذي سنشرحه في الأقسام التالية.
expiry_tsهو 1795305600: أي 22 نوفمبر 2026 الساعة 00:00 بتوقيت UTC، موعد أول إعادة تعيين للمتصدرين الأسبوعيين الذين أنشأهم كودنا.- أربعة منافذ: 7349 و7350 للاعبين بـ gRPC وHTTP، و7348 و7351 للوحة الإدارة. ونحن نستخدم HTTP لأنه ما تستخدمه مكتبة Godot وأسهل للتجربة.
وكل طلبات REST في المقال يرسلها سكربت Python صغير بمكتبته القياسية فقط، rest_tour.py، من Container على الشبكة نفسها، ويطبع لكل طلب الرمز HTTP والزمن والاستجابة، مع اختصار التوكن الطويل.
الحسابات Accounts: من هذا اللاعب؟
يدعم Nakama طرقاً كثيرة للدخول، ويذكر توثيق المصادقة منها معرف الجهاز Device ID، والبريد وكلمة المرور، وحسابات Apple وGoogle وFacebook وSteam وGame Center، والمعرف المخصص Custom ID الذي تربط به نظام حسابات عندك. وكل طريقة تنتهي بالشيء نفسه: حساب واحد في Nakama له معرف uid ثابت، وتوكن جلسة Session Token يرسله العميل مع كل طلب بعد ذلك.
الدخول بمعرف الجهاز Device Authentication
أسهل طريقة للاعب، لأنه لا يكتب شيئاً: اللعبة تولد معرفاً عشوائياً عند أول تشغيل وتحفظه على الجهاز، وترسله مع المعامل create=true، فينشئ Nakama الحساب إن لم يكن موجوداً. وهذا مخرج أول طلب في المختبر، ثم الطلب نفسه مرة ثانية:
=== 1. device authentication: the first time creates the account ===
POST /v2/account/authenticate/device -> HTTP 200 (140.9 ms)
{"created": true, "token": "eyJhbGciOiJIUzI1NiIsInR5...", "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5..."}
session token claims: {'tid': '0662bf68-6092-4fef-bdcf-fcf5b1db6c8c', 'uid': 'd6a11733-e340-4a9b-8152-cb193a25674f', 'usn': 'player_one', 'exp': 1795009264, 'iat': 1795009204}
refresh token claims: {'tid': '0662bf68-6092-4fef-bdcf-fcf5b1db6c8c', 'uid': 'd6a11733-e340-4a9b-8152-cb193a25674f', 'usn': 'player_one', 'exp': 1795012804, 'iat': 1795009204}
=== 2. the same device again: the same account, created=false ===
POST /v2/account/authenticate/device -> HTTP 200 (4.3 ms)
{"token": "eyJhbGciOiJIUzI1NiIsInR5...", "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5..."}والقراءة كما يلي:
created: trueفي المرة الأولى فقط: وفي المرة الثانية اختفى الحقل، أي أن الجهاز نفسه دخل الحساب نفسه. والطلب الأول أخذ 141 مللي ثانية لأنه أنشأ الحساب في القاعدة، والثاني 4.3 مللي ثانية.- توكنان لا توكن واحد: توكن الجلسة
tokenالذي يرسل مع كل طلب، وتوكن التجديدrefresh_tokenالذي لا يستخدم إلا للحصول على توكن جلسة جديد. - داخل التوكن: هو JWT موقع بخوارزمية HS256، وفكه السكربت دون أي مفتاح لأن الجزء الأوسط مرمز لا مشفر، وفيه
uidمعرف الحساب، وusnاسم المستخدم، وtidمعرف الجلسة المشترك بين التوكنين، وexpوiatوقت الانتهاء ووقت الإصدار. والفرق بينexpوiatفي توكن الجلسة 60 ثانية، وفي توكن التجديد 3,600 ثانية، كما في الإعدادات.
وشرحنا التوكن وفكه وتوقيعه بالتفصيل في مقال الجلسات وJWT، والذي يهمنا هنا أن اللاعب يستطيع أن يقرأ توكنه، ولكنه لا يستطيع أن يغير فيه حرفاً، لأن التوقيع يحتاج encryption_key الذي على السيرفر وحده. وهذا ما رأيناه عندما أرسلنا توكناً لم يوقعه Nakama:
=== 5. a token that Nakama did not sign ===
GET /v2/account -> HTTP 401 (2.5 ms)
{"code": 16, "message": "Auth token invalid"}ولماذا 60 ثانية فقط؟ يشرح توثيق الجلسات أن القيمة الافتراضية قصيرة عن قصد، وأن أغلب المشاريع في الإنتاج تجعلها ضعفين أو ثلاثة أضعاف متوسط جلسة اللعب، وتجعل توكن التجديد بين يوم و30 يوماً، وهي المدة التي يبقى فيها اللاعب مسجلاً دون أن يدخل من جديد. والفكرة أن التوكن الذي يسرق من جهاز أو من سجل Logs لا يعيش طويلاً، وأن الحساب الذي توقفه أنت يخرج من اللعبة خلال دقائق لا أيام.
وأما عيب الدخول بمعرف الجهاز فواضح: إذا حذف اللاعب اللعبة أو غير جواله، ضاع المعرف وضاع معه الحساب. ولذلك تأتي الخطوة التالية.
البريد وكلمة المرور Email Authentication
هذا مخرج ثلاثة طلبات: إنشاء حساب بالبريد، ثم دخول بكلمة مرور خاطئة، ثم إنشاء حساب بكلمة مرور قصيرة:
=== 3. email + password, then a wrong password, then a short one ===
POST /v2/account/authenticate/email -> HTTP 200 (1168.9 ms)
{"created": true, "token": "eyJhbGciOiJIUzI1NiIsInR5...", "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5..."}
POST /v2/account/authenticate/email -> HTTP 401 (1166.0 ms)
{"code": 16, "message": "Invalid credentials."}
POST /v2/account/authenticate/email -> HTTP 400 (3.8 ms)
{"code": 3, "message": "Password must be at least 8 characters long."}ولاحظ الأزمنة: الدخول بالجهاز أخذ 4 مللي ثانية، والدخول بالبريد أخذ 1,169 مللي ثانية، والرفض بكلمة مرور خاطئة أخذ الزمن نفسه تقريباً، 1,166. والسبب أن Nakama لا يحفظ كلمة المرور، وإنما يحفظ هاش Hash لها بخوارزمية bcrypt، وفي الكود المصدري للمصادقة تجد أن تكلفتها Cost لا تقل عن 13، أي أن حساب الهاش بطيء عن قصد، حتى يكون تخمين ملايين كلمات المرور مكلفاً على من يسرق القاعدة. والرفض يأخذ الزمن نفسه لأن السيرفر يحسب الهاش في الحالتين ثم يقارن. وهذا رقم يجب أن تعرفه عند التخطيط: كل دخول بالبريد يأخذ من المعالج قرابة ثانية على جهاز مشترك مثل جهاز المختبر، فلا تجعل اللعبة تدخل بالبريد مع كل جولة، وإنما مرة واحدة، ثم تعيش على توكن التجديد.
والطلب الثالث رفض في 3.8 مللي ثانية، دون أي هاش، لأن طول كلمة المرور يفحص أولاً.
ربط أكثر من طريقة دخول بحساب واحد Linking
الطريقة التي ينصح بها التوثيق للألعاب على الجوال: يبدأ اللاعب بمعرف الجهاز دون أي سؤال، ثم تعرض عليه اللعبة لاحقاً أن يربط بريده أو حساب Google أو Apple، فيصبح الحساب نفسه قابلاً للدخول من جهاز جديد:
=== 4. link an email to the device account, so the player can log in from a new phone ===
POST /v2/account/link/email -> HTTP 200 (873.9 ms)
{}
GET /v2/account -> HTTP 200 (7.3 ms)
{"user": {"id": "d6a11733-e340-4a9b-8152-cb193a25674f", "username": "player_one", "lang_tag": "en", "metadata": "{}", "create_time": "2026-11-18T13:40:04Z", "update_time": "2026-11-18T13:40:07Z"}, "wallet": "{}", "email": "[email protected]", "devices": [{"id": "lab-device-0001"}]}الحساب نفسه، بالمعرف d6a11733 نفسه، أصبح فيه بريد وجهاز. والربط أخذ 874 مللي ثانية لأنه يحسب هاش كلمة المرور الجديدة. ويذكر التوثيق أن الحساب يقبل أكثر من جهاز، ولكنه يقبل حساباً واحداً فقط من كل مزود، Google واحد وApple واحد، وأن أي واحد منها يكفي للدخول. وإذا كان عندك نظام حسابات أصلاً، مثل موقع بـ OpenID Connect، فالمعرف المخصص Custom ID أو الدخول عبر مزود هو ما تحتاجه، وشرحنا هذا البروتوكول في مقال OAuth وOpenID Connect.
وقد يتساءل البعض: هل اسم المستخدم player_one فريد؟ نعم، وهذا ما رجع عندما أرسلنا معرف جهاز جديداً مع الاسم نفسه:
curl -s -u lab-server-key: -X POST "http://127.0.0.1:27350/v2/account/authenticate/device?create=true&username=player_one" -d '{"id":"lab-device-9999"}'{"code":6, "message":"Username is already in use."}والرمز 6 هو ALREADY_EXISTS في رموز gRPC التي يستخدمها Nakama ويحولها إلى رموز HTTP. ولاحظ في الأمر أن طلبات الدخول تستخدم server_key كاسم مستخدم في Basic Auth بكلمة مرور فارغة، لأن اللاعب لم يحصل على توكن بعد. وفي لعبتك لا ترسل اسماً ثابتاً عند الإنشاء، وإنما اترك Nakama يولد اسماً عشوائياً، ثم دع اللاعب يغيره من الإعدادات، واعرض له هذا الخطأ إن اختار اسماً محجوزاً.

التخزين Storage: حفظ اللعبة على السيرفر
التخزين في Nakama كائنات JSON، لكل كائن ثلاثة أشياء تعرفه: المجموعة Collection، والمفتاح Key، والمالك User ID. فحفظ اللاعب الأول في الخانة الأولى هو المجموعة saves والمفتاح slot1 والمالك معرفه، ويستطيع لاعب آخر أن يحفظ بالمجموعة والمفتاح نفسيهما دون أي تعارض. ولكل كائن رقمان للصلاحيات، كما يشرح توثيق صلاحيات التخزين:
- القراءة
permission_read: 0 لا يقرؤه إلا السيرفر، و1 يقرؤه المالك فقط، و2 يقرؤه الجميع. - الكتابة
permission_write: 0 لا يكتبه إلا السيرفر، و1 يكتبه المالك.
كتب اللاعب الأول كائنين، حفظاً خاصاً وبطاقة عامة، ثم حاول لاعب آخر أن يقرأهما معاً:
=== 6. storage: a private save (read 1 = owner only) and a public profile (read 2 = everyone) ===
PUT /v2/storage -> HTTP 200 (15.3 ms)
{"acks": [{"collection": "saves", "key": "slot1", "version": "c58e0345b7edc517fe6ee7ddbcd42976", "user_id": "d6a11733-e340-4a9b-8152-cb193a25674f", "create_time": "2026-11-18T13:40:11.121530Z", "update_time": "2026-11-18T13:40:11.121530Z"}, {"collection": "profile", "key": "card", "version": "60676c0f592eb8d502d191d9c3ecf67f", "user_id": "d6a11733-e340-4a9b-8152-cb193a25674f", "create_time": "2026-11-18T13:40:11.121530Z", "update_time": "2026-11-18T13:40:11.121530Z"}]}
=== 7. another player reads both objects of player_one ===
POST /v2/storage -> HTTP 200 (6.2 ms)
{"objects": [{"collection": "profile", "key": "card", "user_id": "d6a11733-e340-4a9b-8152-cb193a25674f", "value": "{\"title\": \"date farmer\"}", "version": "60676c0f592eb8d502d191d9c3ecf67f", "permission_read": 2, "permission_write": 1, "create_time": "2026-11-18T13:40:11Z", "update_time": "2026-11-18T13:40:11Z"}]}والقراءة كما يلي:
- كل كتابة ترجع إصداراً
version: سلسلة من 32 حرفاً تتغير مع كل تعديل، وسوف نستخدمها بعد قليل. - اللاعب الآخر طلب كائنين ورجع له واحد: البطاقة العامة فقط، والحفظ الخاص لم يرجع أصلاً، لا خطأ ولا رسالة رفض. وهذا مقصود، فلا يعرف اللاعب حتى أن الكائن موجود، ولكنه يعني أيضاً أن كود اللعبة يجب ألا يفترض أن عدد ما يرجع هو عدد ما طلب.
حفظ جهازين في الوقت نفسه: الإصدارات Optimistic Concurrency
لنفرض أن اللاعب فتح اللعبة على الجوال وعلى الجهاز اللوحي، وكلاهما قرأ الحفظ بالإصدار c58e0345. لعب على الجوال حتى المستوى 4 وحفظ، ثم عاد إلى الجهاز اللوحي الذي ما زال على المستوى 3 وحفظ. ودون أي فحص، سوف يكتب الحفظ الثاني فوق الأول ويضيع تقدم الجوال، وهذا ما يسمى التحديث الضائع Lost Update. والحل الذي يقدمه Nakama هو الكتابة المشروطة Conditional Write: ترسل الإصدار الذي قرأته، فلا تنجح الكتابة إلا إذا كان الكائن ما زال على الإصدار نفسه:
=== 8. optimistic concurrency (OCC): two devices save from the same version ===
phone writes with version c58e0345 -> HTTP 200 (13.2 ms)
{"acks": [{"collection": "saves", "key": "slot1", "version": "b62c23012f9cd59278726e675452bff2", "user_id": "d6a11733-e340-4a9b-8152-cb193a25674f", "create_time": "2026-11-18T13:40:11.121530Z", "update_time": "2026-11-18T13:40:11.142994Z"}]}
tablet writes with the same old version -> HTTP 400 (4.8 ms)
{"code": 9, "message": "Storage write rejected - version check failed."}
version * = create only if missing -> HTTP 400 (4.5 ms)
{"code": 9, "message": "Storage write rejected - version check failed."}
what is stored now -> HTTP 200 (4.6 ms)
{"objects": [{"collection": "saves", "key": "slot1", "user_id": "d6a11733-e340-4a9b-8152-cb193a25674f", "value": "{\"dates\": 60, \"level\": 4}", "version": "b62c23012f9cd59278726e675452bff2", "permission_read": 1, "permission_write": 1, "create_time": "2026-11-18T13:40:11Z", "update_time": "2026-11-18T13:40:11Z"}]}في المخرج أعلاه لاحظ التالي:
- الجوال نجح: لأن الكائن كان على الإصدار الذي أرسله، فأصبح الإصدار
b62c2301. - الجهاز اللوحي رفض بالرمز 9: وهو FAILED_PRECONDITION، أي أن الشرط لم يتحقق، والرسالة واضحة:
version check failed. - الإصدار
*: يعني «اكتب فقط إن لم يكن الكائن موجوداً»، كما يشرح توثيق المجموعات، وهو مناسب لإنشاء الحفظ الأول مرة واحدة دون أن تقرأ قبله. والكائن موجود هنا، فرفض. - ما بقي في القاعدة: المستوى 4 والتمر 60، أي تقدم الجوال، وهذا هو المطلوب.
ويسمى هذا الأسلوب التحكم المتفائل في التزامن Optimistic Concurrency Control، واختصاراً OCC: لا تقفل الكائن أثناء اللعب، وإنما تفترض أن التعارض نادر، وتكتشفه عند الكتابة. وعندما يرفض الحفظ، لا تعد المحاولة بالقيمة نفسها، وإنما اقرأ الحفظ الجديد، ثم إما أن تدمج الاثنين إن كان ذلك ممكناً، كأن تأخذ أعلى مستوى وأكثر تمر، وإما أن تسأل اللاعب أي النسختين يريد، كما تفعل أغلب الألعاب التي تحفظ في السحابة. والشكل التالي يلخص الصلاحيات والإصدارات:

مشكلة ظهرت في المختبر: مجموعة Collection باسم يبدو رسمياً
في النسخة الأولى من كود السيرفر، احتجنا أن نحفظ آخر وقت أرسل فيه كل لاعب درجته، حتى نمنعه من الإرسال أكثر من مرة كل 30 ثانية كما سيأتي. فحفظناه في المجموعة anticheat والمفتاح last_submit، تحت معرف اللاعب نفسه، بصلاحيتي قراءة وكتابة 0 حتى لا يلمسه. ثم أضفنا إلى السكربت خطوة تحاول فيها اللعبة أن تكتب في هذا الكائن بنفسها، قبل أن يكون السيرفر قد كتبه:
=== 9. the client tries to overwrite the system-owned anticheat object ===
PUT /v2/storage -> HTTP 200 (18.5 ms)
{"acks": [{"collection": "anticheat", "key": "last_submit", "version": "776776e86967e364ba5537ade79c6a3e", "user_id": "d6a11733-e340-4a9b-8152-cb193a25674f", "create_time": "2026-11-18T13:40:11.170896Z", "update_time": "2026-11-18T13:40:11.170896Z"}]}نجحت الكتابة. والسبب أن المجموعة في Nakama مجرد اسم، فلا توجد مجموعة «خاصة بالسيرفر»، وكل لاعب يستطيع أن ينشئ أي كائن في أي مجموعة تحت معرفه، بالصلاحيات الافتراضية التي تسمح له بتعديله. وصلاحية الكتابة 0 تحمي الكائن فقط بعد أن يكتبه السيرفر بها، وهذا ما رأيناه عندما حاول اللاعب نفسه الكتابة بعد أول إرسال لدرجته:
cheat tries to reset its own timer -> HTTP 400 (12.3 ms)
{"code": 3, "message": "Storage write rejected - permission denied."}أي أن اللاعب يستطيع أن يسبق السيرفر فيضع في الكائن قيمة من عنده، والسيرفر في النسخة الأولى كان يقرأ هذا الكائن ويثق فيه. والإصلاح في النسخة الثانية أن تحفظ بيانات السيرفر تحت المستخدم الخاص بالنظام، الذي معرفه أصفار كلها، بمفتاح هو معرف اللاعب، فلا يستطيع أي لاعب أن ينشئ كائناً يملكه غيره:
local SYSTEM = "00000000-0000-0000-0000-000000000000" -- objects owned by the system user, one key per player
...
local rows = nk.storage_read({ { collection = "anticheat", key = context.user_id, user_id = SYSTEM } })وبعد الإصلاح، ما زال اللاعب يستطيع أن يكتب في مجموعة اسمها anticheat تحت معرفه، ورجعت الكتابة 200 في التشغيل الثاني، ولكن السيرفر لم يعد يقرأ ذلك الكائن أصلاً. والقاعدة: لا تقرأ في كود السيرفر بيانات يملكها اللاعب ثم تثق فيها، مهما كان اسم المجموعة.
المتصدرون Leaderboards: الدرجة لا تأتي من اللعبة
المتصدرون في Nakama قائمة مرتبة لها معرف، وأربعة إعدادات تحدد سلوكها، كما يشرح توثيق المتصدرين:
- الترتيب Sort: تنازلي
descللدرجات التي يكون الأعلى فيها أفضل، وتصاعديascلأزمنة السباق. - العامل Operator:
bestيحفظ أفضل درجة للاعب، وsetيحفظ آخر درجة، وincrيضيف إلى ما سبق، مثل مجموع التمر في الأسبوع. - جدول إعادة التعيين Reset Schedule: صيغة Cron، فتنتهي السجلات في موعدها ويبدأ أسبوع جديد فارغاً.
- هل هو authoritative؟ أي هل يكتب فيه السيرفر وحده.
وهذا كود السيرفر في main.lua كاملاً، بنسخته المصححة:
-- main.lua: loaded once when Nakama starts (every .lua file in data/modules is a module).
local nk = require("nakama")
-- 1. A weekly leaderboard: authoritative = clients cannot write to it, "best" keeps each player's best score,
-- reset every Sunday 00:00 UTC (cron), so a new week starts empty. The last argument turns on ranks
-- (off by default). The configuration of an existing leaderboard never changes: this line only creates it.
local LB = "dates_weekly"
nk.leaderboard_create(LB, true, "desc", "best", "0 0 * * 0", { game = "date-harvest" }, true)
local SYSTEM = "00000000-0000-0000-0000-000000000000" -- objects owned by the system user, one key per player
-- 2. The weak way: the client tells us its score and we check what we can.
local MAX_PER_SEC = 3 -- a player can pick at most 3 dates per second
local ROUND_MS = 60000 -- one round lasts 60 s
local function submit_score(context, payload)
local ok, req = pcall(nk.json_decode, payload)
if not ok or type(req) ~= "table" then error({ "bad json", 3 }) end -- 3 = INVALID_ARGUMENT
local score, ms = tonumber(req.score), tonumber(req.duration_ms)
if not score or not ms or score < 0 or ms <= 0 or ms > ROUND_MS + 5000 then
error({ "bad round", 3 })
end
if score > math.floor(ms / 1000 * MAX_PER_SEC) then -- impossible for a human
nk.logger_warn(("rejected score %d in %d ms from %s"):format(score, ms, context.user_id))
error({ "score not possible", 3 })
end
-- one submission per 30 s per player, remembered in storage owned by the system user (players cannot create it)
local now = nk.time()
local rows = nk.storage_read({ { collection = "anticheat", key = context.user_id, user_id = SYSTEM } })
if #rows > 0 and now - rows[1].value.t < 30000 then
error({ "too many submissions, wait", 8 }) -- 8 = RESOURCE_EXHAUSTED
end
nk.storage_write({ { collection = "anticheat", key = context.user_id, user_id = SYSTEM,
value = { t = now }, permission_read = 0, permission_write = 0 } })
local rec = nk.leaderboard_record_write(LB, context.user_id, context.username, score, 0, { ms = ms })
return nk.json_encode({ rank = rec.rank, score = rec.score })
end
nk.register_rpc(submit_score, "submit_score")
-- 3. The matchmaker found players: create a server-authoritative match running harvest.lua for them.
local function matchmaker_matched(context, matched_users)
local match_id = nk.match_create("harvest", { expected = #matched_users })
nk.logger_info(("matched %d players into %s"):format(#matched_users, match_id))
return match_id
end
nk.register_matchmaker_matched(matchmaker_matched)في الكود أعلاه لاحظ التالي:
leaderboard_createعند تحميل الملف: ينشئ المتصدرين إن لم يكونوا موجودين، ولا يغير شيئاً إن كانوا موجودين، وهذه النقطة سوف تكلفنا تجربة كاملة بعد قليل.- الأخطاء بـ
error({ "message", code }): هكذا يرجع كود Lua خطأ للاعب، والرقم من رموز gRPC، ويحوله Nakama إلى رمز HTTP، فالرمز 3 يصبح 400، والرمز 8 يصبح 429، كما يشرح توثيق بيئة Lua. context.user_id: معرف اللاعب يأتي من التوكن الذي تحقق منه Nakama، لا من جسم الطلب، فلا يستطيع لاعب أن يرسل درجة باسم غيره.- الحد الأقصى المعقول: 3 تمرات في الثانية، فدرجة أعلى من ذلك مستحيلة على إنسان في المدة التي يذكرها.
اللعبة تكتب درجتها مباشرة Client Write
هذا ما يحدث عندما ترسل اللعبة الدرجة إلى المتصدرين مباشرة، كما تفعل أغلب الدروس التي تشرح المتصدرين دون السيرفر:
=== 10. the client writes its score directly to the authoritative leaderboard ===
POST /v2/leaderboard/dates_weekly -> HTTP 403 (14.3 ms)
{"code": 7, "message": "Leaderboard only allows authoritative score submissions."}رفض بالرمز 7، PERMISSION_DENIED، لأن المتصدرين أنشئوا بـ authoritative = true. ولو أنشأناهم دون ذلك لقبل Nakama الدرجة 999 كما هي، لأن الطلب صحيح من لاعب مسجل. وهذا أهم سطر في هذا القسم: كل متصدرين في لعبة حقيقية يجب أن يكونوا authoritative.
فحص الدرجة في السيرفر عبر RPC
الطريق الثاني أن ترسل اللعبة درجتها ومدة الجولة إلى الدالة submit_score، فتفحصها ثم تكتبها. وهذا مخرج أربع محاولات: لاعب صادق بـ 150 تمرة في دقيقة، ثم لاعب يغش بـ 5,000، ثم يعيد المحاولة بـ 120، ثم يحاول مرة أخرى فوراً:
=== 11. through the RPC: a possible score, an impossible one, then too soon ===
POST /v2/rpc/submit_score -> HTTP 200 (34.1 ms)
{"payload": "{\"rank\":1,\"score\":150}"}
POST /v2/rpc/submit_score -> HTTP 400 (2.6 ms)
{"code": 3, "error": {}, "message": "score not possible"}
cheat retries with 120 -> HTTP 200 (19.4 ms)
{"payload": "{\"rank\":2,\"score\":120}"}
and again at once with 121 -> HTTP 429 (7.4 ms)
{"code": 8, "error": {}, "message": "too many submissions, wait"}والقراءة كما يلي:
- 5,000 رفضت في 2.6 مللي ثانية: قبل أي قراءة من القاعدة، وسجل Nakama السطر
rejected score 5000 in 60000 msفي سجله، وهذا السطر هو ما تراقبه لتعرف من يحاول. - 120 قبلت: وهذه هي حدود هذا الطريق. فالدرجة ممكنة، والسيرفر لا يعرف هل جمعها اللاعب فعلاً أم كتبها. والفحص هنا يضع سقفاً للكذبة، فيمنع 5,000 ولكنه لا يمنع 120، ولا يمنع 180 وهي الحد الأعلى.
- الرمز 429 للمحاولة الفورية: حد بسيط بإرسال واحد كل 30 ثانية، حتى لا يجرب الغشاش الدرجات واحدة بعد أخرى بحثاً عن الحد.
ولاحظ أن الحد الذي كتبناه يقرأ آخر وقت ثم يكتب الوقت الجديد في خطوتين، فطلبان يصلان في اللحظة نفسها قد يقرآن القيمة القديمة معاً وينجحان معاً. وهذه المشكلة نفسها التي قسناها في مقال تحديد معدل الطلبات تحت اسم «اقرأ ثم زد»، وحلها هناك عداد ذري، وهنا تستطيع أن تكتب الكائن بالإصدار الذي قرأته، فيرفض الطلب الثاني بـ version check failed كما رأينا في التخزين.
وقد يتساءل البعض: إذا كان الفحص لا يمنع 120، فما الحل؟ والإجابة أن الدرجة يجب ألا تأتي من اللعبة أصلاً، وإنما يحسبها السيرفر من أفعال اللاعب أثناء الجولة، وهذا ما سنفعله في قسم المباراة. والشكل التالي يقارن الطرق الثلاثة:

أين الترتيب Rank؟ إعدادات لا تتغير بعد الإنشاء
في النسخة الأولى من الكود، دون الوسيط الأخير في leaderboard_create، رجعت الدالة بـ "rank":0 لكل درجة، وجاءت قائمة اللاعبين حول اللاعب الأول دون ترتيب، بينما قائمة الثلاثة الأوائل فيها ترتيب:
POST /v2/rpc/submit_score -> HTTP 200 (31.4 ms)
{"payload": "{\"rank\":0,\"score\":150}"}
...
=== 12. top 3, then the records around player_one ===
rank 1 farmer_10 score 170 expires 2026-11-22T00:00:00Z
rank 2 farmer_13 score 160 expires 2026-11-22T00:00:00Z
rank 3 player_one score 150 expires 2026-11-22T00:00:00Z
around player_one:
rank (none) farmer_10 score 170
rank (none) farmer_13 score 160
rank (none) player_one score 150
rank (none) farmer_15 score 140
rank (none) farmer_12 score 130والسبب في مرجع دوال Lua: للدالة وسيط سابع enableRanks قيمته الافتراضية false، أي أن Nakama لا يحسب الترتيب ولا يحفظه في ذاكرة الترتيب Rank Cache إلا إذا طلبت ذلك. ولاحظ أن قائمة الأوائل جاءت بترتيب رغم ذلك، فلا تظهر المشكلة إلا في قائمة «حول اللاعب» وفي الرقم الذي ترجعه دالة الكتابة، وهما بالضبط ما تحتاجه الواجهة لتقول للاعب «أنت الثالث هذا الأسبوع». فأضفنا true وأعدنا تشغيل Nakama على القاعدة نفسها، فجاءت النتيجة نفسها تماماً، دون ترتيب. والسبب جملة في توثيق المتصدرين: كل إعدادات المتصدرين لا تتغير بعد إنشائهم، ويجب أن تحذفهم وتنشئهم من جديد إذا أردت تغيير الترتيب أو العامل أو جدول إعادة التعيين أو كونهم authoritative. والدالة leaderboard_create لا ترجع أي خطأ في هذه الحالة، فقط لا تفعل شيئاً. وعلى قاعدة جديدة جاء الترتيب كما ينبغي:
=== 12. top 3, then the records around player_one ===
rank 1 farmer_10 score 170 expires 2026-11-22T00:00:00Z
rank 2 farmer_13 score 160 expires 2026-11-22T00:00:00Z
rank 3 player_one score 150 expires 2026-11-22T00:00:00Z
around player_one:
rank 1 farmer_10 score 170
rank 2 farmer_13 score 160
rank 3 player_one score 150
rank 4 farmer_15 score 140
rank 5 farmer_12 score 130والدرس أوسع من الترتيب: إعدادات المتصدرين والبطولات قرار تتخذه مرة واحدة قبل الإطلاق، وإذا احتجت تغييرها بعد أن يلعب الناس، فالطريق الآمن متصدرون جدد بمعرف جديد، مثل dates_weekly_v2، تبدأ الكتابة فيهم من أول أسبوع جديد، بدل أن تحذف قائمة فيها درجات اللاعبين.
إعادة التعيين الأسبوعية Reset Schedule
كل سجل في المخرج أعلاه يحمل expiry_time هو 2026-11-22T00:00:00Z، وهو الموعد نفسه الذي طبعه Nakama عند التشغيل بالرقم 1795305600. والصيغة 0 0 * * 0 تعني الدقيقة 0 والساعة 0 من يوم الأحد، بتوقيت UTC، أي الساعة الثالثة فجر الأحد بتوقيت السعودية. وهذا مناسب لأسبوع يبدأ يوم الأحد، ولكن إذا كان جمهورك في منطقة زمنية أخرى، أو أردت أن تنتهي البطولة مساء الخميس، فاحسب الساعة بتوقيت UTC قبل أن تكتبها. وبعد الموعد لا يحذف Nakama السجلات القديمة، وإنما تنتهي صلاحيتها ويبدأ كل لاعب أسبوعاً جديداً من الصفر، وتستطيع أن تقرأ أسبوعاً منتهياً بمعامل الوقت في طلب القائمة، وأن تسجل خطافاً يعمل عند كل إعادة تعيين لتوزع الجوائز على الأوائل.
اللعب اللحظي Realtime: المطابقة ومباراة يملكها السيرفر
بعد الحسابات والمتصدرين، نريد أن يلعب لاعبان لا يعرف أحدهما الآخر جولة واحدة مدتها عشر ثوان، يقطف فيها كل منهما ما يستطيع من التمر، وتسجل الدرجة في المتصدرين دون أن تكتبها اللعبة. وهذا يحتاج ثلاثة أشياء من Nakama: قناة WebSocket مفتوحة لكل لاعب، والباحث عن الخصوم Matchmaker، ومباراة يديرها كود السيرفر.
مباراة ممررة Relayed أم مباراة يملكها السيرفر Authoritative؟
في Nakama نوعان من المباريات. النوع الأول يسميه التوثيق اللعب الجماعي الممرر Relayed Multiplayer، وفيه ينقل السيرفر رسائل كل لاعب إلى الآخرين كما هي دون أن يفهمها، ويقول التوثيق إنه مناسب للألعاب التي لا يهم فيها الغش، مثل اللعب التعاوني بين الأصدقاء. والنوع الثاني المباراة التي يملكها السيرفر Authoritative Multiplayer، وفيه يشغل Nakama كودك في حلقة بعدد ثابت من المرات في الثانية، يسمى معدل الخطوات Tick Rate، فيستلم رسائل اللاعبين، ويقرر ما يقبل منها، ويرسل الحالة للجميع. وهي فكرة السيرفر صاحب القرار نفسها التي تقوم عليها شبكات اللعب الجماعي، ولكن بحلقة بطيئة نسبياً تناسب ألعاب الجولات والألعاب على الجوال، لا ألعاب التصويب السريعة.
وفي لعبتنا لا يرسل اللاعب درجته أبداً، وإنما يرسل رسالة واحدة معناها «قطفت تمرة»، والسيرفر هو الذي يعد. وهذا ملف المباراة harvest.lua كاملاً:
-- harvest.lua: a server-authoritative round of the date harvest. The server owns the score:
-- clients only say "I picked" (op 1), and the server decides whether it counts.
local nk = require("nakama")
local M = {}
local OP_PICK, OP_STATE, OP_END = 1, 2, 3
local TICK_RATE = 10 -- match_loop runs 10 times a second
local ROUND_TICKS = 100 -- 10 s of play in the lab (a real round would be longer)
local COOLDOWN_TICKS = 3 -- at most one pick every 3 ticks = 3.3 picks per second
local JOIN_WAIT_TICKS = 300 -- if the players do not all arrive within 30 s, end the match
function M.match_init(context, params)
local state = { presences = {}, players = {}, expected = params.expected or 2, started_at = nil }
return state, TICK_RATE, nk.json_encode({ mode = "harvest" })
end
function M.match_join_attempt(context, dispatcher, tick, state, presence, metadata)
return state, true
end
function M.match_join(context, dispatcher, tick, state, presences)
for _, p in ipairs(presences) do
state.presences[p.session_id] = p
state.players[p.user_id] = state.players[p.user_id] or { name = p.username, score = 0, last = -100, sent = 0, refused = 0 }
end
return state
end
function M.match_leave(context, dispatcher, tick, state, presences)
for _, p in ipairs(presences) do state.presences[p.session_id] = nil end
return state
end
function M.match_loop(context, dispatcher, tick, state, messages)
if not state.started_at then
local n = 0
for _ in pairs(state.presences) do n = n + 1 end
if n < state.expected then -- wait for everyone before the clock starts...
if tick >= JOIN_WAIT_TICKS then -- ...but not forever
dispatcher.broadcast_message(OP_END, nk.json_encode({ error = "not enough players" }))
return nil
end
return state
end
state.started_at = tick
end
for _, m in ipairs(messages) do
local pl = state.players[m.sender.user_id]
if pl and m.op_code == OP_PICK then
pl.sent = pl.sent + 1
if tick - pl.last >= COOLDOWN_TICKS then pl.score = pl.score + 1; pl.last = tick
else pl.refused = pl.refused + 1 end -- too fast: ignored, not trusted
end
end
local elapsed = tick - state.started_at
if elapsed % TICK_RATE == 0 then -- once a second, tell everyone the scores
local s = {}
for uid, pl in pairs(state.players) do s[pl.name] = pl.score end
dispatcher.broadcast_message(OP_STATE, nk.json_encode({ t = elapsed / TICK_RATE, scores = s }))
end
if elapsed >= ROUND_TICKS then
local final = {}
for uid, pl in pairs(state.players) do
-- pcall: if the database is down, an error here would stop the match and the round would be lost
local saved = pcall(nk.leaderboard_record_write, "dates_weekly", uid, pl.name, pl.score, 0, { source = "match" })
if not saved then nk.logger_error("score not saved, keep it for a retry: " .. uid .. " " .. pl.score) end
final[pl.name] = { score = pl.score, sent = pl.sent, refused = pl.refused, saved = saved }
end
dispatcher.broadcast_message(OP_END, nk.json_encode(final))
nk.logger_info("round over: " .. nk.json_encode(final))
return nil -- returning nil ends the match
end
return state
end
function M.match_terminate(context, dispatcher, tick, state, grace_seconds) return state end
function M.match_signal(context, dispatcher, tick, state, data) return state, data end
return Mفي الكود أعلاه لاحظ التالي:
- سبع دوال إلزامية:
match_initترجع الحالة الأولى ومعدل الخطوات والوصف Label الذي يستخدم في البحث عن المباريات، وmatch_join_attemptتقبل اللاعب أو ترفضه، وmatch_joinوmatch_leaveعند الدخول والخروج، وmatch_loopقلب المباراة، وmatch_terminateعند إيقاف السيرفر، وmatch_signalلرسائل من كود السيرفر نفسه. - الحالة State جدول Lua تملكه المباراة: كل دالة تستلمها وترجعها، ولا يراها اللاعب إلا بما ترسله أنت.
match_loopعشر مرات في الثانية: تستلم كل الرسائل التي وصلت منذ الخطوة السابقة دفعة واحدة، فلا تعالج رسالة وحدها وقت وصولها.- حد السرعة بالخطوات: قطفة واحدة كل ثلاث خطوات، أي 3.3 في الثانية، وما زاد عليها يعد في
refusedولا يضاف إلى الدرجة. - إرجاع
nilينهي المباراة: بعد مئة خطوة، أي عشر ثوان، يكتب السيرفر الدرجات بنفسه ويرسل النتيجة. - سطران لم يكونا في النسخة الأولى: الانتظار بحد أقصى 30 ثانية، و
pcallحول كتابة الدرجة، وسوف ترى في قسمي الحدود وتوقف القاعدة لماذا أضفناهما.
الباحث عن الخصوم Matchmaker
اللاعب لا يختار المباراة، وإنما يرسل تذكرة Ticket إلى الباحث عن الخصوم فيها أقل عدد وأكبر عدد من اللاعبين وشروط اختيارية، مثل المستوى أو المنطقة. ويشرح توثيق المطابقة أن Nakama يمر على التذاكر كل interval_sec ثانية، 15 افتراضياً، فيجمع التذاكر التي تقبل بعضها، ويبقي الباقي للمرة التالية. وعندما يجد مجموعة، يستدعي الخطاف الذي سجلناه في main.lua بالدالة register_matchmaker_matched، فينشئ مباراة جديدة بـ match_create("harvest", ...) ويرجع معرفها، فيصل إلى كل لاعب في المجموعة إشعار فيه هذا المعرف ليدخل.
العميل في Godot: nakama-godot دون شاشة
اللاعبون في المختبر مشاريع Godot 4.7.2 تعمل بالخيار --headless في Containers، ومعها المكتبة الرسمية nakama-godot بالإصدار 3.4.0، وتضاف إلى المشروع كمجلد في addons ومفرد Autoload اسمه Nakama. ولاحظ أن آخر إصدار لها صدر في مارس 2024، ومع ذلك عمل مع Godot 4.7.2 دون أي تعديل في المختبر، وهذا يستحق أن تتحقق منه بنفسك عند كل ترقية للمحرك. وهذا الجزء المهم من سكربت اللاعب bot.gd:
client = Nakama.create_client("lab-server-key", opts.host, 7350, "http", 10, NakamaLogger.LOG_LEVEL.ERROR)
var session := await client.authenticate_device_async(opts.device, opts.name)
...
socket = Nakama.create_socket_from(client)
socket.received_matchmaker_matched.connect(_on_matched)
socket.received_match_state.connect(_on_state)
...
var r = await socket.connect_async(session)
...
var ticket: NakamaRTAPI.MatchmakerTicket = await socket.add_matchmaker_async("*", 2, 2)
func _on_matched(m: NakamaRTAPI.MatchmakerMatched) -> void:
...
var j = await socket.join_matched_async(m)
match_id = j.match_id
func _process(_delta: float) -> void:
...
if now - last_pick >= int(opts["pick-ms"]):
last_pick = now
sent += 1
socket.send_match_state_async(match_id, OP_PICK, "{}")في الكود أعلاه لاحظ التالي:
awaitفي كل طلب: كل دوال المكتبة غير متزامنة، فتنتظر النتيجة دون أن تتوقف حلقة اللعبة، وكل نتيجة تحملis_exception()لتعرف هل فشلت.- القناة من العميل نفسه:
create_socket_fromتأخذ العنوان والمنفذ من العميل، وconnect_asyncترسل التوكن، فلا يدخل القناة إلا من سجل الدخول. "*", 2, 2: أي لاعب، وجولة من لاعبين بالضبط.- الرسالة
{}: لا تحمل درجة ولا عدداً، فقط رمز العملية 1، أي «قطفت».
لاعب صادق ولاعب يغش في الجولة نفسها
شغلنا لاعبين: farmer_a يقطف كل 350 مللي ثانية، أي قرابة ثلاث تمرات في الثانية مثل لاعب سريع، وfarmer_cheat يرسل رسالة كل 50 مللي ثانية، أي عشرين في الثانية، كما لو عدل اللاعب قيمة السرعة في ذاكرة اللعبة. وهذا مخرج اللاعب الصادق:
[ 37 ms] farmer_a: logged in as user 0322529f, token expires in 60 s
[ 44 ms] farmer_a: realtime socket connected
[ 53 ms] farmer_a: matchmaker ticket bfd982d3, waiting for one more player
[ 1139 ms] farmer_a: matched after 1091 ms with 2 players, match cb4cf8f2-cfc6
[ 1146 ms] farmer_a: joined, 0 presences in the match
[ 1232 ms] farmer_a: state t=0s scores {"farmer_a":1.0,"farmer_cheat":1.0} (I sent 1 picks)
[ 4228 ms] farmer_a: state t=3s scores {"farmer_a":9.0,"farmer_cheat":11.0} (I sent 9 picks)
[ 7229 ms] farmer_a: state t=6s scores {"farmer_a":18.0,"farmer_cheat":21.0} (I sent 18 picks)
[ 10245 ms] farmer_a: state t=9s scores {"farmer_a":26.0,"farmer_cheat":31.0} (I sent 26 picks)
[ 11254 ms] farmer_a: round over, server says {"farmer_a":{"refused":0,"saved":true,"score":29,"sent":29},"farmer_cheat":{"refused":148,"saved":true,"score":34,"sent":182}}ومن مخرج اللاعب الآخر سطران فقط:
[ 7472 ms] farmer_cheat: state t=3s scores {"farmer_a":9.0,"farmer_cheat":11.0} (I sent 55 picks)
[ 14503 ms] farmer_cheat: round over, server says {"farmer_a":{"refused":0,"saved":true,"score":29,"sent":29},"farmer_cheat":{"refused":148,"saved":true,"score":34,"sent":182}}والقراءة كما يلي:
- من الدخول إلى القناة في 7 مللي ثانية: والمطابقة أخذت قرابة ثانية، لأن Nakama يمر على التذاكر كل ثانيتين في إعدادنا، وكان اللاعب الثاني لم يرسل تذكرته بعد.
- «0 presences» ثم «1 presences»: الأول دخل مباراة فارغة، والثاني وجد الأول فيها، ولذلك لا تبدأ الساعة في
match_loopإلا عندما يكتمل العدد. - الأرقام بفاصلة مثل
9.0: ليست من السيرفر، وإنما من Godot، لأنJSON.parse_stringيقرأ كل رقم كعدد عشري float. - اللاعب الصادق: أرسل 29 وقبلت 29، لم يرفض له شيء.
- اللاعب الذي يغش: أرسل 182 رسالة في عشر ثوان، ورفض السيرفر 148 منها، فبقيت درجته 34. ولو كانت اللعبة هي التي تحسب الدرجة لسجلت 182.
ولكن انظر إلى النتيجة مرة أخرى: الغشاش ما زال متقدماً بخمس تمرات، 34 مقابل 29. والسبب أن حد السيرفر 3.3 قطفة في الثانية، واللاعب الصادق يقطف 2.86، فمن يرسل بأقصى سرعة يأخذ دائماً الحد كله. والفحص في السيرفر لم يمنع الغش، وإنما حدد أقصى ما يكسبه الغشاش، وهذا هو الواقع في أغلب ألعاب الجوال. ولذلك اجعل الحد قريباً من أسرع لاعب حقيقي، لا أعلى منه بكثير، واجمع من السجلات من يصل إلى الحد في كل جولة، فهذا اللاعب يستحق نظرة. ومكافحة الغش بتفصيلها لها مقالها في هذه المرحلة.

الحدود في إعدادات Nakama وما يحدث عند تجاوزها
قد تتوقع أن تجد في صفحة الإعدادات خياراً عاماً لتحديد عدد الطلبات لكل لاعب أو لكل عنوان IP، ولكنه غير موجود فيها. والموجود حدود على الموارد، تحمي السيرفر من رسائل كبيرة أو من لاعب يفتح أشياء كثيرة. وهذا ما حدث عندما تجاوزنا اثنين منها:
[ 71 ms] farmer_t: logged in as user 57985618, token expires in 60 s
[ 77 ms] farmer_t: realtime socket connected
[ 110 ms] farmer_t: ticket 1: 604e6986
[ 127 ms] farmer_t: ticket 2: b088b362
[ 184 ms] farmer_t: ticket 3: 8b86031c
[ 222 ms] farmer_t: ticket 4: Error adding to matchmaker
[ 79 ms] farmer_big: logged in as user afdb9af1, token expires in 60 s
[ 86 ms] farmer_big: realtime socket connected
[ 93 ms] farmer_big: matchmaker ticket 97adebdf, waiting for one more player
[ 2501 ms] farmer_big: matched after 2415 ms with 2 players, match 3874123f-e63c
[ 2504 ms] farmer_big: joined, 0 presences in the match
[ 2504 ms] farmer_big: sending a 5000-byte message
[ 2512 ms] farmer_big: socket closed by the server
[ 172 ms] farmer_b: logged in as user 838a0d11, token expires in 60 s
[ 179 ms] farmer_b: realtime socket connected
[ 204 ms] farmer_b: matchmaker ticket 321ee8a2, waiting for one more player
[ 688 ms] farmer_b: matched after 509 ms with 2 players, match 3874123f-e63c
[ 704 ms] farmer_b: joined, 1 presences in the match
[ 30786 ms] farmer_b: round over, server says {"error":"not enough players"}والقراءة كما يلي:
- التذكرة الرابعة رفضت:
matchmaker.max_ticketsقيمته 3 لكل جلسة، فلا يستطيع لاعب أن يملأ الباحث بتذاكر كثيرة. والعميل لم يرجع إلا رسالة عامة،Error adding to matchmaker، والسبب الحقيقي في سجل السيرفر:matchmaker too many tickets. وهذا يعني أن رسائل الخطأ للاعب مقتضبة عن قصد، وأن التشخيص الحقيقي دائماً في السجل. - الرسالة الكبيرة أغلقت القناة كلها:
socket.max_message_size_bytesقيمته 4,096 بايت، والرسالة 5,000 بايت، وأكبر من ذلك على السلك لأن المكتبة ترمز البيانات بـ Base64 داخل JSON، فيزيد حجمها الثلث. ولم يرفض السيرفر الرسالة وحدها، وإنما أغلق اتصال اللاعب بعد 8 مللي ثانية، دون أي سطر في السجل بمستوى INFO. فإذا كانت لعبتك ترسل حالة كبيرة، مثل خريطة كاملة، فقسمها أو ارفع الحد عن علم. - المشكلة الحقيقية كانت عند اللاعب الآخر:
farmer_bدخل المباراة وبقي ينتظر خصماً لن يعود. وفي النسخة الأولى منharvest.luaبقي ينتظر حتى أوقفناه بعد 60 ثانية، لأن المباراة تنتظر اكتمال العدد دون حد. ولذلك أضفناJOIN_WAIT_TICKS، فانتهت المباراة بعد 30 ثانية برسالةnot enough players، ويستطيع العميل أن يعيد اللاعب إلى الباحث عن الخصوم.
وأما تحديد عدد الطلبات فمسؤوليتك في كودك، كما فعلنا في submit_score، أو في الـ Reverse Proxy أمام Nakama لطلبات HTTP مثل الدخول، بالطرق التي شرحناها في مقال تحديد معدل الطلبات. والحدود الأخرى في الإعدادات تستحق قراءة قبل الإطلاق، مثل socket.outgoing_queue_size، الذي يقول التوثيق إن تجاوزه يجعل السيرفر يعتبر اللاعب بطيئاً ويقطع اتصاله، وmatch.input_queue_size بحجم 128 رسالة تنتظر الخطوة التالية في كل مباراة.
انتهاء الجلسة وتجديدها Session Refresh
التوكن يعيش 60 ثانية في إعدادنا، فانتظر السكربت 62 ثانية ثم استخدمه:
=== 13. wait until the 60 s session token expires ===
GET /v2/account after 62 s -> HTTP 401 (5.6 ms)
{"code": 16, "message": "Auth token invalid"}
POST /v2/account/session/refresh -> HTTP 200 (11.1 ms)
{"token": "eyJhbGciOiJIUzI1NiIsInR5...", "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5..."}
GET /v2/account with the new token -> HTTP 200 (18.4 ms)
{"user": {"id": "b3663776-76c4-49a1-92ab-f5630d99bf2a", "username": "player_one", "lang_tag": "en", "metadata": "{}", "create_time": "2026-11-18T13:42:10Z", "update_time": "2026-11-18T13:42:10Z"}, "wallet": "{}", "devices": [{"id": "lab-device-0001"}]}التوكن المنتهي يرجع 401 بالرسالة نفسها التي رجعت للتوكن المزور، فلا يفرق العميل بينهما من الرسالة، وإنما يعرف وقت الانتهاء مسبقاً من exp داخل التوكن. والتجديد أخذ 11 مللي ثانية دون كلمة مرور، وهذا هو الفرق بينه وبين الدخول بالبريد الذي أخذ أكثر من ثانية. والطريقة الصحيحة في اللعبة أن تجدد قبل الانتهاء بقليل، لا بعد أن يفشل طلب، وتحفظ توكن التجديد على الجهاز حتى يبقى اللاعب مسجلاً بين جلسة وأخرى. ولاحظ في سطر الدخول في مخرج Godot token expires in 60 s، فالمكتبة تقرأ هذا الوقت من التوكن وتعطيك session.is_expired() لتفحصه قبل أي طلب.
كم يستهلك؟ القياس Measurements
زمن كل طلب Request Latency
أرسل السكربت 300 طلب من كل نوع، واحداً بعد الآخر، من Container على الشبكة نفسها، فلا يدخل في الأرقام زمن الإنترنت:
=== 14. 300 calls of each kind, one after another (ms) ===
GET /v2/account p50 9.64 p95 28.39 max 75.30
PUT /v2/storage p50 31.88 p95 69.37 max 172.89
GET /v2/leaderboard top 10 p50 6.21 p95 22.03 max 38.98
POST /v2/rpc/submit_score (rejected in Lua) p50 2.67 p95 14.92 max 30.55والقراءة كما يلي:
- الدالة التي ترفض في Lua أسرع طلب: 2.7 مللي ثانية في الوسيط، لأنها لا تلمس القاعدة، وهذا الزمن هو تكلفة Nakama نفسه مع التحقق من التوكن وتشغيل Lua.
- الكتابة في التخزين الأبطأ: 32 مللي ثانية في الوسيط، لأن كل كتابة معاملة Transaction تنتظر أن يكتب PostgreSQL على القرص.
- الفرق بين الوسيط p50 والنسبة 95 كبير: ثلاثة أضعاف أو أكثر، والجهاز مشترك تعمل عليه عشرات الـ Containers، وهذا ما يجعل الذيل Tail في أي قياس على جهاز مشترك أطول مما ستراه على سيرفر مخصص. وشرحنا لماذا ننظر إلى النسب المئوية لا إلى المتوسط في مقال زمن الاستجابة والإنتاجية.
ولا تأخذ الرقم المطلق من جهاز مشترك، وإنما الترتيب: ما يلمس القاعدة للكتابة أبطأ، وما يرفض قبلها أسرع، وما يحسب هاش كلمة مرور، كالدخول بالبريد، أبطأ من الجميع بمئة مرة.
اختبار الضغط Load Test: 100 و200 و400 لاعب معاً
لكي نضع ضغطاً حقيقياً، أضفنا إلى عميل Godot خيار --swarm N، فيشغل Godot واحد عدداً من اللاعبين، لكل منهم حسابه وقناته، يدخلون بمعدل خمسين في الثانية، ويطلبون المطابقة، ويلعبون جولة كاملة. والسكربت load.sh يقرأ docker stats طوال الجولة ويحفظ أعلى قيمة:
idle:
gm3-nk-nakama 0.06 36.43MiB
gm3-nk-pg 0.05 39.51MiB
100 players: swarm of 100: 100 finished a round, matchmaking p50 813 ms max 4483 ms, picks sent 2841, counted 2841
gm3-nk-nakama peak CPU 43.4% peak memory 118.8 MiB
gm3-nk-pg peak CPU 33.1% peak memory 252.4 MiB
samples: 34
200 players: swarm of 200: 200 finished a round, matchmaking p50 1273 ms max 2156 ms, picks sent 5602, counted 5602
gm3-nk-nakama peak CPU 89.2% peak memory 164.9 MiB
gm3-nk-pg peak CPU 14.1% peak memory 254.3 MiB
samples: 39
400 players: swarm of 400: 400 finished a round, matchmaking p50 970 ms max 4430 ms, picks sent 9226, counted 9192
gm3-nk-nakama peak CPU 113.9% peak memory 210.5 MiB
gm3-nk-pg peak CPU 31.8% peak memory 260.0 MiB
samples: 37والقراءة كما يلي:
- Nakama دون أي لاعب: 36 ميجابايت من الذاكرة وصفر تقريباً من المعالج، وPostgreSQL قرابة 40 ميجابايت.
- المعالج يكبر مع اللاعبين: 43% من نواة واحدة لمئة لاعب، و89% لمئتين، و114% لأربعمئة، أي أكثر من نواة. ونسبة الزيادة لا تتضاعف بالضبط مع العدد، لأن الدخول والمطابقة يتوزعان على ثوان مختلفة في كل تشغيل، ولأن عميل Godot نفسه يعمل على الجهاز نفسه وينافس على المعالج.
- ذاكرة Nakama: من 36 إلى 119 ثم 165 ثم 210 ميجابايت، أي قرابة نصف ميجابايت لكل لاعب متصل في جولة، وهي القنوات المفتوحة والجلسات والمباريات.
- ذاكرة PostgreSQL قفزت إلى 252 ميجابايت مع أول مئة لاعب ثم ثبتت: وهي غالباً الصفحات التي قرأتها القاعدة واحتفظت بها في ذاكرتها المشتركة Shared Buffers، لأنها لم تكبر بعد ذلك مع 200 و400 لاعب.
- المطابقة: الوسيط بين 0.8 و1.3 ثانية، وأسوأها 4.5 ثانية، وكلها قريبة من فترة المرور على التذاكر، ثانيتين في إعدادنا.
- 34 قطفة صادقة رفضت مع 400 لاعب: مع 100 و200 لاعب كان المرسل يساوي المقبول تماماً، ومع 400 قبل السيرفر 9,192 من 9,226. وكل اللاعبين هنا صادقون يقطفون كل 350 مللي ثانية، ولكن تحت الضغط تصل رسالتان من اللاعب نفسه في خطوة واحدة أو في خطوتين متتاليتين، فيراهما السيرفر أسرع من الحد. وهذه هي المشكلة الدائمة في أي فحص سرعة في السيرفر: الشبكة والضغط يجمعان الرسائل الصادقة، فإذا كان الحد قريباً جداً من سرعة اللاعب الحقيقية، عاقبت لاعبين أبرياء. ولذلك لا تحظر من قطفة مرفوضة واحدة، وإنما من نسبة مرفوضة كبيرة ومتكررة.

وهذه الأرقام لا تقول كم لاعباً يتحمل سيرفرك، لأن لعبتك ترسل رسائل مختلفة بمعدل مختلف، ولكنها تعطيك طريقة القياس: شغل لاعبين حقيقيين بمكتبة لعبتك نفسها، بالرسائل نفسها، وراقب المعالج والذاكرة وزمن المطابقة ونسبة الرسائل المرفوضة، ثم ضاعف العدد حتى ترى أين يبدأ الزمن بالارتفاع.
ماذا يحدث إذا توقفت قاعدة البيانات Database؟
كل شيء في Nakama يمر على PostgreSQL، فماذا يرى اللاعب إذا توقفت؟ أوقفناها مرتين: مرة في منتصف جولة، ومرة مع طلبات REST عادية بتوكن صالح، والسكربت dbdown.sh يوقف القاعدة بالأمر docker stop gm3-nk-pg ثم يعيدها.
طلبات REST العادية: انتظار طويل ثم خطأ Timeout
=== B. API calls with a valid session while the database is down
--- 17:09:01 docker stop gm3-nk-pg
GET /v2/account (needs the database) -> HTTP 500 (8095.2 ms)
{"code": 13, "message": "Error retrieving user account."}
RPC rejected in Lua before any query -> HTTP 400 (4.1 ms)
{"code": 3, "error": {}, "message": "score not possible"}
GET leaderboard top 3 -> HTTP 500 (7818.9 ms)
{"code": 13, "message": "Error listing records from leaderboard."}
device login -> HTTP 500 (7713.4 ms)
{"code": 13, "message": "Error finding user account."}والقراءة كما يلي:
- ثمان ثوان قبل الخطأ: لم يرفض Nakama فوراً، وإنما حاول الاتصال بالقاعدة حتى انتهت المهلة، فرجع 500 بالرمز 13، INTERNAL. وفي أحد التشغيلات السابقة لم يرجع الطلب الأول أي رد أصلاً، وأغلق السيرفر الاتصال بعد 12 ثانية، فرأى العميل
RemoteDisconnectedلا رمز HTTP. ولذلك اجعل لكل طلب في لعبتك مهلة Timeout أقصر من ذلك، ورسالة واضحة للاعب، وأعد المحاولة بعد مدة تكبر في كل مرة. - الدالة التي ترفض في Lua ردت في 4 مللي ثانية: لأن التحقق من التوكن لا يحتاج القاعدة، فهو توقيع يتحقق منه Nakama بمفتاحه، والدالة رفضت قبل أن تقرأ أي شيء.
- الدخول نفسه فشل: لاعب جديد لا يستطيع أن يدخل، ولاعب داخل يستطيع أن يستمر فقط فيما لا يلمس القاعدة.
وبعد إعادة تشغيل القاعدة عاد كل شيء دون أن نعيد تشغيل Nakama، فرجع الحساب والمتصدرون بالرمز 200، ونجح الدخول في 14 مللي ثانية، لأن Nakama يفتح اتصالات جديدة بالقاعدة عند الحاجة. ولاحظ أن التوكن الذي حفظناه قبل التوقف كان قد انتهى عندما عادت القاعدة، فرجع 401، لأن التوقف ومعه بدء الـ Containers على جهاز مشترك أخذ أكثر من 60 ثانية، وهذا ما سيحدث للاعبيك أيضاً بعد أي انقطاع طويل، فيجب أن تجدد اللعبة الجلسة بتوكن التجديد قبل أن تعرض للاعب أي خطأ.
في منتصف الجولة: خطأ واحد في match_loop أضاع الجولة
أوقفنا القاعدة بعد ثلاث ثوان من بداية جولة بين لاعبين. والجولة نفسها لا تحتاج القاعدة، فالحالة في ذاكرة المباراة، فاستمر اللعب طبيعياً حتى الخطوة 100، حيث يكتب السيرفر الدرجات في المتصدرين. وفي النسخة الأولى من harvest.lua، دون pcall، كان هذا ما سجله Nakama:
{"level":"error","caller":"server/core_leaderboard.go:533","msg":"Error writing leaderboard record","mid":"a2ffb1d8-d03c-4e2f-8679-7ba2747d9628","error":"failed to connect to `user=postgres database=nakama`:\n\thostname resolving error: lookup gm3-nk-pg on 127.0.0.11:53: no such host ..."}
{"level":"warn","caller":"server/match_handler.go:292","msg":"Stopping match after error from match_loop execution","mid":"a2ffb1d8-d03c-4e2f-8679-7ba2747d9628","tick":100,"error":"/nakama/data/modules/harvest.lua:63: error writing leaderboard record: failed to connect to ..."}ومن جهة اللاعبين:
[ 27268 ms] farmer_y: socket closed by the server
[ 29525 ms] farmer_x: socket closed by the serverالخطأ في leaderboard_record_write خرج من match_loop دون أن يمسكه أحد، فأوقف Nakama المباراة عند الخطوة 100، ولم يصل للاعبين أي رسالة نهاية، وأغلقت قناتاهما بعد ثوان، وضاعت درجتا الجولة كاملة. والمشكلة هنا ليست في القاعدة، فالقواعد تتوقف أحياناً، وإنما في أن خطأ في سطر واحد يوقف المباراة كلها. والإصلاح أن تحمي كل استدعاء يلمس القاعدة داخل المباراة بـ pcall، وأن تحفظ ما لم يكتب لتعيد كتابته، وهذا ما فعلته النسخة الثانية:
2026-11-18T14:08:46.406Z Error writing leaderboard record
2026-11-18T14:08:46.406Z score not saved, keep it for a retry: 771ed1d4-05e4-4cc5-b4d6-5eb1fe5855c1 29
2026-11-18T14:08:50.374Z round over: {"farmer_x":{"refused":0,"saved":false,"score":29,"sent":29},"farmer_y":{"refused":0,"saved":true,"score":29,"sent":29}}انتهت الجولة طبيعياً، وأرسل السيرفر النتيجة، وسجل سطرنا الدرجة التي لم تحفظ ومعرف صاحبها، فتستطيع أن تعيد كتابتها من السجل أو من قائمة تحفظها في ذاكرة السيرفر. ولاحظ أن كتابة اللاعب الثاني رجعت saved: true بعد أربع ثوان من فشل الأول، وتكرر ذلك في تشغيلين، فلا تفترض أن الجولة كلها نجحت أو فشلت معاً، وتعامل مع كل درجة وحدها. وفي لعبة حقيقية ضع الدرجات التي لم تكتب في طابور Queue خارج المباراة يعيد المحاولة، لأن المباراة تنتهي ولا تبقى لتعيد.

ومن لوحة الإدارة تستطيع أن تتحقق من هذا كله دون أي كود: إعدادات المتصدرين كما تراها في الصورة، وسجلات كل لاعب، وكائنات التخزين بصلاحياتها، والمباريات التي تعمل الآن، والدوال المسجلة من كودك في Runtime Modules. وهي مفيدة جداً للمشرف، وخطيرة جداً إذا وصل إليها غيره، لأنها تعدل أي حساب وأي درجة.
Nakama في الإنتاج: ما الذي يتغير؟
المختبر يعمل على جهاز واحد بإعدادات مكشوفة، وقبل أن يلعب عليه أحد تحتاج هذه الخطوات:
- غير كل المفاتيح:
session.encryption_keyوsession.refresh_encryption_keyوruntime.http_keyوconsole.signing_keyوكلمة مرور لوحة الإدارة واسم مستخدمها، بقيم طويلة عشوائية خارج المستودع، والسبب أن من يعرف مفتاح التوقيع يصنع توكن أي لاعب، ومن يعرفhttp_keyيستدعي دوالك RPC من خارج اللعبة. - افتح المنفذ 7350 وحده، وخلف Reverse Proxy مع TLS: اللعبة تتصل بـ HTTPS وWSS، وتذكر أن الـ Proxy يجب أن يمرر ترقية WebSocket وأن يطيل مهلة الصمت، كما رأينا في مقال التواصل اللحظي. ولوحة الإدارة 7351 لا تفتحها للإنترنت أبداً، وإنما ادخلها عبر VPN أو نفق SSH.
- اجعل مدة التوكن مناسبة للعبتك: ضعفي أو ثلاثة أضعاف متوسط جلسة اللعب كما ينصح التوثيق، وتوكن تجديد بين يوم وثلاثين يوماً.
- انسخ القاعدة احتياطياً واختبر الاستعادة: كل الحسابات والحفظ والمتصدرين في PostgreSQL، وNakama لا يحفظ بيانات اللاعبين في أي مكان آخر، فالنسخة الاحتياطية للقاعدة هي النسخة الاحتياطية للعبة كلها، وشرحنا الطريقة المتسقة في مقال نسخ قواعد البيانات.
- ثبت الإصدار وحدث عن علم: اكتب الإصدار الكامل في الـ Image، مثل
3.42.0، واقرأ ملاحظات كل إصدار قبل الترقية، لأنmigrate upيغير القاعدة عند التشغيل، ولا رجوع عنه إلا من نسخة احتياطية. - راقب السجلات: أسطر
rejected scoreوscore not savedالتي يكتبها كودك، وأسطر الأخطاء من Nakama نفسه، لأن رسائل الأخطاء التي تصل للاعب مقتضبة عن قصد كما رأينا.
وأما التوسع، فسيرفر Nakama واحد مع قاعدة بيانات جيدة يكفي عدداً كبيراً من اللاعبين كما تشير أرقام المختبر، والمباريات التي يملكها السيرفر تعيش في ذاكرة السيرفر الذي أنشأها. وتشغيل أكثر من سيرفر Nakama معاً في عنقود Cluster يتبادل الحالة ميزة في النسخة التجارية، وتذكر صفحة الإعدادات أن إعدادات العنقود للنسخة Enterprise وحدها. فإذا وصلت لعبتك إلى حد سيرفر واحد، فهذا وقت أن تقرأ عروض Heroic Labs أو تقسم اللاعبين على أكثر من نشر مستقل بحسب المنطقة.
أخطاء شائعة Common Mistakes
- متصدرون ليسوا authoritative: أي لاعب مسجل يكتب فيهم أي رقم. أنشئهم بـ
authoritative = trueواكتب الدرجة من السيرفر فقط. - الثقة في درجة ترسلها اللعبة: حتى مع فحص RPC، قبلنا 120 وهي كذبة. احسب الدرجة في المباراة من أفعال اللاعب.
- بيانات السيرفر تحت معرف اللاعب: اللاعب يستطيع أن ينشئ الكائن قبلك. احفظها تحت مستخدم النظام بالمعرف الصفري.
- تغيير إعدادات المتصدرين في الكود وانتظار أثرها:
leaderboard_createلا يغير متصدرين موجودين ولا يرجع خطأ. أنشئ متصدرين جدداً بمعرف جديد. - نسيان
enableRanks: قائمة الأوائل تبدو سليمة، وقائمة «حول اللاعب» دون ترتيب، والدالة ترجعrank 0. - الكتابة دون إصدار: جهاز قديم يمسح تقدم جهاز أحدث دون أي خطأ. أرسل الإصدار الذي قرأته.
- مباراة تنتظر إلى الأبد: لاعب ينقطع قبل البداية فيبقى الآخر في مباراة لا تبدأ. ضع حداً للانتظار.
- خطأ غير محمي في
match_loop: أي خطأ فيها يوقف المباراة كلها ويضيع الجولة. احم الاستدعاءات التي تلمس القاعدة بـpcall. - الدخول بالبريد في كل جولة: أكثر من ثانية من المعالج لكل دخول. ادخل مرة، ثم جدد بتوكن التجديد.
- المفاتيح الافتراضية في الإنتاج: Nakama يحذرك منها في كل تشغيل، فاقرأ أول عشرين سطراً من السجل.
قائمة فحص قبل الإطلاق Checklist
| البند | كيف تتحقق | لماذا |
|---|---|---|
| المفاتيح الخمسة مغيرة | لا يظهر insecure default parameter في سجل التشغيل | مفتاح التوقيع يصنع أي توكن |
| المنفذ 7351 مغلق من الخارج | اتصل به من جهاز خارج الشبكة فيفشل | لوحة الإدارة تقرأ وتعدل كل شيء |
| TLS أمام 7350 | اللعبة تتصل بـ https وwss | التوكن يرسل مع كل طلب |
| كل المتصدرين authoritative | كتابة مباشرة من العميل ترجع 403 | وإلا كتب أي لاعب أي رقم |
| الدرجة يحسبها السيرفر | لا توجد دالة تقبل الدرجة من العميل، أو لها سقف وسجل | الفحص يحدد الكذبة ولا يمنعها |
| الحفظ بالإصدار | كتابة بإصدار قديم ترجع الرمز 9 | جهازان للاعب نفسه |
| مدة التوكن والتجديد | العميل يجدد قبل exp | لا يخرج اللاعب في منتصف الجولة |
| نسخة احتياطية مختبرة | استعادة على قاعدة فارغة ثم دخول لاعب قديم | كل اللعبة في القاعدة |
| حدود الانتظار والأخطاء في المباريات | لاعب ينقطع قبل البداية، وقاعدة تتوقف أثناء الجولة | المباراة لا تعلق ولا تضيع |
جدول قرار: أين تضع كل منطق؟ Decision Table
| ما تريده | أين تضعه | السبب |
|---|---|---|
| الدخول والحسابات | طرق Nakama الجاهزة: الجهاز أولاً ثم الربط | هاش كلمات المرور والتوكن والتجديد جاهزة ومختبرة |
| الحفظ والإعدادات | التخزين بصلاحية 1 وبالإصدار | يملكه اللاعب، ولا يمسح جهاز قديم جهازاً أحدث |
| الملف العام للاعب | التخزين بصلاحية قراءة 2 | يقرؤه الجميع ولا يكتبه إلا صاحبه |
| بيانات يعتمد عليها السيرفر | التخزين تحت مستخدم النظام بصلاحية 0 | لا يستطيع اللاعب أن ينشئها أو يغيرها |
| درجات الجولات القصيرة | مباراة يملكها السيرفر تكتب الدرجة | اللاعب يرسل أفعالاً، والسيرفر يعد |
| درجات لا تستطيع حسابها في السيرفر | دالة RPC بسقف وحد زمني وسجل | تحدد الكذبة وتكشف من يحاول |
| لعبة سريعة بستين خطوة في الثانية | سيرفر لعب مخصص، وNakama للحسابات والمطابقة | حلقة المباراة في Nakama تناسب الجولات لا التصويب السريع |
| لعب تعاوني بين أصدقاء | المباراة الممررة Relayed | لا يهم الغش، والسيرفر أخف |
تطبيق عملي Practice
- غير
COOLDOWN_TICKSفيharvest.luaمن 3 إلى 4، وشغل الجولة نفسها، وانظر هل بقي الغشاش متقدماً على اللاعب الصادق الذي يقطف كل 350 مللي ثانية، وكم قطفة صادقة رفضت. - أضف إلى
submit_scoreكتابة الكائن بالإصدار الذي قرأته، ثم أرسل طلبين في اللحظة نفسها من اللاعب نفسه، وتأكد أن واحداً فقط ينجح. - أنشئ متصدرين يوميين بالعامل
incrيجمعون كل التمر الذي قطفه اللاعب في اليوم، واكتب فيهم منmatch_loopبجانب المتصدرين الأسبوعيين. - غير
session.token_expiry_secإلى 7200، وأضف إلىbot.gdتجديد التوكن عندما ترجعsession.would_expire_in(300)القيمة true. - شغل
bash load.sh 800وقارن المعالج وزمن المطابقة ونسبة القطفات المرفوضة بأرقام 400 لاعب.
ملفات المختبر Lab Files وتشغيله
المختبر في مجلد lab، وفيه:
up.shوdown.sh: تشغيل PostgreSQL وNakama على الشبكةgm3-nk-net، وحذف كل شيء.nakama/local.yml: الإعدادات، وnakama/modules-v1النسخة الأولى من كود السيرفر، وnakama/modulesالنسخة المصححة.rest_tour.py: طلبات REST بأقسامهاauthوstorageوleaderboardوaroundوexpiryوtiming.client: مشروع Godot 4.7.2 فيهmain.gdوbot.gd، والمكتبة nakama-godot 3.4.0 ينزلهاrun.shإلىclient/addons.Dockerfile: Godot 4.7.2 الرسمي بعد التحقق من SHA512، دون شاشة.load.shوdbdown.shوdbdown.py: تجربة الضغط وتجربة توقف القاعدة.console-shot.mjs: صورة لوحة الإدارة الحقيقية في الشكل الأخير.run.sh: كل الخطوات بترتيب المقال، وكل خطوة تكتب ملفout-*.txt.
وتشغله بعد بناء الـ Image من مجلد lab:
docker pull heroiclabs/nakama:3.42.0 && docker tag heroiclabs/nakama:3.42.0 gm3-nk-nakama:3.42.0
docker pull postgres:16-alpine && docker tag postgres:16-alpine gm3-nk-postgres:16-alpine
docker pull python:3.13-alpine && docker tag python:3.13-alpine gm3-nk-python:3.13-alpine
docker build -t gm3-nk-godot:4.7.2 .
bash run.shويأخذ التشغيل كاملاً قرابة عشر دقائق، أطولها انتظار انتهاء التوكن وجولات الضغط. ولا تعدل أي ملف .sh أثناء تشغيله، لأن Bash يقرأ السكربت سطراً بعد سطر من القرص، فإذا تغير الملف في منتصف التشغيل نفذ نصف سطر وتوقف بخطأ صياغة Syntax Error.
حذف المختبر Cleanup
bash down.sh
docker image rm gm3-nk-nakama:3.42.0 gm3-nk-postgres:16-alpine gm3-nk-python:3.13-alpine gm3-nk-godot:4.7.2
rm -rf client/.godot client/addons out-*.txt out-*.logالخلاصة Summary
- الخلفية Game Backend تملك الحسابات والحفظ والمتصدرين والمطابقة، وتقرر ما يقبل، والسيرفر المخصص يملك الجولة السريعة، وكثير من الألعاب تحتاج الاثنين.
- Nakama 3.42 برنامج واحد مع PostgreSQL، بدأ بـ 36 ميجابايت من الذاكرة، ووصل إلى 210 ميجابايت وأكثر من نواة مع 400 لاعب في جولات متزامنة.
- الدخول بالجهاز أخذ 4 مللي ثانية، وبالبريد 1,169 مللي ثانية بسبب bcrypt، والتوكن يعيش 60 ثانية افتراضياً ويجدد في 11 مللي ثانية.
- التخزين بالإصدار رفض كتابة الجهاز القديم بالرمز 9، والمجموعة مجرد اسم، فبيانات السيرفر تحفظ تحت مستخدم النظام.
- المتصدرون authoritative رفضوا الكتابة المباشرة بـ 403، ودالة RPC رفضت 5,000 وقبلت 120، والترتيب يحتاج
enableRanks، والإعدادات لا تتغير بعد الإنشاء. - في المباراة التي يملكها السيرفر أرسل الغشاش 182 رسالة وعد السيرفر 34، ولكنه بقي متقدماً على الصادق، ومع 400 لاعب رفض الحد 34 قطفة صادقة، فالحد قرار بين الغش والظلم.
- الحدود الموجودة في الإعدادات على الموارد لا على عدد الطلبات: ثلاث تذاكر لكل جلسة، ورسالة 4,096 بايت تغلق القناة كلها.
- عندما توقفت القاعدة، بقيت الطلبات معلقة ثوان ثم فشلت، وخطأ واحد غير محمي في
match_loopكان كافياً ليضيع الجولة.
وبعد الخلفية تبقى في هذه المرحلة الشبكات التي تنقل حركة اللاعبين لحظة بلحظة، وتشغيل سيرفرات اللعب المخصصة، ومكافحة الغش:
دليلاللعب الجماعي Multiplayer: السيرفر صاحب القرار والتأخيرنبني في Godot 4 سيرفراً مخصصاً صاحب قرار وكلاينتات آلية، ثم نضيف التأخير والارتعاش والفقدان ونقيس كيف يخفي التنبؤ والمطابقة والاستيفاء أثرها عن اللاعب.
دليلخوادم الألعاب المخصصة Dedicated Servers على سيرفركنصدر سيرفر لعبة Godot بقالب التصدير ونغلفه في Docker، ونقيسه مع 64 لاعباً آلياً، ونجعله يحفظ ويفرغ مبارياته عند الإيقاف ونحدثه دون طرد أحد، ثم نقارنه بسيرفر Luanti ونعرف متى تحتاج Agones.
دليلمكافحة الغش Anti-Cheat في الألعاب: ما يمكن وما لا يمكننكتب كلاينتات تغش في لعبتنا الجماعية بأبسط الطرق، ونوقف كل غش منها بفحص على السيرفر ونقيس أثره على اللاعب الأمين، ثم نشرح ما لا يراه السيرفر وثمن مكافحة الغش في النواة.
دليلأول لعبة مع Godot: المشاهد والعقد وGDScriptنبني لعبة صغيرة كاملة في Godot 4 من ثلاثة مشاهد وأربعة سكربتات، ونفهم بها العقد والمشاهد والإشارات وحلقة اللعبة، ثم نشغلها في مختبر يلعبها فيه روبوت حتى تنتهي.
دليلتصدير اللعبة من Godot إلى الويب والجوال وسطح المكتبماذا يحدث فعلاً عند تصدير لعبة Godot، ولماذا تحتاج نسخة الويب Headers خاصة أحياناً، وما تطلبه كل منصة ومتجر، مع مختبر يصدر لعبة واحدة إلى خمس منصات.سجل التحديثات Changelog
- 18 نوفمبر 2026: كتابة المقال، وتشغيل Nakama 3.42.0 مع PostgreSQL 16 في Docker، وعملاء Godot 4.7.2 بالمكتبة nakama-godot 3.4.0، وقياس الطلبات و400 لاعب متزامن وتوقف قاعدة البيانات.