Isifundo Se-3D Asset Server: Sesha, Qhathanisa, Futhi Udawunilode Ama-Asset Egeyimu Emithonjeni engu-18

Lokho okwenziwa yi-3d-asset-server

3d-asset-server inikeza ibhokisi lokusesha elilodwa lamamodeli e-3D, izinto zokwakha, ama-texture, ama-HDRI, ama-sprite, izimpahla ze-UI, umsindo, amafonti, namaphakheji ezimpahla zemidlalo. Isesha abahlinzeki abangu-18, ihlanganise futhi ihlele imiphumela ngokwezinga, ibike isimo somthombo ngamunye, futhi ilande izimpahla uma umhlinzeki evumela ukulanda okuqondile.

Ungasebenzisa iphrojekthi esipheqululini, nge-curl, usebenzisa isixhumi esibonakalayo somugqa womyalo, noma kumsizi we-AI oxhunywe nge-Model Context Protocol (MCP). Imiphumela ihlanganisa ulwazi lwelayisensi, isimo sentengo, izimfuneko zokunikeza udumo, amafomethi, izinqumo, nezixhumanisi zabahlinzeki.

Indlela Ukusesha Okusebenza Ngayo

Embuzweni ngamunye, iseva ikhetha abahlinzeki abafanele bese ibasesha ngokufana. Umhlinzeki ngamunye unesikhathi sakhe sokulinda, ngakho isayithi elihamba kancane noma elingatholakali alivimbeli imiphumela evela kweminye imithombo.

Imiphumela ihlelwa kusetshenziswa ukuhambisana kombhalo, ukuhlelwa komhlinzeki, ukuthi umphumela uvela ku-API noma ku-scraper, ukutholakala mahhala, ukusekelwa kokulanda okuqondile, nokwehlukahlukana kwemithombo. Impendulo ihlanganisa nombiko womhlinzeki ngamunye onezimo ezifana no-ok, error, timeout, skipped, noma link.

Abanye abahlinzeki basekela ukulanda okuqondile. I-Poly Haven, i-ambientCG, i-Kenney, i-TextureCan, nezimpahla zamahhala ezivela ku-BlenderKit ziyizibonelo. Abanye abahlinzeki babuyisa imethadatha ephelele nesixhumanisi sekhasi lempahla, kanti i-Fab, i-Poliigon, ne-TurboSquid banikeza izixhumanisi zamakhasi abo okusesha lapho ukuvikelwa kuma-bot kuvimbela ukusesha okuzenzakalelayo.

Imithombo Esekelwayo

Ikhathalogi yabahlinzeki ihlanganisa imithombo yezinhlobo ezahlukene zokuqukethwe:

• Ama-HDRI nezinto ze-PBR: i-Poly Haven, i-ambientCG, i-HDRMaps, i-HDRI Hub, ne-3DTexel.
• Izimpahla ze-low-poly nezemidlalo: i-Kenney, i-Quaternius, i-Fab, i-itch.io, ne-BlenderKit.
• Ama-texture nezinto eziskeniwe: i-CGBookcase, i-ShareTextures, i-TextureCan, i-Textures.com, ne-3DTextures.me.
• Amamodeli nezimakethe zezimpahla: i-BlenderKit, i-CGTrader, i-TurboSquid, i-Fab, ne-itch.io.

Imininingwane yelayisensi iyahlukahluka ngokohlu. Ngokwesibonelo, i-Poly Haven, i-ambientCG, ne-Kenney zinikeza okuqukethwe kwe-CC0, kanti abahlinzeki bezimakethe bangasebenzisa amalayisensi athile ohlu ngalunye. Hlala ubuyekeza ilayisensi ebuyisiwe nolwazi lokunikeza udumo ngaphambi kokusabalalisa impahla.

Ukufaka Nokulungiselela

Iphrojekthi idinga i-Node.js 20 noma entsha. Klona i-repository, faka okuncikile, bese wakha uhlelo:

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

Qalisa i-web UI, i-HTTP API, ne-MCP endpoint ngalo myalo:

npm start

Iseva yasendaweni isebenza ku-http://localhost:8787 ngokuzenzakalela.

