[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-105281":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":15,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":16,"rankGlobal":10,"rankLanguage":10,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":18,"hasPages":20,"topics":21,"createdAt":10,"pushedAt":10,"updatedAt":25,"readmeContent":26,"aiSummary":10,"trendingCount":15,"starSnapshotCount":15,"syncStatus":27,"lastSyncTime":28,"discoverSource":29},105281,"threejs-procedural-animals","majidmanzarpour\u002Fthreejs-procedural-animals","majidmanzarpour","Fully procedural animals for three.js: sculpted from SDFs, auto-rigged and skinned, with fur, feathers and scales, and IK gaits and actions. No models, no textures, no animation clips.","https:\u002F\u002Fmajidmanzarpour.github.io\u002Fthreejs-procedural-animals\u002F",null,"JavaScript",53,8,52,0,38.86,"MIT License",false,"main",true,[22,23,24],"procedural","procedural-generation","threejs","2026-11-01 00:13:23","# three.js Procedural Animals\n\n**[Live showcase](https:\u002F\u002Fmajidmanzarpour.github.io\u002Fthreejs-procedural-animals\u002F)** · [Repository](https:\u002F\u002Fgithub.com\u002Fmajidmanzarpour\u002Fthreejs-procedural-animals) · \u003C!-- demo video link -->\n\n24 animals for three.js, generated entirely in code: no models, no textures, no animation clips.\nCall `createAnimal('wolf')`, add it to your scene and steer it.\n\n- **24 species, 6 body plans:** paws, hooves, birds, swimmers, snakes, spiders (plus hoppers). Breeds,\n  coats and morphs, both sexes, young animals.\n- **Built at runtime:** sculpted from signed distance fields, meshed, rigged, skinned\n  (dual-quaternion), covered in fur, feathers or scales, and animated with IK gaits and actions.\n- **Seeded individuals:** `seed` picks a repeatable animal with its own size, proportions and coat.\n- **From close-ups to crowds:** five quality tiers, from `hero` (~120k vertices) to `crowd`\n  (~6k vertices, one draw call).\n- **Off the main thread:** builds run in Web Workers, or bake individuals offline for instant loading.\n\n## Install\n\n```sh\nnpm install procedural-animals three\n# until it is published on npm:\nnpm install github:majidmanzarpour\u002Fthreejs-procedural-animals three\n```\n\nthree.js r160+ is the only (peer) dependency. Plain ES modules with TypeScript declarations.\n\n## Quickstart\n\n```js\nimport * as THREE from 'three';\nimport { createAnimal } from 'procedural-animals';\n\nconst renderer = new THREE.WebGLRenderer({ antialias: true });\nrenderer.setSize(innerWidth, innerHeight);\nrenderer.shadowMap.enabled = true;\ndocument.body.appendChild(renderer.domElement);\n\nconst scene = new THREE.Scene();\nscene.background = new THREE.Color(0xa9c1e0);\nconst camera = new THREE.PerspectiveCamera(40, innerWidth \u002F innerHeight, 0.1, 500);\ncamera.position.set(6, 3, 8);\nconst sun = new THREE.DirectionalLight(0xfff3e4, 2.7);\nsun.position.set(6, 10, 4);\nsun.castShadow = true;\nscene.add(sun, new THREE.HemisphereLight(0xdde6f2, 0x5f5a52, 1.15));\nconst floor = new THREE.Mesh(new THREE.PlaneGeometry(200, 200).rotateX(-Math.PI \u002F 2), new THREE.MeshStandardMaterial({ color: 0x77736a }));\nfloor.receiveShadow = true;\nscene.add(floor);\n\nasync function main() {\n  const wolf = await createAnimal('wolf', { seed: 3, quality: 'high' });\n  scene.add(wolf.object); \u002F\u002F don't move wolf.object yourself: the animal moves itself\n\n  let last = performance.now();\n  renderer.setAnimationLoop((now) => {\n    const dt = (now - last) \u002F 1000; \u002F\u002F seconds\n    last = now;\n    wolf.move({ speed: wolf.gears.walk, heading: now \u002F 1000 * 0.3 }); \u002F\u002F m\u002Fs, radians\n    wolf.update(dt); \u002F\u002F once per frame\n    camera.lookAt(wolf.position);\n    renderer.render(scene, camera);\n  });\n}\nmain(); \u002F\u002F no top-level await in the entry module (it can deadlock a Vite production build)\n```\n\nThen:\n\n```js\nwolf.moveTo(new THREE.Vector3(10, 0, 4), { speed: 3 }); \u002F\u002F walk there, emits 'arrive'\nwolf.follow(body.position, body.velocity);                \u002F\u002F or follow your physics body, every frame\nwolf.lookAt(player.position);                             \u002F\u002F null to stop\nawait wolf.play('attack');                                \u002F\u002F 'done' | 'interrupted' | 'stopped' | 'refused'\nwolf.on('footstep', (e) => sfx.play('step', e.position, e.strength));\nwolf.on('attackHit', (e) => damage(e.position, e.direction));\nwolf.dispose();                                           \u002F\u002F free GPU resources, remove from the scene\n```\n\n### Web Workers\n\n`createAnimal` builds in module workers by default and falls back to the calling thread where\n`Worker` doesn't exist. With **Vite**:\n\n```js\n\u002F\u002F vite.config.js\nexport default {\n  worker: { format: 'es' },\n  build: { target: 'es2022' },\n  optimizeDeps: { exclude: ['procedural-animals'] },\n};\n```\n\nwebpack 5 and Parcel 2 need no setup. For other bundlers, bundle the worker yourself and install it:\n\n```sh\nnpx esbuild node_modules\u002Fprocedural-animals\u002Fsrc\u002Fworker.js --bundle --format=iife --minify --outfile=public\u002Fanimal-worker.js\n```\n\n```js\nimport { setWorkerFactory } from 'procedural-animals';\nsetWorkerFactory(() => new Worker('\u002Fanimal-worker.js'));\n```\n\n`createAnimal(id, { worker: false })` builds on the calling thread (blocks for the build time).\n\n### Baking (instant loading)\n\nA build takes 0.4-6 s. Bake individuals ahead of time into `.animal` files and load them in ~20 ms:\n\n```sh\nnpx procedural-animals-bake wolf --seed 3 --quality high -o public\u002Fwolf-3.animal\n```\n\n```js\nconst wolf = await createAnimal('wolf', { baked: fetch('\u002Fwolf-3.animal').then((r) => r.arrayBuffer()) });\n```\n\n## API\n\n```js\nimport { createAnimal, listSpecies, loadSpecies, setWorkerFactory, clearBuildCache, QUALITY } from 'procedural-animals';\n```\n\n**`createAnimal(species, options)`** (every option is optional)\n\n| option | default | meaning |\n| --- | --- | --- |\n| `seed` | `1` | the individual (size, proportions, coat; sex, age and variant unless given) |\n| `quality` | `'high'` | `'hero' \\| 'high' \\| 'medium' \\| 'low' \\| 'crowd'` |\n| `variant`, `sex`, `age` | by seed | breed \u002F coat \u002F morph; `'male' \\| 'female'`; `'adult' \\| 'juvenile'` |\n| `ground` | `() => 0` | `(x, z) => y` terrain height, in the space of `animal.object.parent` |\n| `water` | none | `(x, z) => y \\| null` water surface (swimmers need it; land animals drink and wade) |\n| `perches` | `[]` | `Vector3[]` points birds can fly to |\n| `position`, `heading` | origin, `0` | start pose (heading in radians, `0` faces +Z) |\n| `baked` | none | an `ArrayBuffer` (or a Promise of one) from a `.animal` file |\n| `worker` | `true` | `false` builds on this thread |\n| `castShadow`, `receiveShadow` | `true` | |\n\n**The animal**\n\n| member | meaning |\n| --- | --- |\n| `object` | the `Object3D` to add to your scene (keep its transform at identity) |\n| `update(dt)` | advance `dt` seconds; call once per frame |\n| `move({ speed, heading })`, `stop()`, `moveTo(point, { speed })`, `follow(pos, vel)` | locomotion; the animal picks its gait |\n| `lookAt(target)` | track a `Vector3` with the head |\n| `play(action, opts)`, `stopAction(name)` | actions; `play` returns a Promise |\n| `on(event, fn)`, `off(event, fn)` | events: `footstep`, `attackHit`, `actionStart`, `actionEnd`, `arrive`, `takeoff`, `land`, `death`, `vocalize`, `wingbeat` |\n| `setQuality(tier)`, `setLod(0 \\| 1 \\| 2)` | coat detail on the existing mesh; motion detail for crowds |\n| `setDebug(mode, on)`, `setCoverings(on)` | `'albedo' \\| 'weights' \\| 'material' \\| 'bare'`; fur shells on\u002Foff |\n| `position`, `heading`, `speed`, `velocity`, `state` | current motion state (read only) |\n| `gears`, `gaits`, `actions` | this individual's named speeds (m\u002Fs), gaits and actions |\n| `attachments` | `mouth`, `head`, `back` (+ bird feet, horse `seat` \u002F stirrups \u002F bits) to parent props to |\n| `dispose()` | free everything |\n\n**Actions:** every species has `jump`, `sit`, `lie`, `sleep`, `eat`, `drink`, `attack`, `hit`,\n`death` and `stand`. Birds add `takeoff`, `land`, `perch`, `glide`, `flap`; swimmers `burst`;\nsnakes `coil`, `strike`; hoppers `hop`; many species add their own (see below).\n\n**Quality tiers**\n\n| tier | vertices | use |\n| --- | ---: | --- |\n| `hero` | 110-130k | cinematic close-ups |\n| `high` | 65-80k | the player's animal (default) |\n| `medium` | 25-32k | mid distance, phones |\n| `low` | 11-15k | herds of 10-20 |\n| `crowd` | 5-8k | crowds of 100 (with `setLod(2)`), one draw call |\n\nBuilds are cached by species, seed, quality and variant, so a herd of 100 from 6 seeds builds 6 times.\nCPU cost is ~0.1 ms per animal per frame.\n\nThe complete reference (every option, event payload, state field and recipe) is in\n[llms.txt](llms.txt), and the types are in [src\u002Findex.d.ts](src\u002Findex.d.ts).\n\n## Species\n\n| id | plan | variants | extra actions |\n| --- | --- | --- | --- |\n| `wolf` | paws | grey, black, pale, tawny | snarl \u002F howl body language |\n| `dog` | paws | shepherd, retriever, terrier | greet, playbow, sniff, dig |\n| `fox` | paws | red, cross, silver, urban | pounce, listen |\n| `cat` | paws | mackerel, classic, ginger, black, tuxedo, calico, grey | loaf, groom, knead, stalk, slowblink |\n| `lion` | paws | tawny, white | roar, yawn |\n| `cheetah` | paws | | sprint gait |\n| `bear` | paws | eurasian, grizzly, coastal, black | standup, sniff, dig |\n| `rat` | paws | wild, agouti, dark, albino, hooded | rear, groom, scurry, box |\n| `rabbit` | hopper | wild, domestic, fawn, black, white, dutch, lop, ... | hop, binky, groom, periscope, thump, flee |\n| `horse` | hooves | bay, darkbay, chestnut, black, grey, palomino, dun, buckskin | rideable (`seat`, stirrups) |\n| `deer` | hooves | summer, winter | stomp, alert, flee |\n| `cow` | hooves | holstein, hereford, angus, jersey, highland | lick, chew, moo, swish, shake |\n| `pig` | hooves | largewhite, landrace, duroc, hampshire, berkshire, spotted | wallow, grunt, sniff, root, frolic |\n| `sheep` | hooves | whiteface, suffolk, merino, black, shorn | alert, bleat, headshake, stamp, pronk |\n| `goat` | hooves | saanen, alpine, pied, nubian, boer | browse, bleat, headshake, paw |\n| `boar` | hooves | adult, yearling, piglet | sniff, grunt, headshake |\n| `frog` | hopper | bullfrog, bullfrog-pale, common-frog | hop, croak, blink |\n| `chicken` | bird | red, leghorn, australorp, barred, buff, speckled | rooster, chick |\n| `crow` | bird | american, carrion, hooded | |\n| `eagle` | bird | bald, golden | |\n| `fish` | swimmer | trout, goldfish, clownfish, bluegill | burst |\n| `shark` | swimmer | white, blacktip | burst |\n| `snake` | snake | corn, rattlesnake | coil, strike |\n| `spider` | spider | wolf, tarantula | |\n\nImport one species directly to bundle only it: `import wolf from 'procedural-animals\u002Fspecies\u002Fwolf'`\nand `createAnimal(wolf, { seed: 3 })`. String ids load species on demand.\n\n## For AI agents\n\nRead [llms.txt](llms.txt) (complete, dense reference) and [src\u002Findex.d.ts](src\u002Findex.d.ts). The contract:\n\n1. `const a = await createAnimal(id, { seed, quality, ground, position, heading })` inside an `async` function\n2. `scene.add(a.object)` and never transform `a.object` yourself\n3. steer with `a.move({ speed, heading })`, `a.moveTo(point)` or `a.follow(pos, vel)` every frame\n4. `a.play(action)` for actions\n5. `a.update(dt)` once per frame with `dt` in **seconds**; `a.dispose()` when done\n\nUnits: metres, seconds, radians, +Y up, heading `0` faces +Z (`Math.atan2(dx, dz)` faces a point).\nRead speeds from `a.gears` (names differ per species). `ground` must match the terrain you draw.\nSwimmers need `water` and a start position below the surface.\n\n## Showcase\n\nThe [live showcase](https:\u002F\u002Fmajidmanzarpour.github.io\u002Fthreejs-procedural-animals\u002F) shows every\nspecies, variant and action, with debug views (skeleton, IK, SDF primitives, skin weights) and a\n\"use in your game\" panel that writes the code for the animal on screen. Add `?demo` for the\ntwo-minute reel.\n\n```sh\nnpm install\nnpm run build:showcase   # dist\u002Fshowcase.html\nnpm run build:pages      # dist\u002Fpages\u002F, deployed to GitHub Pages by .github\u002Fworkflows\u002Fpages.yml\nnode showcase\u002Frecord.mjs # render the demo reel to MP4 (needs Chromium and ffmpeg)\n```\n\n## Contributing\n\n[docs\u002FAUTHORING.md](docs\u002FAUTHORING.md) explains how a species is built and checked.\n\n```sh\nnpm test                                   # every species builds, moves and plays every action\nnode tools\u002Fmetrics.mjs \u003Cid> --seeds 1-4    # motion, skin and performance checks (tools\u002Fthresholds.json)\nnode tools\u002Frender.mjs \u003Cid> --views turntable,gaits,face,actions\nnode tools\u002Fcompare.mjs \u003Cid>                # renders beside your local reference photos\n```\n\nThe browser tools need Chromium (`npx playwright-core install chromium`).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",2,"2026-10-31 04:26:18","CREATED_QUERY"]