{"id":16344111,"url":"https://github.com/aaronjanse/marble-complete","last_synced_at":"2025-03-20T23:32:11.119Z","repository":{"id":109450031,"uuid":"102927845","full_name":"aaronjanse/marble-complete","owner":"aaronjanse","description":"Design a turing-complete marble run with ascii/unicode art","archived":false,"fork":false,"pushed_at":"2018-02-10T22:21:05.000Z","size":1238,"stargazers_count":54,"open_issues_count":1,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-17T18:53:50.048Z","etag":null,"topics":["ascii","asciidots","esolang","esoteric-language","marble-runs","marbles","turing-completeness"],"latest_commit_sha":null,"homepage":"https://ajanse.me/marble-complete/demo","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaronjanse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2017-09-09T04:51:34.000Z","updated_at":"2024-11-14T10:03:33.000Z","dependencies_parsed_at":"2023-04-11T06:18:04.778Z","dependency_job_id":null,"html_url":"https://github.com/aaronjanse/marble-complete","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronjanse%2Fmarble-complete","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronjanse%2Fmarble-complete/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronjanse%2Fmarble-complete/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronjanse%2Fmarble-complete/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronjanse","download_url":"https://codeload.github.com/aaronjanse/marble-complete/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244711410,"owners_count":20497411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["ascii","asciidots","esolang","esoteric-language","marble-runs","marbles","turing-completeness"],"created_at":"2024-10-11T00:26:54.825Z","updated_at":"2025-03-20T23:32:11.113Z","avatar_url":"https://github.com/aaronjanse.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MarbleComplete\n_Build and simulate your own turing-complete marble runs with ascii/unicode art_\n\nI have always had a love for mechanical computers. After reading a wonderful post on [turing-complete marble runs](https://nbickford.wordpress.com/2014/03/25/images-from-marble-runs-and-turing-machines/), I decided that I wanted to design a turing-complete marble tower. From this desire was born MarbleComplete, the 2d esolang for designing (turing-complete) marble runs using [AsciiDots](https://github.com/aaronduino/asciidots) syntax.\n\n[![Join the chat at https://gitter.im/marble-complete/Lobby](https://badges.gitter.im/marble-complete/Lobby.svg)](https://gitter.im/marble-complete/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n\u003ca class=\"anchor\" name=\"demo-gif\"\u003e\u003c/a\u003e\n[![Fun demo looks cool](https://raw.githubusercontent.com/aaronduino/marble-complete/master/demo.gif)](https://aaronduino.github.io/marble-complete/demo?code=%0A%20%20%20%20o%0A%20%20%20%20%7C%0A%2F---v---%5C%0A%7C%20%20%20%7C%20%20%20%7C%0A%3A.%2F-t-%5C%20%7C%0A%7C.%2B..%20%7C%20%7C%0A%7C%20%7C%20%20%20%7C%20%7C%0A%5E-t%20%20%20t-%2F%0A%7C%20.....%0Ao%0A)\n\nUnlike it's parent [AsciiDots](https://github.com/aaronduino/asciidots), the only logical operator in MarbleComplete is a _toggler_:\n\n![Turing Tumble Bit Piece](https://raw.githubusercontent.com/aaronduino/marble-complete/master/toggler.gif)\n\nThe Turing Tumble kickstarter has a [gif of the real life equivalent](https://ksr-ugc.imgix.net/assets/016/325/165/19cae5d12c1d7fbeb07222b17ac63909_original.gif?w=680\u0026fit=max\u0026v=1492659230\u0026auto=format\u0026gif-q=50\u0026q=92\u0026s=d6d2f74ec54534198f285ee2f0672606).\n\n## Running the Interpreter\n\nRun `python3 interpret.py --help` to read about available flags.\n\nFor the demo gif, I ran the interpreter in auto-stepped debug mode with a delay of 0.25 seconds. The code was prettified, too.\n\n```\npython3 interpret.py test.marbles -a 0.25 -d -p\n```\n\n## Documentation\n\n### Starting \u0026 Ending\nA starting marble is represented with a lowercase o (`o`).  \nProgram execution ends when a marble rolls over an ampersand (`\u0026`).\n\n### Comments\nEverything on a line after a pound symbol (`#`) is considered a comment and is ignored by the interpreter.\n\n```\n\u0026 # This text is a comment.\n```\n\n### Paths\nMarbles travel down paths (`|` or `-`):\n\n```\no # This is where the program starts\n| # The marble travels downwards\n| # Keep on going!\n\u0026 # The program ends\n```\n\nThink as these two paths as mirrors:  \n`/`  \n`\\`  \n\nYou can use them to make a path turn:\n\n```\n/-\u0026         # This is where the program ends!\n|\n\\-\\ /-\\\n  | | |\n/-/ | \\-\\\n\\---/   |\n        |\n        \\-o # Here's where the program starts\n```\n\n#### Special Paths\n`+` is the crossing of paths (they do not interact)\n\n`\u003e` acts like a regular, 2-way, horizontal, path, except marbles can be inserted into the path from the bottom or the top. Those marbles will go to the right\u003cbr\u003e\n`\u003c` does likewise except new marbles go to the left\u003cbr\u003e\n`^` (caret) does this but upwards\u003cbr\u003e\n`v` (the lowercase letter 'v') does likewise but downwards\n\nHere's a way to \"bounce\" a marble backwards along its original path using these symbols:\n\n```\n/-\u003e-- # Input/output comes through here\n| |\n\\-/\n```\n\nBut there's an easier way to do that:\n\n`(` reflects a marble backwards along its original path. It accepts marble coming from the left, and lets them pass through to the right\u003cbr\u003e\n`)` does likewise but for the opposite direction\n\n`*` duplicates a marble and distributes copies including the original marble to all attached paths except the origin of marble\n\nHere's a fun example of using these special paths. Don't worry—we'll soon be able to do more than just start then end a program.\n\n```\n  /-\\ /-\u0026 # End\n  | | |\n  \\-+-v\n    | | /-\\\n(-\u003c-/ | | |\n  |   \\-\u003c-/\n  \\-\\\n    |\n    o    # Start\n```\n\n## Togglers\n\nIf you want to create a toggler that starts learning _left_ (like \\\\), use a lowercase t (`t` -\u003e `↘`).  \nIf you want to create a toggler that starts learning _right_ (like /), use an uppercase T (`T` -\u003e `↙`).\n\nHere's a visualization of what a toggler does:\n\n![Toggler](https://raw.githubusercontent.com/aaronduino/marble-complete/master/toggler.gif)\n\n## Wires\n\nIn order to make togglers move in unison (thereby allowing turing-completeness), connect them with _wires_.\n\nIn ascii, wires are represented via periods (`.`). These can be automatically [prettified](#ascii-vs-unicode-source) into unicode lines (e.g. `┄`).\n\n## Gates\nMarbles can also be controlled via _gates_.  \nAn open gate is represented by a colon (`:`) and a closed gate is represented by an exclamation mark (`!`).\n\nA gate can be opened/closed via a pulse from a toggler down a connected wire.\n\nGates are useful when you want to control the order in which marbles move.\n\n## IO\nGetting input from stdin is very simple. Whenever a marble rolls onto a question mark (`?`), it reads one character from stdin. If that character is a `0`, the marble moves to the left, and if the character is a `1`, the marble  moves to the right. If the character read from std in is neither a `0` nor a `1`, an exception is thrown.\n\nExample:\n\n```\n  o\n  |\n/-?-\\\n|   |\n|   \\-- # the input was `1`\n|\n\\------ # the input was `0`\n```\n\nIf a wire activates a `1`, a `1` is printed to stdout. If a wire activates a `0`, a `0` is printed to stdout.  \n`0`'s and `1`'s are conductive, meaning that can act like wires.\n\n## Ascii vs Unicode source\nPrograms are typically written with AsciiDots' ascii path rules:\n\n```\n /---\n |\n |\n/t\\\n|.+..\n\\v/ .\n/t\\ .\n|.+./\n| |\n| *---\n| |\n| |\n| |\n```\n\n... And then translated into Unicode box drawings via `prettify.py`:\n\n```\n ╔═══\n ║    \n ║    \n╔↘╗   \n║╰+┄╮\n╚⇓╝ ┆\n╔↘╗ ┆\n║╰+┄╯\n║ ║   \n║ *══\n║ ║   \n║ ║   \n║ ║\n```\n\nPrettified code can always be re-asciified via `asciify.py`.\n\n# Sample Programs\n\nMemory Cell:\n\n```\n o\n |\n v----------------- # query\n |\n |     /----------- # set to 0\n |     |   /------- # set to 1\n |     |   |\n |     |   |    /-- # toggle\n |     v\\ /v    |\n/t\\   /t/ \\t\\  /t\\\n|.+.. |.   .|  |.|\n\\v/ ..+.....+..+.|\n/t\\ . |     |  | |\n|.+.. |     |  | \\-- # now 1\n| |   |     |  \\---- # now 0\n0 1\n```\n\nMemory tape:\n\n```\n           /v----o\n o     o   \\T\n |    \\v\\-\\ .\n |     !+.+.*\n/t\\    || | .\n|.+.. /T+-* .\n\\v/ ..+.| | .\n |  . | | | .\n/+\\ . *-+-v .\n||t.. | | | .\n\\+----+-+-/ .\n |    \\v\\-\\ .\n |     !+.+.*\n/t\\    || | .\n|.+.. /T+-* .\n\\v/ ..+.| | .\n |  . | | | .\n/+\\ . *-+-v .\n||t.. | | | .\n\\+----+-+-/ .\n |    \\v\\-\\ .\n```\n\n---\n\n\u003ca rel=\"license\" href=\"http://creativecommons.org/licenses/by-sa/4.0/\"\u003e\u003cimg alt=\"Creative Commons License\" style=\"border-width:0\" src=\"https://i.creativecommons.org/l/by-sa/4.0/88x31.png\" /\u003e\u003c/a\u003e\u003cbr /\u003eThis work is licensed under a \u003ca rel=\"license\" href=\"http://creativecommons.org/licenses/by-sa/4.0/\"\u003eCreative Commons Attribution-ShareAlike 4.0 International License\u003c/a\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronjanse%2Fmarble-complete","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronjanse%2Fmarble-complete","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronjanse%2Fmarble-complete/lists"}