بيان caputchin.json

‏caputchin.json في جذر مستودعك هو مصدر حقيقة المؤلّف والمفهرِس للعبة المتجر. يقرؤه المفهرِس على الخادم ليعرف هويّة اللعبة، وأين تقيم حزمتها، وأيّ تهيئات تقدّم، وكيف يعيد تشغيلها. لا يُقرَأ في المتصفّح أبدًا؛ الـ SDK لا يحمّله وقت التشغيل.

هذه الصفحة مرجع الحقول. للبناء، انظر ابنِ لعبة المتجر؛ وللنشر، انظر انشر إلى المتجر. الأنواع الدقيقة مُصدَّرة من الـ SDK كـ GameManifest (انظر مرجع الـ SDK).

لعبة واحدة دنيا

{
  "terms_accepted": true,
  "license": "MIT",
  "marketplace": {
    "name": "Leaf Memory",
    "description": "Match pairs of tropical leaves before the timer runs out.",
    "preview": "preview.png"
  },
  "npm": "@your-org/leaf-memory",
  "entry": "dist/leaf-memory.js"
}

الحقول الأعلى

لا حقل version: يثبّت المفهرِس الحزمة على مرجع غير قابل للتغيير بنفسه (نسخة npm المنشورة أو SHA الالتزام المحلول).

كتلة marketplace

الكتلة اختيارية بالكامل. احذف name / url وتعرض صفحة التفاصيل ببساطة لا نسبة مؤلّف (مالك GitHub المعروض في مكان آخر على الصفحة هوية منفصلة حاضرة دائمًا، لا ارتداد لهذه النسبة). احذف email فلا تستقبل إشعارات إخفاق نشر. اضبط الحقول الفرعية التي تريدها فقط.

مؤشّرات التوزيع

يثبّت المفهرِس حزمة كل لعبة على مرجع غير قابل للتغيير كي تبقى تجزئة السلامة المخزَّنة صالحة، ويعيد الحلّ في كل تشغيل (cron يوميّ إضافةً إلى "انشر أو حدّث" يدويًّا):

• entry + npm يُحلّان إلى cdn.jsdelivr.net/npm/<npm>@<resolved-version>/<entry>.
• entry وحده يُحلّ إلى cdn.jsdelivr.net/gh/<owner>/<repo>@<commit-sha>/<entry>.
• npm وحده يُحلّ إلى مدخل الحزمة الافتراضي عند النسخة المثبَّتة.

لا تثبيت نسخة من جانب المستخدم؛ لتجميد بناء، يستضيفه مستخدم ذاتيًّا عبر game-src الخاص بالأداة (لعبة مخصّصة).

أداة run

افتراضيًّا يشغّل الفحص الذاتي لإعادة التشغيل حزمة entry الحيّة خاصتك. حين تكون لعبتك كبيرةً أو قائمةً على إطار عمل أو WASM، اشحن أداة run بلا واجهة مخصّصة هزيلة بدلًا:

{
  "run": {
    "entry": "dist/run.js",
    "modules": [
      { "name": "sim.wasm", "type": "wasm", "path": "dist/sim.wasm" }
    ]
  }
}

القيود التي يفرضها المفهرِس

تُتحقَّق وقت الفهرسة؛ ومخالفة تفشّل النشر بـ manifest-error (انظر مرجع أخطاء النشر).

run.entry:

• يجب أن يكون JavaScript: يجب أن يطابق الاسم الأساسي [a-zA-Z0-9_-]+.js. أداة run دائمًا JS (يُشحَن WASM كوحدة، أدناه).
• يجب أن يكون مسارًا نسبيًّا نظيفًا للمستودع: لا شرطة مائلة بادئة، ولا اجتياز ..، ولا فراغ، ولا ? / #، ولا بادئة scheme://.

كل مدخل run.modules[] هو { name, type, path }:

• name يجب أن يطابق [a-zA-Z0-9_-]+.(wasm|js)، الوحدة إمّا JS أو WASM، لا شيء آخر. الـ name هو محدّد الاستيراد الذي يستخدمه المدخل.
• type يجب أن يتّفق مع الامتداد: wasm لاسم .wasm، وjs لاسم .js.
• name يجب ألّا يكون اسمًا محجوزًا (entry.js، وartifact.js) يستخدمه مضيف إعادة التشغيل داخليًّا.
• name يجب أن يكون فريدًا داخل المصفوفة (لا تكرار).
• path يجب أن يكون مسارًا نسبيًّا نظيفًا للمستودع (القواعد نفسها كـ run.entry).
• 16 وحدة على الأكثر.

احذف run لإعادة تشغيل entry الحيّة مباشرةً. انظر عقد إعادة التشغيل لما يجب أن تصدّره الأداة.