Ukulungiselela i-Docker

Ungakha futhi usebenzise iseva nge-Docker:

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

Ukusebenzisa i-Web UI

Vula i-http://localhost:8787 ngemva kokuqala iseva. Inguqulo esingathwe iyatholakala ku-3d.shep.bot.

Sebenzisa ikhasi lokusesha ukufaka umbuzo, ukhethe uhlobo lwempahla, ukhawulele imiphumela ezimpahleni zamahhala, udinge ukulanda okuqondile, noma ukhethe abahlinzeki abathile. Isimo sokusesha sigcinwa ku-URL, ngakho umbuzo ofana no-/search?q=sunset&type=hdri&free=true ungagcinwa njengophawu lokubekisa noma wabelwane ngawo.

Vula ishidi lemininingwane lomphumela ukuze ubuyekeze ilayisensi yawo, umbhali, amafomethi, inani lamapholigoni, omaka, izinqumo ezitholakalayo, nobukhulu befayela obulinganisiwe. Ngemva kwalokho ungakhetha ifomethi nesinqumo, ulande impahla, ukopishe umyalo we-curl, noma ukopishe umyalo ogxile kuma-agent.

Iwebhusayithi esingathwe inikeza nemibhalo, inkomba ye-OpenAPI, ulwazi lomthombo, nesiqondiso sokusingatha wena. Amafayela ayo agxile kuma-agent ahlanganisa i-/AGENTS.md, i-/llms.txt, i-/llms-full.txt, ne-/openapi.json.

Ukusesha nge-HTTP API

I-endpoint eyinhloko yokusesha yi-GET /v1/search. Nikeza umbuzo onezihlungi ongazikhetha ezifana nohlobo lwempahla, ukutholakala mahhala, ukusekelwa kokulanda okuqondile, abahlinzeki, umkhawulo wemiphumela, ne-offset.

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

Impendulo emfushane iqukethe imiphumela ehleliwe nemibiko yabahlinzeki:

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

Sebenzisa i-GET /v1/providers ukuze uthole ikhathalogi yabahlinzeki, i-GET /v1/assets/{provider}:{id} ukuze uthole imininingwane ephelele yempahla, kanye ne-GET /v1/assets/{id}/files ukuze uhlole amafayela akhethwe yifomethi nesinqumo.

Ukulanda nge-API

Efayelini elizimele, i-endpoint yokulanda iqondisa kabusha kufayela lomthombo. Ezimpahleni ezinamafayela amaningi, isakaza i-zip equkethe impahla nabangane bayo:

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

I-API iphinde iveze i-/health, i-/openapi.json, i-/v1/catalog, ne-/v1/stats. Ikhathalogi inikeza izibalo zabahlinzeki nezimpahla, kanti i-endpoint yezibalo ibika ukusetshenziswa nempilo yemithombo.

Ukusebenzisa i-CLI

I-CLI eyakhiwe isekela ukunikeza isevisi nge-HTTP, i-MCP ngokufaka nokukhipha okujwayelekile, nokusesha kusuka ku-terminal.

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

Imiphumela ikhombisa amaphuzu, uhlobo lwempahla, isimo sokuba mahhala, isihlonzi somhlinzeki, isihloko, kanye ne-URL yomthombo. Izimo zabahlinzeki ziphrintwa ngemva kwemiphumela ukuze ubone ukuthi yiziphi izingosi eziphendulile nokuthi yiziphi ezinikeze izixhumanisi kuphela.

Ukuqalisa isevisi ephelele yendawo kusuka ku-CLI, sebenzisa:

3d-asset-server serve

Ukuqalisa iseva ye-MCP ngokufaka nokukhipha okujwayelekile, sebenzisa:

3d-asset-server mcp

Ukusebenzisa i-MCP Nabasizi be-AI

I-MCP ivumela umsizi we-AI ukuthi aseshe impahla, ahlole imininingwane yayo, futhi alande amafayela avunyelwe. Amathuluzi atholakalayo yilawa:

