SP-CellBots – A Simulator for Programmable Matter

Sven Pohl B.Sc. sven.pohl@zen-systems.de — MIT License © 2026
This project is licensed under the MIT License.

SP-CellBots is an open simulation and control system for programmable matter.
It 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 structures.

⚠️ Note: The term "CellBots" is used here in a descriptive, non-commercial context and is not affiliated with any external research groups or trademarks.

„Morph. Code. Forge.“

AI-generated CellBot concept Image generated with OpenAI (ChatGPT/DALL·E)

WebGUI BotController (Screenshot)

Animated Blender export (Rendering)

---

📚 Contents

• Description
• Installation & Quickstart
• CellBot Protocol and OP-Codes
• CellBot Hardware Blueprint (Virtual)
• Direct Radio
• Usage & Examples
• API
• Morphing
• Blender Replay and Animation
• Tools (Scripts)
• Vision & Future Applications
• Research Notes

---

🧩 Version

Current version: 1.6
Developed and tested on Node.js v23.11.0.
Due to rapid ecosystem changes, newer or older versions may cause incompatibilities.

Latest changes:

• 1.6 (18.04.2026)
  Direct-Radio transition layer and API architecture refactor

  • Added preparation for a simpler hardware transition path with direct radio communication (communication_mode = direct_radio) while keeping mesh_opcode as default reference mode
  • Added configurable Radio IDs (rid) and static radio mapping flow for direct addressing in both ClusterSim and BotController
  • 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
  • Refactored BotController API implementation from a monolithic botcontroller_class.js block into structured runtime/service modules for better maintainability and faster extension
  • 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
  • Added dedicated documentation chapter: Direct Radio
  • LLM testing and interactive API control during this phase were performed with Codex GPT-5.4

• 1.5 (04.04.2026)
  API V1 becomes practically usable

  • Expanded the BotController API into a much more complete control layer for humans, scripts, and LLM tooling
  • Added high-level transport helpers such as move_carrier_to and diagnose_move_carrier_to
  • Added small Morph API building blocks such as morph_get_structures, morph_get_algos, morph_start, and morph_check_progress
  • Improved payload-aware path planning, payload synchronization after carrier rotations, and bundled rotation execution with cleaner ACK routing
  • Extended diagnostics and recovery behavior around MOVE planning, payload transport, and morph progress tracking
  • Fixed several smaller consistency and simulator/controller sync issues discovered during direct LLM-driven testing
  • LLM testing and interactive API control during this phase were performed with Codex GPT-5.4

👉 Full changelog is available at:
➡️ docs/changelog.md

---

📖 How to cite

If you use SP-CellBots in your work, please cite one (or both) of the following:

• Software (GitHub / CITATION.cff):
  Use the repository citation metadata (GitHub “Cite this repository” / CITATION.cff).
• Paper (Zenodo DOI):
  https://doi.org/10.5281/zenodo.19509605

---

🚧 Planned Features

• Decentralized AntMorph algorithm (planned):
  A lightweight, swarm-based morphing system is in development, inspired by ant behavior.
  Bots will attempt to fill free target positions without global coordination, based on local visibility and optional heuristics (e.g., cluster center proximity).
  Goal: support fast and distributed formation of arbitrary patterns in constrained environments.

---

🤝 Contributing

Pull requests are welcome!

💛 Support / Donate

If you enjoy this project and want to support ongoing development, feel free to send a Bitcoin donation to:

BTC address:
'bc1qr49kr0cn92wmtne4tasdqe9qzfhj0jqvpxjhha'

"If you’d like to say thanks: Even a few sats are appreciated!"

🙏 Thank you!

---

📬 Feedback welcome
If you're experimenting with CellBots or building something on top of it, I'd love to hear from you.
Even a short message helps with motivation and future planning.

Feel free to drop a quick note to:
'sven.pohl@zen-systems.de'