{"id":18535769,"url":"https://github.com/daniel5151/embcrusted","last_synced_at":"2025-06-20T02:38:03.216Z","repository":{"id":79236125,"uuid":"221780027","full_name":"daniel5151/embcrusted","owner":"daniel5151","description":"A z-machine interpreter for running Infocom-era text adventure games on embedded hardware.","archived":false,"fork":false,"pushed_at":"2020-09-07T22:35:06.000Z","size":29542,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-15T00:39:17.933Z","etag":null,"topics":["embedded","no-std","rust","z-machine","zmachine","zmachine-interpreter","zork"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/daniel5151.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-14T20:21:25.000Z","updated_at":"2023-02-21T00:56:22.000Z","dependencies_parsed_at":"2023-03-29T19:02:27.172Z","dependency_job_id":null,"html_url":"https://github.com/daniel5151/embcrusted","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/daniel5151/embcrusted","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel5151%2Fembcrusted","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel5151%2Fembcrusted/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel5151%2Fembcrusted/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel5151%2Fembcrusted/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daniel5151","download_url":"https://codeload.github.com/daniel5151/embcrusted/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel5151%2Fembcrusted/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260867855,"owners_count":23074915,"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":["embedded","no-std","rust","z-machine","zmachine","zmachine-interpreter","zork"],"created_at":"2024-11-06T19:27:19.138Z","updated_at":"2025-06-20T02:37:58.198Z","avatar_url":"https://github.com/daniel5151.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# embcrusted\n\nA z-machine interpreter for Infocom-era text adventure games which can run on embedded hardware.\n\n`embcrusted` is forked from [`encrusted`](https://github.com/DeMille/encrusted), though it's been heavily refactored and stripped-down to run in an embedded `no_std` environment. It's missing all these features (and more!):\n\n-   No Save / Load functionality\n-   No fancy resource-intensive data structures (like hash-maps for dictionaries).\n-   Not a single `#[derive(Debug)]` in sight\n\nHere's a video of `embcrusted` playing `Zork I` off a [Planck EZ](https://ergodox-ez.com/pages/planck) Keyboard (running a ARM Cortex-M4 MCU), intercepting keystrokes as \"input\", and faking keystrokes as \"output\". Note that the game is running _entirely_ on the keyboard, and only sends data to the device it's plugged into.\n\n\u003cimg src=\"zorkey.gif\" alt=\"embcrusted running Zork I on a Plack EZ Keyboard\"\u003e\n\nCheck out the `zorkey` branch on [my fork of the QMK firmware](https://github.com/daniel5151/qmk_firmware/tree/zorkey/keyboards/planck/keymaps/prilik) if you're interested in the code that makes this possible.\n\n## Target Platforms\n\n`embcrusted` is completely `no_std`, though it does depend on `alloc`.\n\nAt the moment, `embcrusted` has only been tested on the following system:\n\n| Platform                                                                             | Flash ROM | RAM  |\n| ------------------------------------------------------------------------------------ | --------- | ---- |\n| `STM32F303xC` (inside the [Planck EZ](https://ergodox-ez.com/pages/planck) keyboard) | 256kb     | 48kb |\n\n## Resource requirements\n\nStorage and Memory requirements will vary by game (stack usage, dynamic-memory size, binary size) and compilation target (code density).\n\nThat said, here are some benchmarks I've collected using `encrusted-ui-no-std` (compiled and run on `amd64`, linked with libc, with inlined _Zork I_ game data):\n\n```bash\n# additional RUSTFLAGS to strip binary during compilation.\n# for full list of compiler flags, see the `profile.release` section in Cargo.toml\nRUSTFLAGS='-C link-arg=-s' cargo +nightly run -p encrusted-ui-no-std --release\n```\n\n-   Storage Requirements\n    -   Just `embcrusted`: **60.43 KiB**\n    -   Just _Zork_ game data: **82.88 KiB**\n    -   Just `encrusted-ui-no-std` (with _Zork_ and `embcrusted` commented out): **19.07 KiB**\n    -   **_Total Additional Storage:_** **143.32 KiB**\n-   Heap Usage\n    -   _Zork_ base z-machine dynamic memory requirements: **11.58 KiB**\n    -   z-machine interpreter (before first exec): **2.70 KiB**\n    -   z-machine interpreter (after a bit of gameplay): **3.71 KiB**\n    -   **_High Watermark Heap usage:_** **17.62 KiB**\n\nI did not benchmark stack usage during interpreter execution (though it probably isn't too much?).\n\n## Usage\n\nIn a nutshell:\n\n-   Implement the `embcrusted::Ui` trait\n-   Construct a new `Zmachine` interpreter with a reference to the game's data, your UI implementation, and an initial RNG seed\n-   Run the interpreter in a loop, handling input and exit requests as necessary.\n\nSee the `encrusted-ui` and `encrusted-ui-no-std` packages for some basic examples.\n\n## Future work\n\nAt the moment, `embcrusted` meets the resource constrains of my target hardware, and as such, it's unlikely that I'll be improving it much further.\n\nThat said, if you're interested in helping out, there are a couple of places that could be improved / need some more work.\n\nPRs are welcome!\n\n-   RAM usage could be improved by refactoring `String` operations into in-place buffer manipulations, and replacing `Vec`s with static buffers.\n    -   This would also remove the dependency on `alloc`, for _very_ resource constrained systems.\n-   Binary size could be cut down further by adding feature-flags for specific z-machine version features.\n-   It might be possible to shrink the game file down somewhat with some low-overhead decompression at runtime (e.g: [`heatshrink`](https://github.com/atomicobject/heatshrink)). I've done some preliminary tests, and while it's somewhat promising, it's not something I'll be integrating into `embcrusted` just yet. If you're interested in experimenting, take a look at `buffer.rs` :eyes:\n-   A quick grep for \"FIXME\" or \"TODO\" will probably turn up plenty of things which need fixing :smile:.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel5151%2Fembcrusted","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaniel5151%2Fembcrusted","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel5151%2Fembcrusted/lists"}