كتلة preferred

كتلة preferred الاختيارية تحمل تلميحات عرض. كل مفتاح استشاريّ: يحقّ للمضيف احترامه، ولا يتجاوز أبدًا سمة تضمين صريحة.

{
  "preferred": { "width": 360, "height": 480, "layout": "modal" }
}

لعبة متجاوبة ينبغي أن تمتدّ عبر حاويتها افتراضيًّا تستطيع إعلان "full" على أيّ محور:

{
  "preferred": { "width": "full", "height": 480 }
}

تُحترَم هذه التلميحات فقط للألعاب التي تحلّها المنصّة على الخادم (ألعاب المتجر، أو معرّف لعبة مُعطًى بلا مفتاح موقع). حزمة game-src مستضافة ذاتيًّا لا تستطيع المنصّة قراءتها قبل التركيب تتجاهل البصمة وتلميح التخطيط معًا.

كتل التهيئات

locales، وskins، وconfigurations كلٌّ يعلن schema اختياريًّا (أنواع لكل مفتاح وتوثيق) إضافةً إلى presets (بنوك الخيارات المسمّاة). تحلّ الأداة خيار الزائر مقابلها وتسلّم لعبتك النتيجة المسطّحة كـ ctx. كتالوج أنواع الحقول الكامل هو مرجع مخطّط التخصيص المشترك؛ الأنواع نفسها تقود مخطّط لوحة التحكّم للعبة مخصّصة.

حقل skins.schema قد يكون color، أو أصلًا (image / audio / video)، أو قياسيًّا (boolean، وnumber، وrange، وlist) مستخدمًا أشكال القيد نفسها كـ configurations ({ "type": "range", "min": 0, "max": 24 }، و["dots","stripes"]، وهكذا). قيم المظهر القياسية تُحلّ إلى قيمتها المكتوبة النوع في ctx.skin (الـ number عدد حقيقي)، تمامًا كقيمة إعداد؛ وقيم اللون والأصل تُحلّ إلى نصوص.

‏_theme تهيئة مظهر يعلن الوضع الذي تعمل فيه: light، أو dark، أو any (حذفه يعني any). تهيئة light أو dark تظهر في ذلك الوضع فقط؛ وتهيئة any تُقرَأ على أيّ خلفية ومؤهَّلة لكليهما. هناك افتراضي واحد لكل وضع. تهيئة موسومة _default: true هي الافتراضية للوضع/الأوضاع التي هي مؤهَّلة لها، فافتراضي any يغطّي كليهما؛ وحين تُوسَم عدّة تهيئات مؤهَّلة افتراضيةً لوضع، تفوز به الأولى بترتيب الإعلان. ضع تهيئةً خاصةً بوضع فوق تهيئة any لإعطاء ذلك الوضع مظهرًا مخصّصًا بينما تسقط تهيئة any إلى الآخر.

ملفّات .caputchin/ المقسّمة

كتل التهيئات (خصوصًا مجموعات اللغات الكاملة) تجعل caputchin.json طويلًا. انقل أي محور إلى ملفّه الخاص تحت مجلّد .caputchin/، تاركًا البيان قصيرًا:

caputchin.json
.caputchin/locales.json
.caputchin/skins.json
.caputchin/configurations.json

الكائن الأعلى لكل ملفّ هو كتلة ذلك المحور ({ schema?, presets }). الثلاثة اختيارية. الأسبقية استبدال للمحور كله، caputchin.json يفوز: إن أُعلِن محور مضمَّنًا وكملفّ معًا، تُستخدَم الكتلة المضمَّنة ويُتجاهَل الملفّ (النشر ينبّه كي تعرف أنه ميّت). أبقِ كل محور في مكان واحد بالضبط.

المجموعات

يستطيع مستودع شحن عدّة ألعاب. غلاف مجموعة يعلن مسارات أبناء بدل entry / npm:

{
  "marketplace": { "name": "Caputchin Core Pack", "description": "The official pack." },
  "games": ["./packages/leaf-memory", "./packages/dino-runner"]
}

كل مسار يشير إلى مجلّد ابن يحمل caputchin.json الخاص. معرّفات الأبناء هي owner/repo/<leaf-dir>. احذف كتلة marketplace للغلاف لفهرسة الأبناء بلا صفحة مجموعة.

انظر أيضًا

• ابنِ لعبة المتجر: إنتاج الحزمة التي يشير إليها هذا البيان.
• عقد إعادة التشغيل: ما يجب أن تصدّره أداة run.
• مرجع أخطاء النشر: كل خطأ تحقّق بيان وقائمة الرخص الموافَق عليها.
• مرجع مخطّط التخصيص: أنواع الحقول التي تستخدمها كتل التهيئات.