{"id":50337351,"url":"https://github.com/fdb/karl-sims-recreated","last_synced_at":"2026-05-29T14:30:47.045Z","repository":{"id":349117159,"uuid":"1201061346","full_name":"fdb/karl-sims-recreated","owner":"fdb","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-04T09:59:45.000Z","size":1218,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T10:25:35.525Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fdb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-04T06:43:40.000Z","updated_at":"2026-04-04T09:59:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fdb/karl-sims-recreated","commit_stats":null,"previous_names":["fdb/karl-sims-recreated"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/fdb/karl-sims-recreated","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fdb%2Fkarl-sims-recreated","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fdb%2Fkarl-sims-recreated/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fdb%2Fkarl-sims-recreated/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fdb%2Fkarl-sims-recreated/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fdb","download_url":"https://codeload.github.com/fdb/karl-sims-recreated/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fdb%2Fkarl-sims-recreated/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33657690,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-29T14:30:45.691Z","updated_at":"2026-05-29T14:30:47.034Z","avatar_url":"https://github.com/fdb.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Evolving Virtual Creatures\n\nA recreation of Karl Sims' [\"Evolving Virtual Creatures\"](https://www.karlsims.com/papers/siggraph94.pdf) (SIGGRAPH 1994) in Rust + WebGPU.\n\nCreatures are built from directed graphs of 3D rectangular solids connected by joints. Both their morphology (body plan) and neural control systems are co-evolved using genetic algorithms. Fitness is evaluated via physics simulation — creatures that swim faster toward a target survive and reproduce.\n\n![Swimming Starfish](screenshots/m3-swimming-starfish.png)\n\n## Architecture\n\n```\nkarl-sims-recreated/\n├── core/       # Physics, genetics, brain, simulation (Rust, compiles to native + WASM)\n├── server/     # Evolution server with SQLite, REST API, WebSocket (Rust, tokio + axum)\n├── web/        # wgpu WebGPU renderer + WASM bindings (Rust → WASM)\n└── frontend/   # React + TypeScript dashboard UI\n```\n\n**Core** compiles to both native (for server-side fitness evaluation) and WASM (for browser rendering). All math uses `glam` with `scalar-math` for cross-platform floating-point determinism.\n\n## Prerequisites\n\n- [Rust](https://rustup.rs/) (1.85+, edition 2024)\n- [wasm-pack](https://rustwasm.github.io/wasm-pack/installer/) (0.14+)\n- [Node.js](https://nodejs.org/) (20+)\n- WASM target: `rustup target add wasm32-unknown-unknown`\n\n## Quick Start\n\n### Browser viewer (no server)\n\n```bash\n./dev.sh\n```\n\nOpens the 3D viewer at `http://localhost:5173` with demo scenes: starfish, hinged pair, universal/spherical joints, swimming starfish (water physics), random creature (brain-driven), and mini evolution (in-browser).\n\n### Server-side evolution\n\n**1. Start the server:**\n\n```bash\ncargo run --release -p karl-sims-server\n```\n\nStarts 8 parallel workers + HTTP server on `http://localhost:3000`.\n\n**2. Start an evolution:**\n\n```bash\ncurl -X POST http://localhost:3000/api/evolutions \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"population_size\": 100}'\n```\n\n**3. Monitor progress:**\n\n```bash\n# Check status\ncurl http://localhost:3000/api/evolutions/1\n\n# Get best creatures\ncurl http://localhost:3000/api/evolutions/1/best\n\n# Stop evolution\ncurl -X POST http://localhost:3000/api/evolutions/1/stop\n```\n\nOr open the frontend dashboard (run `./dev.sh` in another terminal) for a visual UI with live fitness charts.\n\n## API\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/api/evolutions` | List all evolution runs |\n| `POST` | `/api/evolutions` | Start a new evolution |\n| `GET` | `/api/evolutions/:id` | Get evolution status |\n| `GET` | `/api/evolutions/:id/best` | Get top 10 creatures |\n| `POST` | `/api/evolutions/:id/stop` | Stop a running evolution |\n| `WS` | `/api/live` | WebSocket stream of generation stats |\n\n## How It Works\n\n### Genotype\n\nA directed graph where nodes describe rigid body parts (dimensions, joint type, neural circuit) and edges describe connections (attachment face, scale, reflection). The graph can be recursive — a node connecting to itself produces repeated limbs.\n\n### Phenotype Development\n\nThe graph is traversed from the root node, creating 3D bodies connected by joints. Each node's local neural graph is instantiated per body part. Seven joint types: rigid, revolute, twist, universal, bend-twist, twist-bend, spherical.\n\n### Neural Brain\n\nA dataflow graph evaluated twice per physics timestep. Six neuron functions: sum, product, sigmoid, sin, oscillate-wave (time-varying), memory. Inputs come from joint angle sensors and photosensors (for light following). Outputs drive joint torques, clamped by cross-sectional area.\n\n### Physics Engine\n\nCustom deterministic engine (no Rapier):\n\n- **Featherstone's O(N) Articulated Body Algorithm** with floating-base support for free-swimming creatures\n- **RK4-Fehlberg** adaptive integration (4th order, deterministic step adaptation)\n- **Viscous water drag** — per-face force opposing normal velocity, proportional to area\n- **OBB collision detection** — AABB broad phase + 15-axis SAT narrow phase, penalty spring response\n\n### Genetic Algorithm\n\n- **Population**: 300 (configurable), 1/5 survival ratio\n- **Reproduction**: 40% asexual (copy + mutate), 30% crossover, 30% grafting\n- **Mutation**: 5 operators — node parameter perturbation, random node addition, connection mutation, connection add/remove, garbage collection\n- **Selection**: roulette wheel weighted by fitness\n\n### Fitness\n\n- **Swimming speed**: distance traveled through water per unit time, with anti-circling and continuing-movement bonuses\n- **Following**: average speed toward a repositioning light source across multiple trials (uses photosensors)\n\n## Project Structure\n\n```\ncore/src/\n├── spatial.rs       # 6D spatial algebra (SVec6, SMat6, SXform)\n├── featherstone.rs  # Articulated Body Algorithm (3-pass ABA)\n├── body.rs          # Rigid body (mass, inertia, face geometry)\n├── joint.rs         # 7 joint types with spatial kinematics\n├── world.rs         # Physics world with RK45 + water + collisions\n├── genotype.rs      # Directed graph genome with nested brain graphs\n├── phenotype.rs     # Grow genotype → physics world\n├── brain.rs         # Neural dataflow graph evaluation\n├── creature.rs      # Creature = genome + world + brain\n├── mutation.rs      # 5 mutation operators\n├── mating.rs        # Crossover + grafting\n├── fitness.rs       # Swimming + following fitness evaluation\n├── evolution.rs     # Population management + selection\n├── water.rs         # Viscous drag model\n├── collision.rs     # OBB detection + penalty response\n└── integrator.rs    # RK4-Fehlberg adaptive integrator\n```\n\n## Tests\n\n```bash\ncargo test -p karl-sims-core\n```\n\n78 tests covering spatial algebra, Featherstone dynamics, joint kinematics, water drag, collision detection, genotype generation, phenotype development, brain evaluation, mutation, mating, fitness evaluation, and evolution.\n\n## References\n\n- Sims, K. \"Evolving Virtual Creatures.\" SIGGRAPH 1994.\n- Featherstone, R. *Rigid Body Dynamics Algorithms*. Springer, 2008.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffdb%2Fkarl-sims-recreated","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffdb%2Fkarl-sims-recreated","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffdb%2Fkarl-sims-recreated/lists"}