Mafunzo ya Seva ya Rasilimali za 3D: Tafuta, Linganisha na Pakua Rasilimali za Michezo kutoka Vyanzo 18

Kazi ya 3d-asset-server

3d-asset-server hutoa kisanduku kimoja cha kutafuta miundo ya 3D, nyenzo, maumbo, HDRI, sprites, vipengee vya UI, sauti, fonti, na vifurushi vya vipengee vya michezo. Hutafuta kwenye watoa huduma 18, huunganisha na kupanga matokeo, huripoti hali ya kila chanzo, na hupakua vipengee wakati mtoa huduma anaruhusu upakuaji wa moja kwa moja.

Unaweza kutumia mradi huu kupitia kivinjari, kwa curl, kupitia kiolesura chake cha mstari wa amri, au kutoka kwa msaidizi wa AI aliyeunganishwa kupitia Model Context Protocol (MCP). Matokeo yanajumuisha taarifa za leseni, hali ya bei, mahitaji ya kutaja chanzo, miundo, maazimio, na viungo vya watoa huduma.

Jinsi Utafutaji Unavyofanya Kazi

Kwa kila swali, seva huchagua watoa huduma husika na kuwatafuta kwa wakati mmoja. Kila mtoa huduma ana muda wake wa kuisha, kwa hiyo tovuti iliyo polepole au isiyopatikana haizuii matokeo kutoka vyanzo vingine kuonekana.

Matokeo hupangwa kwa kutumia umuhimu wa maandishi, mpangilio wa mtoa huduma, ikiwa matokeo yametoka kwenye API au scraper, upatikanaji bila malipo, usaidizi wa upakuaji wa moja kwa moja, na utofauti wa vyanzo. Jibu pia linajumuisha ripoti ya kila mtoa huduma yenye hali kama vile ok, error, timeout, skipped, au link.

Baadhi ya watoa huduma wanaunga mkono upakuaji wa moja kwa moja. Poly Haven, ambientCG, Kenney, TextureCan, na vipengee vya bure kutoka BlenderKit ni mifano. Watoa huduma wengine hurejesha metadata kamili na kiungo cha ukurasa wa kipengee, huku Fab, Poliigon, na TurboSquid wakitoa viungo vya kurasa zao za utafutaji wakati ulinzi dhidi ya roboti unazuia utafutaji wa kiotomatiki.

Vyanzo Vinavyoungwa Mkono

Katalogi ya watoa huduma inajumuisha vyanzo vya aina mbalimbali za maudhui:

• HDRI na nyenzo za PBR: Poly Haven, ambientCG, HDRMaps, HDRI Hub, na 3DTexel.
• Vipengee vya low-poly na michezo: Kenney, Quaternius, Fab, itch.io, na BlenderKit.
• Maumbo na nyenzo zilizochanganuliwa: CGBookcase, ShareTextures, TextureCan, Textures.com, na 3DTextures.me.
• Miundo na masoko ya vipengee: BlenderKit, CGTrader, TurboSquid, Fab, na itch.io.

Maelezo ya leseni hutofautiana kulingana na tangazo. Kwa mfano, Poly Haven, ambientCG, na Kenney hutoa maudhui ya CC0, huku watoa huduma wa masoko wakitumia leseni mahususi kwa kila tangazo. Kagua kila mara taarifa ya leseni na kutaja chanzo iliyorejeshwa kabla ya kusambaza kipengee.

Kusakinisha na Kuweka

Mradi unahitaji Node.js 20 au mpya zaidi. Nakili hazina, sakinisha utegemezi, kisha jenga programu:

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

Anzisha UI ya wavuti, API ya HTTP, na endpoint ya MCP kwa:

npm start

Seva ya ndani huendeshwa kwenye http://localhost:8787 kwa chaguo-msingi.

Usanidi wa Docker

Unaweza pia kujenga na kuendesha seva kwa Docker:

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

Kutumia UI ya Wavuti

Fungua http://localhost:8787 baada ya kuanzisha seva. Toleo linalopangishwa linapatikana kwenye 3d.shep.bot.

Tumia ukurasa wa utafutaji kuingiza swali, kuchagua aina ya kipengee, kuzuia matokeo kwa vipengee vya bure, kuhitaji upakuaji wa moja kwa moja, au kuchagua watoa huduma mahususi. Hali ya utafutaji huhifadhiwa kwenye URL, kwa hiyo swali kama /search?q=sunset&type=hdri&free=true linaweza kuwekwa alamisho au kushirikiwa.

Fungua laha ya maelezo ya matokeo ili kukagua leseni yake, mwandishi, miundo, idadi ya poligoni, lebo, maazimio yanayopatikana, na ukubwa wa faili unaokadiriwa. Kisha unaweza kuchagua muundo na azimio, kupakua kipengee, kunakili amri ya curl, au kunakili kidokezo kinachoelekezwa kwa wakala.

Tovuti inayopangishwa pia hutoa nyaraka, marejeleo ya OpenAPI, taarifa za chanzo, na mwongozo wa kujiendeshea. Faili zake zinazoelekezwa kwa mawakala zinajumuisha /AGENTS.md, /llms.txt, /llms-full.txt, na /openapi.json.

