3D Asset Server qo‘llanmasi: 18 ta manbadan o‘yin assetlarini qidiring, solishtiring va yuklab oling

3d-asset-server nima qiladi

3d-asset-server 3D modellar, materiallar, teksturalar, HDRI'lar, spritlar, UI aktivlari, audio, shriftlar va o'yin aktivlari to'plamlarini qidirish uchun yagona qidiruv maydonini taqdim etadi. U 18 ta provayderni qidiradi, natijalarni birlashtiradi va saralaydi, har bir manba holatini ko'rsatadi hamda provayder to'g'ridan-to'g'ri yuklab olishga ruxsat berganda aktivlarni yuklab oladi.

Loyihadan brauzer orqali, curl yordamida, buyruq qatori interfeysi orqali yoki Model Context Protocol (MCP) orqali ulangan AI yordamchisidan foydalanishingiz mumkin. Natijalar litsenziya ma'lumotlari, narx holati, atributsiya talablari, formatlar, ruxsatlar va provayder havolalarini o'z ichiga oladi.

Qidiruvlar qanday ishlaydi

Har bir so'rov uchun server tegishli provayderlarni tanlaydi va ularni parallel ravishda qidiradi. Har bir provayderning o'z vaqt chegarasi mavjud, shuning uchun sekin ishlayotgan yoki mavjud bo'lmagan sayt boshqa manbalardan natijalar chiqishiga xalaqit bermaydi.

Natijalar matnning mosligi, provayder reytingi, natija API yoki skreper orqali olingani, bepul mavjudligi, to'g'ridan-to'g'ri yuklab olishni qo'llab-quvvatlashi va manbalar xilma-xilligi asosida saralanadi. Javob shuningdek ok, error, timeout, skipped yoki link kabi holatlar bilan har bir provayder bo'yicha hisobotni ham o'z ichiga oladi.

Ayrim provayderlar to'g'ridan-to'g'ri yuklab olishni qo'llab-quvvatlaydi. Poly Haven, ambientCG, Kenney, TextureCan va BlenderKit'dagi bepul aktivlar bunga misol bo'ladi. Boshqa provayderlar to'liq metama'lumotlar va aktiv sahifasiga havola qaytaradi, Fab, Poliigon va TurboSquid esa bot himoyasi avtomatik qidiruvga to'sqinlik qilganda o'z qidiruv sahifalariga havolalar taqdim etadi.

Qo'llab-quvvatlanadigan manbalar

Provayderlar katalogi turli xil kontentlar uchun manbalarni o'z ichiga oladi:

• HDRI'lar va PBR materiallari: Poly Haven, ambientCG, HDRMaps, HDRI Hub va 3DTexel.
• Low-poly va o'yin aktivlari: Kenney, Quaternius, Fab, itch.io va BlenderKit.
• Teksturalar va skanerlangan materiallar: CGBookcase, ShareTextures, TextureCan, Textures.com va 3DTextures.me.
• Modellar va aktivlar marketpleyslari: BlenderKit, CGTrader, TurboSquid, Fab va itch.io.

Litsenziya tafsilotlari ro'yxatga qarab farq qiladi. Masalan, Poly Haven, ambientCG va Kenney CC0 kontentini taklif qiladi, marketpleys provayderlari esa ro'yxatga xos litsenziyalarni qo'llashi mumkin. Aktivni tarqatishdan oldin qaytarilgan litsenziya va atributsiya ma'lumotlarini har doim tekshiring.

O'rnatish va sozlash

Loyiha Node.js 20 yoki undan yangiroq versiyasini talab qiladi. Repozitoriyni klonlang, bog'liqliklarni o'rnating va ilovani yig'ing:

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

Veb UI, HTTP API va MCP endpointini quyidagi buyruq bilan ishga tushiring:

npm start

Mahalliy server sukut bo'yicha http://localhost:8787 manzilida ishlaydi.

Docker sozlamalari

Serverni Docker yordamida ham yig'ish va ishga tushirish mumkin:

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

Veb UI'dan foydalanish

