{"id":30067469,"url":"https://github.com/svenpohl/sp-cellbots","last_synced_at":"2026-04-29T22:00:57.767Z","repository":{"id":305339109,"uuid":"1022628704","full_name":"svenpohl/sp-cellbots","owner":"svenpohl","description":"ClusterSim and BotController simulate protocol and control logic for CellBots – a framework for programmable matter.","archived":false,"fork":false,"pushed_at":"2026-04-28T04:23:33.000Z","size":8869,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T06:14:33.576Z","etag":null,"topics":["3d-visualization","blender","javascript","morphing","nodejs","programmable-matter","robotics","simulation","sp-cellbots","threejs","webgl"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/svenpohl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","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":"2025-07-19T13:38:59.000Z","updated_at":"2026-04-28T04:11:53.000Z","dependencies_parsed_at":"2025-08-08T09:03:12.538Z","dependency_job_id":"d182f57b-293b-4b3c-b83b-c96f0e2970ff","html_url":"https://github.com/svenpohl/sp-cellbots","commit_stats":null,"previous_names":["svenpohl/cellbots"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/svenpohl/sp-cellbots","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svenpohl%2Fsp-cellbots","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svenpohl%2Fsp-cellbots/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svenpohl%2Fsp-cellbots/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svenpohl%2Fsp-cellbots/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/svenpohl","download_url":"https://codeload.github.com/svenpohl/sp-cellbots/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svenpohl%2Fsp-cellbots/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32445555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T20:22:27.477Z","status":"ssl_error","status_checked_at":"2026-04-29T20:22:26.507Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["3d-visualization","blender","javascript","morphing","nodejs","programmable-matter","robotics","simulation","sp-cellbots","threejs","webgl"],"created_at":"2025-08-08T09:01:14.734Z","updated_at":"2026-04-29T22:00:57.762Z","avatar_url":"https://github.com/svenpohl.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SP-CellBots – A Simulator for Programmable Matter\n\nSven Pohl B.Sc. \u003csven.pohl@zen-systems.de\u003e — MIT License © 2026  \nThis project is licensed under the [MIT License](./LICENSE).\n\n**SP-CellBots** is an open simulation and control system for programmable matter.  \nIt is based on a fictional hardware model: the **SP-CellBot**, a modular unit capable of moving across identical elements, stacking, and forming fixed connections in order to *morph* into arbitrary \nstructures. \n\n\u003e ⚠️ Note: The term \"CellBots\" is used here in a descriptive, non-commercial context and is not affiliated with any external research groups or trademarks.\n\n\u003cdiv align=\"center\"\u003e\u003cstrong\u003e„Morph. Code. Forge.“\u003c/strong\u003e\u003c/div\u003e\n\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"docs/img/ai_cellbot.png\" width=\"180\"/\u003e\u003cbr\u003e\n      \u003csub\u003e\n        AI-generated CellBot concept\u003cbr\u003e\n        \u003csup\u003e\u003ci\u003eImage generated with OpenAI (ChatGPT/DALL·E)\u003c/i\u003e\u003c/sup\u003e\n      \u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"docs/img/webgui.png\" width=\"180\"/\u003e\u003cbr\u003e\n      \u003csub\u003e\n        WebGUI BotController\u003cbr\u003e\n        \u003csub\u003e(Screenshot)\u003c/sub\u003e\n      \u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"docs/img/stick_figure_blender.png\" width=\"180\"/\u003e\u003cbr\u003e\n      \u003csub\u003e\n        Animated Blender export\u003cbr\u003e\n        \u003csub\u003e(Rendering)\u003c/sub\u003e\n      \u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 📚 Contents\n\n- [Description](docs/description.md)  \n- [Installation \u0026 Quickstart](docs/install.md)  \n- [CellBot Protocol and OP-Codes](docs/protocol.md)  \n- [CellBot Hardware Blueprint (Virtual)](docs/hardware_blueprint.md)  \n- [Direct Radio](docs/direct_radio.md)  \n- [Usage \u0026 Examples](docs/usage.md)  \n- [API](docs/api.md)  \n- [Morphing](docs/morphing.md)  \n- [Blender Replay and Animation](docs/blender.md)  \n- [Tools (Scripts)](docs/tools.md)  \n- [Vision \u0026 Future Applications](docs/vision.md)\n- [Research Notes](docs/research.md)\n\n---\n\n\n\n## 🧩 Version\n\nCurrent version: **1.7.1**  \nDeveloped and tested on **Node.js v23.11.0**.  \nDue to rapid ecosystem changes, newer or older versions may cause incompatibilities.\n\nLatest changes:\n\n- **1.7.1** (29.04.2026)  \n**VoxelEdit integration**\n  - Added `tools/voxeledit/` – a standalone 3D voxel editor for SP-CellBots\n  - Three.js-based editor with Construct (XML), Structure (JSON), and Overlay modes\n  - Place, delete, rename, and visually edit bot positions in a 3D viewport\n  - Separate target-file workflow for TRGT markers\n  - Express server on port 5175, start with `cd tools/voxeledit \u0026\u0026 node server.js`\n\n- **1.7** (28.04.2026)  \n**Vehicle Kinematics mobility mode (preview)**\n  - Added `mobility_mode = vehicle_kinematics` as the new default mode (preview)\n  - In this mode, SP-CellBots can only drive forward/backward in a straight line, and can climb walls/stairs only in that direction — path planning accounts for this constraint\n  - Mode is currently only active for the LLM-facing API command `move_bot_to` (NOT for morphing)\n  - Goal: preparation for simpler, more realistic hardware as a stepping stone toward `full_edge` mobility\n  - Primary demo: `node api.js structurescan` + `node api.js move_bot_to B26 5 2 4 0 0 -1`\n  - Test batch sequence: `node api.js batch ./tests/batch02.json`\n  - Additional changes: minor bugfixes and sequential batch processing in `api.js`\n\n- **1.6** (18.04.2026)  \n**Direct-Radio transition layer and API architecture refactor**\n  - Added preparation for a simpler hardware transition path with **direct radio communication** (`communication_mode = direct_radio`) while keeping `mesh_opcode` as default reference mode\n  - Added configurable **Radio IDs (`rid`)** and static radio mapping flow for direct addressing in both ClusterSim and BotController\n  - Introduced and documented the new **NBH / RNBH OP-codes** for direct-radio neighborhood discovery, enabling precise bot relocalization (position/orientation sync) without mesh route addressing\n  - Refactored BotController API implementation from a monolithic `botcontroller_class.js` block into structured runtime/service modules for better maintainability and faster extension\n  - Migrated and stabilized core API command paths for `direct_radio`, including scan, level-2 scan, movement, rotation, targeted resync (`search_bot`), and crater build/fill execution flows\n  - Added dedicated documentation chapter: **[Direct Radio](docs/direct_radio.md)**\n  - LLM testing and interactive API control during this phase were performed with **Codex GPT-5.4**\n\n- **1.5** (04.04.2026)  \n**API V1 becomes practically usable**\n  - Expanded the BotController API into a much more complete control layer for humans, scripts, and LLM tooling\n  - Added high-level transport helpers such as **`move_carrier_to`** and **`diagnose_move_carrier_to`**\n  - Added small Morph API building blocks such as **`morph_get_structures`**, **`morph_get_algos`**, **`morph_start`**, and **`morph_check_progress`**\n  - Improved payload-aware path planning, payload synchronization after carrier rotations, and bundled rotation execution with cleaner ACK routing\n  - Extended diagnostics and recovery behavior around MOVE planning, payload transport, and morph progress tracking\n  - Fixed several smaller consistency and simulator/controller sync issues discovered during direct LLM-driven testing\n  - LLM testing and interactive API control during this phase were performed with **Codex GPT-5.4**\n\n👉 Full changelog is available at:  \n➡️ [docs/changelog.md](docs/changelog.md)\n\n---\n\n## 📖 How to cite\n\nIf you use SP-CellBots in your work, please cite one (or both) of the following:\n\n- **Software (GitHub / CITATION.cff):**  \n  Use the repository citation metadata (GitHub “Cite this repository” / `CITATION.cff`).\n- **Paper (Zenodo DOI):**  \n  [https://doi.org/10.5281/zenodo.19509605](https://doi.org/10.5281/zenodo.19509605)\n\n---\n\n## 🚧 Planned Features\n\n- **Decentralized AntMorph algorithm (planned):**  \n  A lightweight, swarm-based morphing system is in development, inspired by ant behavior.  \n  Bots will attempt to fill free target positions without global coordination, based on local visibility and optional heuristics (e.g., cluster center proximity).  \n  Goal: support fast and distributed formation of arbitrary patterns in constrained environments.\n\n\n---\n\n## 🤝 Contributing\n\nPull requests are welcome!\n\n\n## 💛 Support / Donate\n\nIf you enjoy this project and want to support ongoing development, feel free to send a Bitcoin donation to:\n\n**BTC address:**  \n'bc1qr49kr0cn92wmtne4tasdqe9qzfhj0jqvpxjhha'\n\n\u003e *\"If you’d like to say thanks: Even a few sats are appreciated!\"*\n\n🙏 Thank you!\n\n---\n\n📬 **Feedback welcome**  \nIf you're experimenting with CellBots or building something on top of it, I'd love to hear from you.  \nEven a short message helps with motivation and future planning.\n\nFeel free to drop a quick note to:  \n'sven.pohl@zen-systems.de'\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvenpohl%2Fsp-cellbots","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsvenpohl%2Fsp-cellbots","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvenpohl%2Fsp-cellbots/lists"}