Kutafuta kwa API ya HTTP

Endpoint kuu ya utafutaji ni GET /v1/search. Toa swali lenye vichujio vya hiari kama vile aina ya kipengee, upatikanaji bila malipo, usaidizi wa upakuaji wa moja kwa moja, watoa huduma, kikomo cha matokeo, na nafasi ya kuanzia.

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

Jibu lililofupishwa lina matokeo yaliyopangwa na ripoti za watoa huduma:

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

Tumia GET /v1/providers kupata katalogi ya watoa huduma, GET /v1/assets/{provider}:{id} kupata maelezo kamili ya kipengee, na GET /v1/assets/{id}/files kukagua faili zilizochaguliwa kwa muundo na azimio.

Kupakua kupitia API

Kwa faili inayojitosheleza, endpoint ya upakuaji huelekeza kwenye faili ya chanzo. Kwa vipengee vyenye faili nyingi, hutiririsha zip iliyo na kipengee na faili zake zinazoandamana:

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

API pia hutoa /health, /openapi.json, /v1/catalog, na /v1/stats. Katalogi hutoa hesabu za watoa huduma na vipengee, huku endpoint ya takwimu ikiripoti matumizi na afya ya vyanzo.

Kutumia CLI

CLI iliyojengwa inaunga mkono huduma ya HTTP, MCP kupitia ingizo na towe la kawaida, pamoja na utafutaji kutoka kwenye terminal.

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

Matokeo yanaonyesha alama, aina ya kipengee, hali ya bure, kitambulisho cha mtoa huduma, kichwa, na URL ya chanzo. Hali za watoa huduma huchapishwa baada ya matokeo ili uweze kuona ni tovuti zipi zilijibu na zipi zilitoa viungo pekee.

Ili kuendesha huduma kamili ya ndani kutoka kwenye CLI, tumia:

3d-asset-server serve

Ili kuanzisha seva ya MCP kupitia ingizo na towe la kawaida, tumia:

3d-asset-server mcp

Kutumia MCP na Visaidizi vya AI

MCP humwezesha msaidizi wa AI kutafuta vipengee, kukagua maelezo yake, na kupakua faili zinazoruhusiwa. Zana zinazopatikana ni:

• search_assets hutafuta kwa watoa huduma kwa kutumia vichujio vya hoja, aina, mtoa huduma, leseni, uwezo wa kupakua, na kurasa.
• get_asset hurejesha metadata, maelezo ya leseni, fomati na mwonekano unaopatikana, pamoja na faili ambazo upakuaji uliochaguliwa ungepakua.
• download_asset huhifadhi kipengee na faili zake za ziada kwenye saraka iliyosanidiwa na kutoa pakiti za zip zinazotumika.
• list_providers hueleza kila mtoa huduma, aina za vipengee, bei, leseni, na usaidizi wa upakuaji wa moja kwa moja.

Claude Code

Sanidi Claude Code ili izindue mchakato wa ndani wa MCP na ihifadhi faili kwenye saraka ya vipengee ya mradi wa sasa:

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

Claude Desktop, Cursor, na Wateja Wengine wa Stdio

Ongeza ingizo la seva kwenye usanidi wa MCP wa mteja:

{
  "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 ya Mbali

Seva inayopangishwa inasaidia MCP ya Streamable HTTP:

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

Kwa seva unayojiendeshea mwenyewe, elekeza mteja kwenye http://<host>:8787/mcp. Upakuaji wa HTTP wa mbali umezimwa kwa chaguo-msingi kwa sababu ungeandika faili kwenye diski ya seva. Katika hali hiyo, get_asset hurejesha URL za moja kwa moja za faili na URL ya zipu ya kifurushi. Weka ASSET_SERVER_HTTP_DOWNLOADS=true pekee wakati seva inapaswa kuhifadhi faili hizo.

Kuelewa Upakuaji

Wakati hakuna fomati iliyobainishwa, seva hupendelea fomati zinazofaa kwa michezo na wavuti. Miundo hupendelea glb, kisha gltf, fbx, obj, na blend. HDRI hupendelea hdr na kisha exr. Nyenzo hupendelea ramani za picha au zipu, maumbo hupendelea jpg, png, zip, au exr, na pakiti hupakuliwa kama faili za zipu zilizotolewa.

Mwonekano chaguo-msingi ni chaguo lililo karibu zaidi na 2K. Faili za ziada huhifadhi njia zake zinazohusiana, hivyo kuruhusu faili ya glTF kupata faili zake za binary na maumbo bila kupanga upya kwa mikono.

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

Kipakua hupakua URL za umma za http na https pekee, hukataa anwani za faragha na loopback, huweka kikomo cha ukubwa kinachoweza kusanidiwa, na hukataa njia hatari za kumbukumbu kama ../. Hakiuki kurasa za kuingia, mchakato wa malipo, au ulinzi wa hotlink.

Usanidi

Weka vigezo vya mazingira kabla ya kuanzisha seva ili kudhibiti anwani yake ya mtandao, watoa huduma, upakuaji, usalama, na utendaji.

• PORT na HOST hudhibiti anwani ya HTTP ya kufungia. Chaguo-msingi zake ni 8787 na 0.0.0.0.
• ASSET_SERVER_PROVIDERS hupokea orodha iliyotenganishwa kwa koma kama polyhaven,ambientcg,kenney.
• ASSET_DOWNLOAD_DIR hubadilisha folda chaguo-msingi ya upakuaji wa MCP kutoka ./assets.
• ASSET_SERVER_MAX_DOWNLOAD_BYTES huweka kikomo cha ukubwa kwa kila upakuaji, ambacho chaguo-msingi ni 2 GiB.
• ASSET_SERVER_PROVIDER_TIMEOUT_MS na ASSET_SERVER_HTTP_TIMEOUT_MS hurekebisha muda wa kusubiri wa mtoa huduma na HTTP.
• ASSET_SERVER_CACHE_TTL_MS hudhibiti muda wa kuhifadhi akiba ya HTTP iliyo kwenye kumbukumbu.
• BLENDERKIT_API_KEY inaweza kufungua vipengee vya BlenderKit vya mpango na vilivyonunuliwa.
• NODE_USE_ENV_PROXY=1 hufanya Node itumie HTTPS_PROXY iliyosanidiwa.

Uthibitishaji na Vikomo vya Kasi

Weka ASSET_SERVER_API_KEY ili kulinda /v1/* na /mcp. Wateja wanaweza kutuma ufunguo kama tokeni ya Bearer, kichwa cha x-api-key, au kigezo cha hoja cha api_key. Kuwa mwangalifu na vigezo vya hoja kwa sababu historia ya kivinjari na kumbukumbu za seva vinaweza kuwa navyo.

Kikomo cha kasi kimewezeshwa kwa chaguo-msingi kwa maombi 120 kwa kila mteja ndani ya dirisha la sekunde 60. Sanidi ASSET_SERVER_RATE_LIMIT na ASSET_SERVER_RATE_LIMIT_WINDOW, au weka kikomo kuwa 0 ili kukizima.

Utatuzi wa Matatizo ya Proksi na Watoa Huduma

CGTrader inaweza kuzuia anwani za IP za wingu na vituo vya data. Mara nyingi hufanya kazi kutoka kwenye muunganisho wa nyumbani; kwenye seva, sanidi proksi na uweke NODE_USE_ENV_PROXY=1. Watoa huduma wanaochanganuliwa wanaweza pia kubadilisha HTML yao. Mmoja akivurugika, vyanzo vingine vitaendelea kurejesha matokeo, na npm run test:live inaweza kukagua upatikanaji wa watoa huduma.

Ufuatiliaji wa Kina

Weka METRICS_PORT ili kufichua vipimo vya Prometheus kwenye mlango tofauti. Seva huhifadhi vipimo vyenye lebo zenye mipaka kwa utafutaji, maombi kwa watoa huduma, upakuaji, kutazamwa kwa rasilimali, miito ya zana za MCP, maombi ya HTTP na kutazamwa kwa kurasa. Pia huweka kumbukumbu za matukio ya utafutaji zilizoundwa bila kurekodi anwani za IP, funguo au vidakuzi.

Ikiwa PROMETHEUS_URL imesanidiwa, sehemu ya takwimu inaweza kuripoti data iliyojumlishwa kutoka kwa nakala nyingi. Bila hiyo, takwimu huwakilisha mchakato wa sasa tangu ulipoanzishwa upya mara ya mwisho.

Mtiririko Unaopendekezwa wa Kazi

1. Tafuta kwa upana ukitumia swali lenye maelezo, kama vile sunset, low poly tree au brick wall.
2. Chuja kwa aina ya rasilimali, hali ya bila malipo, upatikanaji wa upakuaji wa moja kwa moja au watoa huduma waliochaguliwa.
3. Kagua leseni, hitaji la kutoa sifa, miundo, ubora na orodha ya faili.
4. Chagua muundo na ubora unaofaa kwa mchezo au tovuti yako.
5. Pakua rasilimali au nakili kiungo chake cha chanzo ikiwa mtoa huduma haruhusu upakuaji wa moja kwa moja.
6. Hifadhi maelezo yoyote ya lazima ya sifa na faili za leseni pamoja na mradi wako.

Hitimisho

3d-asset-server hubadilisha ugunduzi wa rasilimali uliotawanyika kuwa mtiririko mmoja wa kazi. Kiolesura chake cha wavuti, API ya HTTP, CLI na zana za MCP hukuwezesha kutafuta watoa huduma wengi, kulinganisha maelezo ya leseni na upakuaji, na kupata miundo, maumbo, HDRI na pakiti zilizo tayari kutumika. Anza ndani ya kompyuta yako ukitumia Node.js au Docker, kisha sanidi watoa huduma, uthibitishaji, njia za upakuaji, vikomo vya kasi na ufuatiliaji kwa ajili ya uwekaji wa uzalishaji.