Serverni ishga tushirgandan so'ng http://localhost:8787 manzilini oching. Joylashtirilgan versiya 3d.shep.bot manzilida mavjud.

Qidiruv sahifasidan so'rov kiriting, aktiv turini tanlang, natijalarni bepul aktivlar bilan cheklang, to'g'ridan-to'g'ri yuklab olishni talab qiling yoki muayyan provayderlarni tanlang. Qidiruv holati URL manzilida saqlanadi, shuning uchun /search?q=sunset&type=hdri&free=true kabi so'rovni xatcho'pga qo'shish yoki ulashish mumkin.

Natijaning batafsil oynasini ochib, uning litsenziyasi, muallifi, formatlari, poligonlar soni, teglari, mavjud ruxsatlari va taxminiy fayl hajmini ko'rib chiqing. Keyin format va ruxsatni tanlashingiz, aktivni yuklab olishingiz, curl buyrug'ini nusxalashingiz yoki agent uchun mo'ljallangan so'rovni nusxalashingiz mumkin.

Joylashtirilgan veb-sayt hujjatlar, OpenAPI ma'lumotnomasi, manba haqidagi ma'lumotlar va o'z serveringizda joylashtirish bo'yicha ko'rsatmalarni ham taqdim etadi. Agentlar uchun mo'ljallangan fayllar qatoriga /AGENTS.md, /llms.txt, /llms-full.txt va /openapi.json kiradi.

HTTP API bilan qidirish

Asosiy qidiruv endpointi GET /v1/search hisoblanadi. Aktiv turi, bepul mavjudligi, to'g'ridan-to'g'ri yuklab olishni qo'llab-quvvatlashi, provayderlar, natijalar limiti va offset kabi ixtiyoriy filtrlar bilan birga so'rov taqdim eting.

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

Qisqartirilgan javob saralangan natijalar va provayder hisobotlarini o'z ichiga oladi:

{
  "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
    }
  ]
}

Provayderlar katalogini olish uchun GET /v1/providers, aktivning to'liq tafsilotlari uchun GET /v1/assets/{provider}:{id} va format hamda ruxsat bo'yicha tanlangan fayllarni ko'rish uchun GET /v1/assets/{id}/files dan foydalaning.

API orqali yuklab olish

O'zini o'zi to'liq ta'minlaydigan fayl uchun yuklab olish endpointi manba fayliga yo'naltiradi. Bir nechta fayldan iborat aktivlar uchun esa aktiv va unga qo'shimcha fayllarni o'z ichiga olgan zip arxivini uzatadi:

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

API shuningdek /health, /openapi.json, /v1/catalog va /v1/stats endpointlarini taqdim etadi. Katalog provayderlar va aktivlar sonini ko'rsatadi, statistika endpointi esa foydalanish va manbalar holati haqida hisobot beradi.

CLI'dan foydalanish

Yig'ilgan CLI HTTP orqali xizmat ko'rsatishni, standart kiritish va chiqarish orqali MCP'ni hamda terminaldan qidirishni qo'llab-quvvatlaydi.

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

Natijalar ball, aktiv turi, bepul yoki pulliligi, provayder identifikatori, nomi va manba URL manzilini ko‘rsatadi. Provayder holatlari natijalardan keyin chiqariladi, shunda qaysi saytlar javob berganini va qaysilari faqat havolalar taqdim etganini ko‘rishingiz mumkin.

CLI orqali to‘liq mahalliy xizmatni ishga tushirish uchun quyidagidan foydalaning:

3d-asset-server serve

Standart kirish va chiqish orqali MCP serverini ishga tushirish uchun quyidagidan foydalaning:

3d-asset-server mcp

MCP’dan AI yordamchilari bilan foydalanish

MCP AI yordamchisiga aktivlarni qidirish, ularning tafsilotlarini ko‘rish va ruxsat etilgan fayllarni yuklab olish imkonini beradi. Mavjud vositalar:

