{"id":30656068,"url":"https://github.com/iluha168/mcdrive","last_synced_at":"2026-07-16T14:04:03.268Z","repository":{"id":309077059,"uuid":"1035096339","full_name":"iluha168/MCDrive","owner":"iluha168","description":"Store your bytes as blocks in a Minecraft server!","archived":false,"fork":false,"pushed_at":"2025-08-09T16:59:15.000Z","size":1574,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-31T10:05:48.769Z","etag":null,"topics":["drive","driver","filesystem","minecraft","nbd"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iluha168.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2025-08-09T16:42:26.000Z","updated_at":"2025-08-22T15:43:05.000Z","dependencies_parsed_at":"2025-08-09T18:33:02.387Z","dependency_job_id":"8190fac6-6adb-407f-8584-e9c9586e0b53","html_url":"https://github.com/iluha168/MCDrive","commit_stats":null,"previous_names":["iluha168/mcdrive"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/iluha168/MCDrive","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iluha168%2FMCDrive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iluha168%2FMCDrive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iluha168%2FMCDrive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iluha168%2FMCDrive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iluha168","download_url":"https://codeload.github.com/iluha168/MCDrive/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iluha168%2FMCDrive/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35546267,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-16T02:00:06.687Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["drive","driver","filesystem","minecraft","nbd"],"created_at":"2025-08-31T10:05:08.751Z","updated_at":"2026-07-16T14:04:03.248Z","avatar_url":"https://github.com/iluha168.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- omit in toc --\u003e\n# MCDrive\n\nMCDrive is a virtual storage device for Linux. It stores bytes as blocks in a Minecraft server.\n![Minecraft blocks overlayed by their corresponding byte values](docs/hex-overlay.png)\n![GParted showing an MCDrive with GPT](docs/GParted-gpt-only.png)\n\n\"Why do not you use NBT?\", \"Why not use blockstates?\", etc...? One of my personal goals was to make stored data visually interesting in-game.\n\n\u003c!-- omit in toc --\u003e\n# Table of contents:\n- [WHY](#why)\n- [HOW](#how)\n- [**RUN**](#run)\n\n## WHY\n\n*MCDrive was **written as a joke** in two short evenings. The code is terrible and the architecture can be improved.*\n\nI saw this [video on YouTube](https://www.youtube.com/watch?v=DSAnn5BOIBA) about a Minecraft plugin, that runs an HTTP server, which uses the in-game world itself as BLOB storage.\n\nThat implementation included a custom file system, which was far from perfect. I thought \"I could do you one better\" and went one layer lower in the abstraction, allowing *any* file system.\n\nMy task became very simple - mapping 3D world of Minecraft into a 1D array of bytes, and letting existing file systems handle the rest ✨. With 1382400000000000000 blocks in the overworld, and 1 byte per 1 block, the available storage space is ~1257285 TebiBytes. *This size has shown me just how buggy various partition managers can be :P*\n\n## HOW\n*Image generated by the amazing [Excalidraw](https://excalidraw.com).*\n![Architecture](docs/architecture.svg)\n\n1. Linux has support for **N**etwork **B**lock **D**evices. By loading the NBD module, we create block **dev**ices called `nbdXXX` at `/dev/`. These can be used as drives, in fact, your physical drives are sitting in that folder too.\n2. A C program, ran as super-user, translates `/dev/nbd0` APIs into another intermediary FIFO-based protocol. Those FIFOs are created **in userspace**.\n3. Because FIFOs are accessible by a regular user, we can safely run a Minecraft server as that user. A [PaperMC](https://papermc.io/) plugin polls FIFOs and performs according changes in the Minecraft world, and the server itself provides real-time world updates to the clients.\n\n*Performs changes in the world*? And HOW is that?\n\nI decided to go with a \"1 byte = 1 block\" approach. This meant generating an alphabet of 256 blocks, which is pretty easy.\n`0` has been hardcoded to \"air\", and the rest of the alphabet are full blocks with no gravity.\n\nDrives must be 1-dimensional, but a Minecraft world is 3-dimensional. I decided to unwrap blocks in a chunk from bottom to top, and chunks in a world - in a spiral around the origin.\nThis made stored information easy to observe in-game, because it does not shoot off into the distance; it prioritizes staying close to the origin. (In addition, less regions are created this way.)\n![Some chunks filled in a spiral](docs/preview.png)\n\n## **RUN**\n*Note that the plugin is licensed under GNU GPL 3, and the NBD bridge is licensed under GNU GPL 2.*\n\nPrerequisites\n- `gcc` v14.\n- `sudo`.\n- A clone of this repository.\n- [Latest PaperMC](https://papermc.io/downloads/all?project=paper) for 1.21.7 in `Server/server.jar`.\n\nRunning\n1. Open a terminal, change CWD into `NBD-FIFO/`, and execute `./run.sh`. This does require super-user, but it must be ran as a regular user (to create FIFOs as).\n2. Open a terminal, change CWD into `Server/`, and execute `./run.sh`.\n3. [ONCE] Apply `/gamerule randomTickSpeed 0` to prevent data corruption.\n\nNow you can use `/dev/nbd0` as a drive. Write to it raw, or partition it with a file system - anything your heart desires!\n\n\u003e [!CAUTION]\n\u003e - **Always** shutdown the NBD bridge before the Minecraft server. Press Ctrl+C to request shutdown and wait for it to exit gracefully.\n\u003e - After you shutdown the NBD bridge, you have to shutdown the server as well.\n\n\u003e [!NOTE]\n\u003e Linux caches IO in memory. If you make a change to the drive in-game, there is a good chance no program will detect it.\n\u003e - Filesystem cache seems to drop on unmount of its partition.\n\u003e - Drive cache seems to drop on restart of the NBD bridge.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filuha168%2Fmcdrive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filuha168%2Fmcdrive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filuha168%2Fmcdrive/lists"}