{"id":21064057,"url":"https://github.com/luochen1990/smart-turtle","last_synced_at":"2025-05-16T02:32:20.942Z","repository":{"id":30959625,"uuid":"34517763","full_name":"luochen1990/smart-turtle","owner":"luochen1990","description":"High level APIs for Turtle robot in ComputerCraft","archived":false,"fork":false,"pushed_at":"2020-05-20T02:34:10.000Z","size":787,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-03T18:52:48.301Z","etag":null,"topics":["lua","minecraft"],"latest_commit_sha":null,"homepage":"","language":"Lua","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/luochen1990.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-24T12:35:40.000Z","updated_at":"2022-04-19T23:54:44.000Z","dependencies_parsed_at":"2022-09-06T09:22:33.736Z","dependency_job_id":null,"html_url":"https://github.com/luochen1990/smart-turtle","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/luochen1990%2Fsmart-turtle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luochen1990%2Fsmart-turtle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luochen1990%2Fsmart-turtle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luochen1990%2Fsmart-turtle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luochen1990","download_url":"https://codeload.github.com/luochen1990/smart-turtle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254456059,"owners_count":22074088,"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":["lua","minecraft"],"created_at":"2024-11-19T17:48:09.378Z","updated_at":"2025-05-16T02:32:17.527Z","avatar_url":"https://github.com/luochen1990.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"Smart Turtle\n============\n\nThis script provide high level APIs for turtle robot in [ComputerCraft mod for Minecraft](https://github.com/dan200/ComputerCraft).\n\nYou can access the [raw turtle API document here](http://www.computercraft.info/wiki/Turtle_(API)).\n\nFeatures\n--------\n\n* provide functional style monadic api to use\n    - absolute coordinate system based api\n    - obstacle avoidance support (`move.to()` and `move.go()`)\n    - auto refuel\n    - auto tidy backpack slots\n    - provide high level combinators to construct complex logic in a very easy way\n* provide a deeply customized REPL\n    - you can use smart-turtle's variables in this REPL directly\n    - you can input an IO monad to execute it directly, e.g. `move` instead of `move()`\n    - support `Ctrl+C` to abort running process\n    - support `Ctrl+P` to print call stack\n    - support `Ctrl+U` to clean current line\n    - support `Ctrl+L` to clean screen\n    - persistent command history\n    - you can customize your own repl style by modifing `_replStyle` variable\n* provide a stack trace mechanism to help debugging\n    - you can manually mark functions which you want it to appear in the stack trace\n\nDocument\n--------\n\n### Single Turtle APIs\n\n- absolute coord based api\n    * implementation ideas\n        - get init pos \u0026 facing \u0026 aiming via gps\n        - maintains current pos \u0026 facing \u0026 aiming locally\n    * basic concepts\n        - turtle's workMode:\n            * `workMode.destroy`: whether auto dig when move blocked\n            * `workMode.violence`: whether auto attack when move blocked\n            * `workMode.retrySeconds`: time to retry when move blocked by other turtles\n        - turtle's workState:\n            * `workState.pos`: turtle's current gps position\n            * `workState.facing`: turtle's current facing direction: E/S/W/N\n            * `workState.aiming`: turtle's current aiming height: 1/0/-1\n        - about the \"tank model\" of turtle's state\n            * the turtle's state description method is inspired by tank\n            * a tank can rotate it's body and it's gun, same as the turtle\n            * a turtle's body can face to one of the four horizontal dir\n            * a turtle's gun (just image it) can aim to up/front/down\n            * so a turtle have 4 * 3 = 12 different state at each position\n            * the st apis will reference the facing and aiming state to work\n        - pos:\n            * short for \"position\"\n            * means a vector with three integer coord value\n        - dir:\n            * short for \"direction\"\n            * means a unit vector parallel to one of the three axis\n            * there are 4 horizontal directions: E/S/W/N and 2 vertical: U/D\n            * all directions can be found in `const.dir`, e.g. `const.dir.U`\n    * usage description\n        - `turn.to(d)`: turn to face/aim direction `d`\n        - `move`: move toward the aiming direction\n        - `dig`: dig toward the aiming direction\n- provide high level combinators to construct complex logic\n    * usage description\n        - `io1 * io2`: if `io1` succeed then execute `io2`\n        - `io1 + io2`: if `io1` failed then execute `io2`\n        - `io ^ n`: replicate `io` for `n` times\n        - `rep(io)`: repeat `io` until it fail\n        - `retry(io)`: retry `io` until it success, with sleep interval increased\n        - `retry(t)(io)`: retry `io` for `t` seconds\n        - `try(io)`: execute `io` and always return true\n        - `-io`: execute `io` and reverse the success/fail result\n        - `scan(area, mainDir)(io)`: scan an area, and execute a specific action at each pos\n- advanced move apis which support obstacle avoidance\n    * implementation idea\n        - inspired by the wall-following algorithm for 2-dimensional maze\n        - first, we attempt to approach the destPos until blocked\n        - second, we choose a detourPlane to detour following wall until closer\n        - we repeat the above two steps until we arrive the destPos\n    * usage description\n        - `move.to(destPos)`: go to `destPos`\n        - `move.go(destVec)`: go to `workState.pos + destVec`\n\nGet the code\n------------\n\n```\ngit clone https://github.com/luochen1990/smart-turtle\ncd smart-turtle\ncat src/* \u003e st.lua\n```\n\nThe `st.lua` file is a standalone file which you can run on turtle directly.\n\nTodo\n----\n\nSingle Turtle:\n\n* digAll(): dig all connected blocks which satisfy a specific condition in front of the turtle\n* search(): a generalized version of digAll, search all connected blocks which satisfy a specific condition and execute a specific action facing such a position\n* copy(): scan around a building and generate a blueprint, which can later be used to paste to somewhere else\n* paste(): paste a blueprint here, note that the turtle's current pos and dir will affect the pos and dir of the building\n\nTurtle Swarm:\n\n* control center: a specific server which maintain swarm state and send control instructions to turtle workers\n* task: a task is failable and retryable, it cannot be split anymore, and can only have one turtle working on it at a specific time\n* job: a job is just like a function when given number of workers returns a list of task\n* logistic station: a container, such as chest, which allows turtles suck or drop facing it\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluochen1990%2Fsmart-turtle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluochen1990%2Fsmart-turtle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluochen1990%2Fsmart-turtle/lists"}