دليل خادم الأصول ثلاثية الأبعاد: قلّب، قارن، ونزّل أصول الألعاب من 18 مصدر

شنو كيدير 3d-asset-server

3d-asset-server كيوفّر خانة بحث وحدة للموديلات ثلاثية الأبعاد، والمواد، والتكسشرات، وHDRIs، والـ sprites، وموارد واجهة المستخدم، والصوت، والخطوط، وحزم موارد الألعاب. كيقلب فـ 18 مزوّد، كيدمج النتائج وكيرتّبها، كيعرض حالة كل مصدر، وكينزّل الموارد إلا كان المزوّد كيسمح بالتنزيل المباشر.

تقدر تستعمل المشروع من المتصفح، باستعمال curl، عبر واجهة سطر الأوامر، ولا من مساعد ذكي مربوط عبر Model Context Protocol (MCP). النتائج فيها معلومات الرخصة، وحالة الثمن، ومتطلبات نسب المصدر، والصيغ، والدقة، وروابط المزوّدين.

كيفاش كخدم البحث

مع كل استعلام، السيرفر كيختار المزوّدين المناسبين وكيفتش فيهم بالتوازي. كل مزوّد عندو مهلة زمنية خاصة به، وبهذا الموقع البطيء ولا غير المتاح ما كيمنعش ظهور النتائج من المصادر الأخرى.

النتائج كترتّب باستعمال مدى ملاءمة النص، والترتيب ديال المزوّد، واش النتيجة جاية من API ولا من scraper، والتوفّر المجاني، ودعم التنزيل المباشر، وتنوّع المصادر. الاستجابة كتضم حتى تقرير لكل مزوّد بحالات بحال ok وerror وtimeout وskipped ولا link.

شي مزوّدين كيدعمو التنزيل المباشر. Poly Haven وambientCG وKenney وTextureCan والموارد المجانية من BlenderKit أمثلة على هاد الشي. مزوّدين آخرين كيرجعو البيانات الوصفية كاملة ورابط صفحة المورد، بينما Fab وPoliigon وTurboSquid كيعطيو روابط لصفحات البحث ديالهم ملي كتمنع حماية البوتات البحث الآلي.

المصادر المدعومة

كتضم لائحة المزوّدين مصادر لأنواع مختلفة من المحتوى:

• HDRIs ومواد PBR: Poly Haven وambientCG وHDRMaps وHDRI Hub و3DTexel.
• موارد منخفضة المضلعات وموارد الألعاب: Kenney وQuaternius وFab وitch.io وBlenderKit.
• التكسشرات والمواد الممسوحة: CGBookcase وShareTextures وTextureCan وTextures.com و3DTextures.me.
• الموديلات وأسواق الموارد: BlenderKit وCGTrader وTurboSquid وFab وitch.io.

تفاصيل الرخص كتختلف حسب كل قائمة. مثلا، Poly Haven وambientCG وKenney كيوفرو محتوى برخصة CC0، بينما مزوّدو الأسواق يقدرو يطبّقو رخص خاصة بكل قائمة. ديما راجع معلومات الرخصة ونسب المصدر اللي رجعات قبل ما توزّع أي مورد.

التثبيت والإعداد

المشروع كيتطلب Node.js 20 ولا أحدث. حمّل المستودع، وثبّت الاعتماديات، وبنِ التطبيق:

git clone https://github.com/arielshad/3d-asset-server.git
cd 3d-asset-server
npm install
npm run build

شغّل واجهة الويب وHTTP API ونقطة MCP بهاد الأمر:

npm start

السيرفر المحلي كيتشغّل افتراضيا فـ http://localhost:8787.

الإعداد باستعمال Docker

تقدر حتى تبني وتشغّل السيرفر باستعمال Docker:

docker build -t 3d-asset-server .
docker run -p 8787:8787 3d-asset-server

استعمال واجهة الويب

حلّ http://localhost:8787 من بعد ما تشغّل السيرفر. النسخة المستضافة متوفرة فـ 3d.shep.bot.