• search_assets so‘rov, tur, provayder, litsenziya, yuklab olish imkoniyati va sahifalash filtrlari yordamida provayderlarni qidiradi.
• get_asset metadata, litsenziya ma’lumotlari, mavjud formatlar va ruxsatlarni, shuningdek tanlangan yuklab olish amali yuklaydigan fayllarni qaytaradi.
• download_asset aktiv va unga hamroh fayllarni sozlangan katalogga saqlaydi hamda qo‘llab-quvvatlanadigan zip to‘plamlarini chiqaradi.
• list_providers har bir provayder, uning aktiv turlari, narxlari, litsenziyasi va to‘g‘ridan-to‘g‘ri yuklab olishni qo‘llab-quvvatlashi haqida ma’lumot beradi.

Claude Code

Claude Code’ni mahalliy MCP jarayonini ishga tushirish va fayllarni joriy loyiha aktivlari katalogiga saqlash uchun sozlang:

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

Claude Desktop, Cursor va boshqa Stdio mijozlari

Mijozning MCP konfiguratsiyasiga server yozuvini qo‘shing:

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

Masofaviy MCP

Joylashtirilgan server Streamable HTTP MCP’ni qo‘llab-quvvatlaydi:

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

O‘zingiz joylashtirgan server uchun mijozni http://<host>:8787/mcp manziliga yo‘naltiring. Masofaviy HTTP orqali yuklab olish sukut bo‘yicha o‘chirilgan, chunki ular server diskiga fayllar yozadi. Bu rejimda get_asset to‘g‘ridan-to‘g‘ri fayl URL manzillari va bundle zip URL manzilini qaytaradi. Fayllar serverda saqlanishi kerak bo‘lgandagina ASSET_SERVER_HTTP_DOWNLOADS=true ni o‘rnating.

Yuklab olishlarni tushunish

Format ko‘rsatilmaganda, server amaliy o‘yin va veb formatlarini afzal ko‘radi. Modellarda avval glb, keyin gltf, fbx, obj va blend tanlanadi. HDRI’lar uchun avval hdr, keyin exr tanlanadi. Materiallar uchun tasvir xaritalari yoki zip, teksturalar uchun jpg, png, zip yoki exr afzal ko‘riladi, to‘plamlar esa chiqarilgan zip fayllar sifatida yuklab olinadi.

Standart ruxsat mavjud variantlar ichidan 2K ga eng yaqinini tanlaydi. Hamroh fayllar nisbiy yo‘llarini saqlab qoladi, shu sababli glTF fayli o‘zining ikkilik va tekstura fayllarini qo‘lda qayta joylashtirmasdan topa oladi.

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

Yuklab oluvchi faqat ochiq http va https URL manzillaridan foydalanadi, maxfiy va loopback manzillarni rad etadi, sozlanadigan hajm chegarasini qo‘llaydi hamda ../ kabi xavfli arxiv yo‘llarini qabul qilmaydi. U login sahifalari, to‘lov jarayonlari yoki hotlink himoyasini chetlab o‘tmaydi.

Konfiguratsiya

Serverni ishga tushirishdan oldin uning tarmoq manzili, provayderlari, yuklab olishlari, xavfsizligi va unumdorligini boshqarish uchun muhit o‘zgaruvchilarini o‘rnating.

• PORT va HOST HTTP ulanish manzilini boshqaradi. Ularning standart qiymatlari 8787 va 0.0.0.0.
• ASSET_SERVER_PROVIDERS polyhaven,ambientcg,kenney kabi vergul bilan ajratilgan ro‘yxatni qabul qiladi.
• ASSET_DOWNLOAD_DIR standart MCP yuklab olish katalogini ./assets o‘rniga o‘zgartiradi.
• ASSET_SERVER_MAX_DOWNLOAD_BYTES har bir yuklab olish uchun hajm chegarasini belgilaydi; standart qiymat 2 GiB.
• ASSET_SERVER_PROVIDER_TIMEOUT_MS va ASSET_SERVER_HTTP_TIMEOUT_MS provayder va HTTP kutish vaqtlarini sozlaydi.
• ASSET_SERVER_CACHE_TTL_MS xotiradagi HTTP keshi amal qilish muddatini boshqaradi.
• BLENDERKIT_API_KEY BlenderKit tarif rejasi va xarid qilingan aktivlardan foydalanishni ochishi mumkin.
• NODE_USE_ENV_PROXY=1 Node’ni sozlangan HTTPS_PROXY dan foydalanishga majbur qiladi.