• search_assets isesha abahlinzeki isebenzisa izihlungi zombuzo, uhlobo, umhlinzeki, ilayisensi, amandla okulanda, kanye nokupheja.
• get_asset ibuyisa imethadatha, ulwazi lwelayisensi, amafomethi nezinqumo ezitholakalayo, kanye namafayela azolandwa lapho kukhethwa ukulanda.
• download_asset igcina impahla namafayela ayo ahambisana nayo kufolda emisiwe futhi ikhiphe amaphakethe e-zip asekelwayo.
• list_providers ichaza wonke umhlinzeki, izinhlobo zempahla zakhe, amanani, ilayisensi, kanye nokusekelwa kokulanda okuqondile.

Claude Code

Hlela i-Claude Code ukuze iqalise inqubo ye-MCP yendawo futhi igcine amafayela kufolda yempahla yephrojekthi yamanje:

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

Claude Desktop, Cursor, Namanye Amaklayenti e-Stdio

Engeza okufakiwe kweseva ekucushweni kwe-MCP kweklayenti:

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

i-MCP Ekude

Iseva esingathwe kuyo isekela i-Streamable HTTP MCP:

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

Uma usebenzisa iseva ozibambele yona, qondisa iklayenti ku-http://<host>:8787/mcp. Ukulanda kwe-HTTP okukude kuvaliwe ngokuzenzakalela ngoba bekuzobhala amafayela kudiski yeseva. Kuleyo modi, i-get_asset ibuyisa ama-URL aqondile amafayela kanye ne-URL ye-zip yephakheji. Setha ASSET_SERVER_HTTP_DOWNLOADS=true kuphela lapho iseva kufanele igcine amafayela.

Ukuqonda Ukulanda

Uma kungacaciswanga ifomethi, iseva ikhetha amafomethi asebenzayo emidlalo nakuwebhu. Amamodeli akhetha glb, bese kuba gltf, fbx, obj, kanye ne-blend. Ama-HDRI akhetha hdr bese kuba exr. Izinto zokwakha zikhetha amamephu ezithombe noma i-zip, ukwakheka kukhetha jpg, png, zip, noma exr, kanti amaphakethe alandwa njengamafayela e-zip akhishiwe.

Isinqumo esizenzakalelayo siyindlela etholakalayo eseduze kakhulu ne-2K. Amafayela ahambisana nayo agcina izindlela zawo ezihlobene, okwenza ifayela le-glTF lithole ifayela lalo le-binary namafayela okwakheka ngaphandle kokuhlelwa kabusha ngesandla.

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

Isilandi silanda kuphela ama-URL asesidlangalaleni e-http ne-https, senqaba amakheli ayimfihlo nawezokubuyela kumshini ofanayo, sisebenzisa umkhawulo kasayizi olungisekayo, futhi senqaba izindlela ezingaphephile zamaphakheji njenge-../. Asidluli emakhasini okungena, ezinqubweni zokukhokha, noma ekuvikelweni kwe-hotlink.

Ukucushwa

Setha okuguquguqukayo kwemvelo ngaphambi kokuqala iseva ukuze ulawule ikheli lenethiwekhi, abahlinzeki, ukulanda, ukuphepha, kanye nokusebenza kwayo.

• PORT no-HOST balawula ikheli lokubopha le-HTTP. Okuzenzakalelayo kwabo ngu-8787 no-0.0.0.0.
• ASSET_SERVER_PROVIDERS yamukela uhlu oluhlukaniswe ngamakhoma olufana ne-polyhaven,ambientcg,kenney.
• ASSET_DOWNLOAD_DIR ishintsha ifolda ezenzakalelayo yokulanda ye-MCP isuke ku-./assets.
• ASSET_SERVER_MAX_DOWNLOAD_BYTES isetha umkhawulo kasayizi wokulanda ngakunye, ozenzakalelayo ku-2 GiB.
• ASSET_SERVER_PROVIDER_TIMEOUT_MS no-ASSET_SERVER_HTTP_TIMEOUT_MS balungisa izikhathi zokulinda zomhlinzeki neze-HTTP.
• ASSET_SERVER_CACHE_TTL_MS ilawula isikhathi sokuhlala senqolobane ye-HTTP esenkumbulweni.
• BLENDERKIT_API_KEY ingavula amapulani e-BlenderKit nempahla ethengiwe.
• NODE_USE_ENV_PROXY=1 yenza i-Node isebenzise i-HTTPS_PROXY emisiwe.