استعمل صفحة البحث باش تدخل استعلام، وتختار نوع المورد، وتحصر النتائج فالموارد المجانية، وتشترط التنزيل المباشر، ولا تختار مزوّدين محددين. حالة البحث كتتخزّن فالرابط، وبالتالي استعلام بحال /search?q=sunset&type=hdri&free=true تقدر تديرو فالمفضلة ولا تشاركو.

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

الموقع المستضاف كيوفّر حتى التوثيق، ومرجع OpenAPI، ومعلومات المصادر، وإرشادات الاستضافة الذاتية. الملفات الموجّهة للوكلاء فيها /AGENTS.md و/llms.txt و/llms-full.txt و/openapi.json.

البحث باستعمال HTTP API

نقطة البحث الرئيسية هي GET /v1/search. عطِ استعلاما مع فلاتر اختيارية بحال نوع المورد، والتوفّر المجاني، ودعم التنزيل المباشر، والمزوّدين، وحدّ النتائج، والإزاحة.

curl 'http://localhost:8787/v1/search?q=brick+wall&type=material&free=true&limit=5'

الاستجابة المختصرة فيها النتائج المرتّبة وتقارير المزوّدين:

{
  "query": "brick wall",
  "results": [
    {
      "id": "polyhaven:brick_wall_001",
      "title": "Brick Wall 001",
      "type": "material",
      "license": {
        "name": "CC0",
        "commercialUse": true,
        "attributionRequired": false
      },
      "resolutions": ["1k", "2k", "4k", "8k"],
      "downloadable": true
    }
  ],
  "providers": [
    {
      "provider": "polyhaven",
      "status": "ok",
      "count": 5
    }
  ]
}

استعمل GET /v1/providers باش تجيب كتالوج المزوّدين، وGET /v1/assets/{provider}:{id} باش تجيب التفاصيل الكاملة ديال المورد، وGET /v1/assets/{id}/files باش تفحص الملفات المختارة حسب الصيغة والدقة.

التنزيل عبر API

بالنسبة لملف مستقل، نقطة التنزيل كتحوّل للرابط ديال الملف الأصلي. وبالنسبة للموارد اللي فيها بزاف ديال الملفات، كترسل ملف zip فيه المورد والملفات المرافقة ديالو:

curl -OJ 'http://localhost:8787/v1/assets/polyhaven:WoodenChair_01/download?format=gltf&resolution=1k'

الـ API كيوفّر حتى /health و/openapi.json و/v1/catalog و/v1/stats. الكتالوج كيعطي عدد المزوّدين والموارد، بينما نقطة الإحصائيات كتعرض الاستعمال وصحة المصادر.

استعمال CLI

الـ CLI المبني كيدعم تقديم HTTP، وMCP عبر الإدخال والإخراج القياسيين، والبحث من الطرفية.

node dist/cli.js search "low poly tree" --type model --free --limit 5

النتائج كاتبيّن النقطة، نوع الأصل، واش مجاني، معرّف المزوّد، العنوان، ورابط المصدر. حالات المزوّدين كاتطبع من بعد النتائج باش تشوف شنو المواقع اللي جاوبات وشنو اللي غير وفّرات الروابط.

باش تشغّل الخدمة المحلية كاملة من CLI، استعمل:

3d-asset-server serve

باش تبدا سيرفر MCP عبر الإدخال والإخراج العاديين، استعمل:

3d-asset-server mcp

استعمال MCP مع المساعدين بالذكاء الاصطناعي

MCP كيخلّي المساعد بالذكاء الاصطناعي يقلب على الأصول، يطّلع على التفاصيل ديالها، وينزّل الملفات المسموح بها. الأدوات المتاحة هي:

• search_assets كيقلب عند المزوّدين باستعمال فلاتر البحث، النوع، المزوّد، الرخصة، قابلية التنزيل، وتقسيم الصفحات.
• get_asset كيرجّع الميتاداتا، معلومات الرخصة، الصيغ والدقّات المتاحة، والملفات اللي غادي يجيبها التنزيل المختار.
• download_asset كيحفظ الأصل والملفات المرافقة ديالو فمجلد مُعدّ، وكيفكّ الحزم المضغوطة المدعومة.
• list_providers كيشرح كل مزوّد، أنواع الأصول ديالو، الأثمنة، الرخصة، ودعم التنزيل المباشر.