Autentifikatsiya va tezlik cheklovlari

/v1/* va /mcp ni himoyalash uchun ASSET_SERVER_API_KEY ni o‘rnating. Mijozlar kalitni Bearer token, x-api-key sarlavhasi yoki api_key so‘rov parametri sifatida yuborishi mumkin. So‘rov parametrlaridan foydalanishda ehtiyot bo‘ling, chunki brauzer tarixi va server jurnallarida ular saqlanib qolishi mumkin.

Tezlikni cheklash sukut bo‘yicha har bir mijoz uchun 60 soniyalik oynada 120 ta so‘rov bilan yoqilgan. ASSET_SERVER_RATE_LIMIT va ASSET_SERVER_RATE_LIMIT_WINDOW ni sozlang yoki cheklovni o‘chirish uchun qiymatni 0 qilib o‘rnating.

Proksi va provayder muammolarini bartaraf etish

CGTrader bulut va ma’lumotlar markazi IP manzillarini bloklashi mumkin. U ko‘pincha uy interneti orqali ishlaydi; serverda proksi sozlang va NODE_USE_ENV_PROXY=1 ni o‘rnating. Ma’lumot qirib oluvchi provayderlar HTML kodini ham o‘zgartirishi mumkin. Ulardan biri ishlamay qolsa, boshqa manbalar natijalarni qaytarishda davom etadi, npm run test:live esa provayderlar mavjudligini tekshirishi mumkin.

Kengaytirilgan monitoring

Prometheus metrikalarini alohida portda ochish uchun METRICS_PORT qiymatini o‘rnating. Server qidiruvlar, provayder so‘rovlari, yuklab olishlar, aktivlarni ko‘rishlar, MCP vositalari chaqiruvlari, HTTP so‘rovlari va sahifa ko‘rishlari uchun chegaralangan teglar bilan metrikalarni qayd etadi. Shuningdek, IP manzillar, kalitlar yoki cookie’larni qayd etmasdan, tuzilgan qidiruv hodisalarini jurnalga yozadi.

Agar PROMETHEUS_URL sozlangan bo‘lsa, statistika endpointi replikalar bo‘yicha umumlashtirilgan ma’lumotlarni qaytarishi mumkin. Aks holda, statistika jarayon oxirgi marta qayta ishga tushirilganidan beri faqat joriy jarayonga tegishli ma’lumotlarni aks ettiradi.

Tavsiya etiladigan ish jarayoni

1. sunset, low poly tree yoki brick wall kabi tavsiflovchi so‘rov bilan keng qidiring.
2. Aktiv turi, bepul ekanligi, to‘g‘ridan-to‘g‘ri yuklab olish imkoniyati yoki tanlangan provayderlar bo‘yicha filtrlang.
3. Litsenziya, atributsiya talabi, formatlar, ruxsatlar va fayllar ro‘yxatini tekshiring.
4. O‘yiningiz yoki veb-saytingiz uchun mos format va ruxsatni tanlang.
5. Aktivni yuklab oling yoki provayder to‘g‘ridan-to‘g‘ri yuklab olishga ruxsat bermasa, uning manba havolasini nusxalang.
6. Talab qilinadigan atributsiya va litsenziya fayllarini loyihangiz bilan birga saqlang.

Xulosa

3d-asset-server tarqoq aktivlarni izlash jarayonini yagona ish oqimiga aylantiradi. Uning veb-interfeysi, HTTP API’si, CLI’si va MCP vositalari yordamida ko‘plab provayderlarda qidirish, litsenziya hamda yuklab olish ma’lumotlarini taqqoslash va foydalanishga tayyor modellar, teksturalar, HDRI’lar hamda to‘plamlarni olish mumkin. Node.js yoki Docker yordamida mahalliy ishga tushiring, so‘ngra ishlab chiqarish muhitida provayderlar, autentifikatsiya, yuklab olish yo‘llari, so‘rovlar tezligi cheklovlari va monitoringni sozlang.