Ukuqinisekiswa Nobukhulu Bezicelo

Setha ASSET_SERVER_API_KEY ukuze uvikele i-/v1/* kanye ne-/mcp. Amaklayenti angathumela ukhiye njengethokheni ye-Bearer, kunhlokweni ye-x-api-key, noma kupharamitha yombuzo ye-api_key. Qaphela ngamapharamitha emibuzo ngoba umlando wesiphequluli namalogi eseva kungase kube nawo.

Ukukhawulelwa kwezinga kunikwe amandla ngokuzenzakalelayo ngezicelo ezingu-120 ngeklayenti ngalinye phakathi kwewindi lamasekhondi angu-60. Lungisa ASSET_SERVER_RATE_LIMIT kanye ne-ASSET_SERVER_RATE_LIMIT_WINDOW, noma setha umkhawulo ube ngu-0 ukuze ukuvale.

Ukuxazulula Izinkinga Zommeleli Nomhlinzeki

I-CGTrader ingase ivimbe amakheli e-IP amafu nawe-datacenter. Ivamise ukusebenza kusukela ekuxhumekeni kwasekhaya; kuseva, lungisa ummeleli bese usetha NODE_USE_ENV_PROXY=1. Abahlinzeki abaqoqwa ngedatha nabo bangashintsha i-HTML yabo. Uma oyedwa ephazamiseka, eminye imithombo iyaqhubeka nokubuyisa imiphumela, futhi npm run test:live ingahlola ukutholakala kwabahlinzeki.

Ukuqapha Okuthuthukile

Setha METRICS_PORT ukuze uveze amamethrikhi e-Prometheus echwebeni elihlukile. Iseva igcina amamethrikhi anamalebula anomkhawulo okusesha, izicelo kubahlinzeki, ukulanda, ukubukwa kwama-asset, izingcingo zamathuluzi e-MCP, izicelo ze-HTTP, nokubukwa kwamakhasi. Iphinde ibhale imicimbi yokusesha ehlelekile ngaphandle kokugcina amakheli e-IP, okhiye, noma amakhukhi.

Uma i-PROMETHEUS_URL ilungisiwe, i-endpoint yezibalo ingabika idatha ehlanganisiwe kuwo wonke ama-replica. Ngaphandle kwayo, izibalo zimelela inqubo yamanje kusukela iqalwe kabusha okokugcina.

Ukugeleza Komsebenzi Okunconyiwe

1. Sesha kabanzi ngombuzo ochazayo ofana ne-sunset, low poly tree, noma brick wall.
2. Hlunga ngohlobo lwe-asset, isimo sokuba mahhala, ukutholakala kokulanda okuqondile, noma abahlinzeki abakhethiwe.
3. Hlola ilayisensi, imfuneko yokunikeza udumo, amafomethi, izinqumo, nohlu lwamafayela.
4. Khetha ifomethi nesinqumo esifanele umdlalo noma iwebhusayithi yakho.
5. Landa i-asset noma ukopishe isixhumanisi sayo somthombo uma umhlinzeki engakuvumeli ukulanda okuqondile.
6. Gcina noma yikuphi ukunikezwa kodumo namafayela elayisensi kanye nephrojekthi yakho.

Isiphetho

3d-asset-server iguqula ukutholakala kwama-asset ahlakazekile kube ukugeleza komsebenzi okukodwa. I-UI yayo yewebhu, i-HTTP API, i-CLI, namathuluzi e-MCP kukuvumela ukuthi useshe abahlinzeki abaningi, uqhathanise ulwazi lwelayisensi nolokulanda, futhi uthole amamodeli, ama-texture, ama-HDRI, namaphakethe alungele ukusetshenziswa. Qala endaweni yangakini nge-Node.js noma i-Docker, bese ulungiselela abahlinzeki, ukuqinisekiswa, izindlela zokulanda, imikhawulo yezinga, nokuqapha ukuze kusetshenziswe ekukhiqizeni.