Claude Code

ضبط Claude Code باش يطلق عملية MCP المحلية ويحفظ الملفات فمجلد الأصول ديال المشروع الحالي:

claude mcp add 3d-assets -e ASSET_DOWNLOAD_DIR="$PWD/assets" -- node /path/to/3d-asset-server/dist/cli.js mcp

Claude Desktop وCursor وزبناء Stdio آخرين

زيد مدخلة ديال السيرفر فإعدادات MCP ديال الزبون:

{
  "mcpServers": {
    "3d-assets": {
      "command": "node",
      "args": ["/path/to/3d-asset-server/dist/cli.js", "mcp"],
      "env": {
        "ASSET_DOWNLOAD_DIR": "/path/to/your/game/assets"
      }
    }
  }
}

MCP عن بُعد

السيرفر المستضاف كيدعم MCP عبر Streamable HTTP:

claude mcp add --transport http 3d-assets https://3d.shep.bot/mcp

إلى كان السيرفر مستضاف عندك، وجّه الزبون لـ http://<host>:8787/mcp. التنزيلات عبر HTTP عن بُعد معطّلة افتراضياً حيث غادي تكتب الملفات فقرص السيرفر. فهاد الوضع، get_asset كيرجّع روابط مباشرة للملفات ورابط zip ديال الحزمة. فعّل ASSET_SERVER_HTTP_DOWNLOADS=true غير إلا كان خاص السيرفر يخزّن الملفات.

فهم التنزيلات

إلى ما تحدداتش الصيغة، السيرفر كيفضّل الصيغ العملية ديال الألعاب والويب. الموديلات كاتفضّل glb، ومن بعد gltf، fbx، obj، وblend. صور HDRI كاتفضّل hdr ومن بعد exr. المواد كاتفضّل خرائط الصور ولا zip، والخامات كاتفضّل jpg، png، zip، ولا exr، والحزم كاتتنزّل كملفات zip مفكوكة.

الدقّة الافتراضية هي أقرب اختيار متاح لـ 2K. الملفات المرافقة كاتحافظ على المسارات النسبية ديالها، وهادشي كيخلّي ملف glTF يلقى الملف الثنائي وملفات الخامات ديالو بلا ما تحتاج ترتّبهم يدوياً.

assets/
└── polyhaven-WoodenChair_01/
    ├── WoodenChair_01_2k.gltf
    ├── WoodenChair_01.bin
    └── textures/
        ├── WoodenChair_01_diff_2k.jpg
        ├── WoodenChair_01_nor_gl_2k.jpg
        └── WoodenChair_01_arm_2k.jpg

أداة التنزيل كاتجيب غير الروابط العمومية ديال http وhttps، كاترفض العناوين الخاصة وعناوين loopback، كاتفرض حدّ حجم قابل للضبط، وكاترفض مسارات الأرشيف غير الآمنة بحال ../. وما كاتتجاوزش صفحات تسجيل الدخول، مراحل الأداء، ولا حماية hotlink.

الإعدادات

عيّن متغيّرات البيئة قبل ما تبدا السيرفر باش تتحكم فالعنوان الشبكي، المزوّدين، التنزيلات، الأمان، والأداء.

• PORT وHOST كيتحكمو فعنوان ربط HTTP. القيم الافتراضية ديالهم هي 8787 و0.0.0.0.
• ASSET_SERVER_PROVIDERS كيقبل لائحة مفصولة بفواصل بحال polyhaven,ambientcg,kenney.
• ASSET_DOWNLOAD_DIR كيبدّل مجلد تنزيل MCP الافتراضي من ./assets.
• ASSET_SERVER_MAX_DOWNLOAD_BYTES كيحدّد الحراسة ديال حجم كل تنزيل، والقيمة الافتراضية هي 2 GiB.
• ASSET_SERVER_PROVIDER_TIMEOUT_MS وASSET_SERVER_HTTP_TIMEOUT_MS كيعدّلو مهلات المزوّدين وHTTP.
• ASSET_SERVER_CACHE_TTL_MS كيتحكم فمدة صلاحية ذاكرة HTTP المؤقتة.
• BLENDERKIT_API_KEY يقدر يفتح أصول BlenderKit ديال الخطط والمقتناة.
• NODE_USE_ENV_PROXY=1 كيخلّي Node يستعمل HTTPS_PROXY المهيّأ.

