# Codels

> Codels is a library of 3D models for three.js games. Most models are defined as code (CodelSpec) and
> can be fetched as ready-to-use three.js ES modules, React Three Fiber components, glTF/GLB, OBJ or STL.
> All files are public, CORS-enabled and need no API key.

## Conventions
- Units: meters · Up: +Y · Front: +Z · Origin: center of the model's base (y = 0)
- Built-in models are CC0 (public domain). Community uploads show their license on the model page.

## Find a model
- Search: https://codels.download/api/v1/models?q=<words>&category=<slug>&tags=<a,b>&sort=relevance|popular|new
- Tags (with counts): https://codels.download/api/v1/tags?q=<prefix>
- Categories: https://codels.download/api/v1/categories
- Model metadata + all URLs: https://codels.download/api/v1/models/<slug>

## Use a model
- Agent page (description, preview image, size, parts, full code): https://codels.download/m/<slug>.md
- three.js ES module exporting create<Name>(): THREE.Group: https://codels.download/m/<slug>.js
- React Three Fiber component: https://codels.download/m/<slug>.jsx
- Many copies (forests, crowds, props): https://codels.download/m/<slug>.instanced.js — bake<Name>() merges the model into one geometry per material; create<Name>Instances(count, place) returns InstancedMeshes
- Standalone HTML demo: https://codels.download/m/<slug>.html
- Binary glTF: https://codels.download/m/<slug>.glb (also .gltf, .obj, .stl); add ?compress=meshopt for a 2–3× smaller file (GLTFLoader.setMeshoptDecoder(MeshoptDecoder) from three/addons/libs/meshopt_decoder.module.js)
- Preview image: https://codels.download/m/<slug>.png · 4-view sheet: https://codels.download/m/<slug>.sheet.png
- Parametric models accept query params on every URL (see the "Parameters" table in the .md page), e.g. https://codels.download/m/pine-tree.js?height=5&snow=true

## Packs (curated kits) and collections
- Overview with every model's links: https://codels.download/c/<pack>.md · one ES module with all models: https://codels.download/c/<pack>.js · ZIP: https://codels.download/c/<pack>.zip
- Packs: medieval-village-kit, platformer-kit, scifi-base-kit, city-street-kit, forest-nature-kit, dungeon-kit, racing-kit, farm-kit, space-kit, pirate-kit, winter-kit, cafe-kitchen-kit, modular-dungeon-kit, modular-house-kit

## MCP server
- Endpoint (Streamable HTTP): https://codels.download/mcp — tools: search_models, get_model (includes a preview image), get_model_code, list_packs, get_pack, list_categories
- Claude Code: claude mcp add --transport http codels https://codels.download/mcp

## CLI
- npx codels-cli search "medieval barrel" · npx codels-cli add pine-tree --param height=5 · --format r3f|instanced|glb · npx codels-cli pack platformer-kit

## Rate limits and API keys
- No key needed. Without a key: 120 API / 600 file / 240 MCP requests per minute per IP (preview .png images are not limited).
- Optional free API key (https://codels.download/me/api-keys): 1200 / 6000 / 1200 per minute plus usage statistics. Send it as "Authorization: Bearer cdl_…" (or "X-Api-Key"), e.g. claude mcp add --transport http codels https://codels.download/mcp --header "Authorization: Bearer cdl_…"
- Responses carry X-RateLimit-Limit / X-RateLimit-Remaining; a 429 has Retry-After.

## Recommended workflow
1. Search with the API, pick the best match by title/tags/triangles.
2. Read https://codels.download/m/<slug>.md to see the preview and dimensions.
3. Save the .js module into the project (no extra dependencies besides 'three') and call the factory.
4. Scale/position it in the scene; models are already grounded at y = 0.

## Categories
- nature: Nature — nature/trees, nature/rocks, nature/plants, nature/terrain
- buildings: Buildings — buildings/houses, buildings/medieval, buildings/modern, buildings/structures, buildings/modular
- props: Props — props/furniture, props/containers, props/tools, props/lighting, props/decor
- vehicles: Vehicles — vehicles/cars, vehicles/aircraft, vehicles/watercraft, vehicles/space, vehicles/other
- characters: Characters — characters/humanoids, characters/animals, characters/creatures
- items: Items & Weapons — items/weapons, items/collectibles, items/consumables, items/equipment
- scifi: Sci-Fi — scifi/props, scifi/structures, scifi/robots
- urban: Urban & Street — urban/street, urban/traffic, urban/roads
- gamekit: Game Kit — gamekit/platforms, gamekit/hazards, gamekit/markers, gamekit/interactive
- space: Space — space/celestial, space/stations
- food: Food & Drink — food/fruits, food/meals, food/drinks