المصادقة وحدود المعدّل

عيّن ASSET_SERVER_API_KEY باش تحمي /v1/* و/mcp. يقدرو الزبناء يرسلو المفتاح كرمز Bearer، ولا فـ header ديال x-api-key، ولا كمعامل استعلام api_key. ردّ بالك من معاملات الاستعلام حيث يقدرو يبانُو فتاريخ المتصفح وسجلات السيرفر.

تحديد المعدّل مفعّل افتراضياً بـ 120 طلب لكل زبون فنافذة ديال 60 ثانية. ضبط ASSET_SERVER_RATE_LIMIT وASSET_SERVER_RATE_LIMIT_WINDOW، ولا عيّن الحد على 0 باش تعطل هاد الخاصية.

استكشاف مشاكل البروكسي والمزوّدين

CGTrader يقدر يحظر عناوين IP ديال السحابة ومراكز البيانات. غالباً كيخدم من اتصال منزلي؛ فالسيرفر، ضبط بروكسي وعيّن NODE_USE_ENV_PROXY=1. المزوّدين اللي كيتجمع منهم المحتوى يقدرو حتى هما يبدلو HTML ديالهم. إلا تعطل واحد، المصادر الأخرى كاتواصل ترجع النتائج، وnpm run test:live يقدر يفحص توفّر المزوّدين.

المراقبة المتقدمة

عيّن METRICS_PORT باش تخرّج مقاييس Prometheus فـ بورت مستقل. السيرفر كيسجّل مقاييس بعلامات محدودة لعمليات البحث، وطلبات المزوّدين، والتنزيلات، ومشاهدات الأصول، واستدعاءات أدوات MCP، وطلبات HTTP، ومشاهدات الصفحات. وكيسجّل حتى أحداث البحث بشكل منظّم بلا ما يسجّل عناوين IP ولا المفاتيح ولا ملفات تعريف الارتباط.

إلى كان PROMETHEUS_URL مكوّن، يقدر endpoint ديال الإحصائيات يبلّغ على بيانات مجمّعة عبر النسخ المتعددة. إلا ما كانش مكوّن، فالإحصائيات كتمثّل العملية الحالية من آخر إعادة تشغيل ديالها.

طريقة العمل الموصى بها

1. قلّب بشكل واسع باستعمال طلب وصفي بحال sunset أو low poly tree أو brick wall.
2. صفّي النتائج حسب نوع الأصل، أو واش مجاني، أو واش متاح التنزيل المباشر، أو حسب المزوّدين المختارين.
3. عاين الرخصة، ومتطلبات نسب المصدر، والصيغ، والدقّات، ولائحة الملفات.
4. اختار الصيغة والدقّة المناسبتين للعبة ديالك أو للموقع ديالك.
5. نزّل الأصل أو نسخ الرابط ديال المصدر إلا كان المزوّد ما كيسمحش بالتنزيل المباشر.
6. خلّي أي ملفات ديال نسب المصدر والرخصة المطلوبة مع المشروع ديالك.

الخلاصة

3d-asset-server كيحوّل البحث المتفرّق على الأصول لسيرورة عمل وحدة. الواجهة ديالو على الويب، وواجهة HTTP البرمجية، وCLI، وأدوات MCP كيسمحوا ليك تقلّب فعدد كبير ديال المزوّدين، وتقارن معلومات الرخص والتنزيل، وتجيب نماذج، وخامات، وHDRIs، وحزم واجدة للاستعمال. بدا محلياً باستعمال Node.js أو Docker، ومن بعد كوّن المزوّدين، والمصادقة، ومسارات التنزيل، وحدود المعدّل، والمراقبة فالنشر الإنتاجي.