# UCraft: a Minecraft server in C built for machines with little memory

> UCraft implements the bare essentials of the Minecraft protocol in C, producing a binary of roughly 46K bytes that runs on a microcontroller, a printer or a home router. The trade-off is explicit: it is a foundation for very primitive gameplay, not a full server replacement, and it currently tracks a single client release.

**vimpop/UCraft** — A minecraft server implementation written in C for machines with limited resources. 

- Repository: https://github.com/vimpop/UCraft
- Stars: 519 · Forks: 27
- Language: C
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/vimpop-ucraft

## A Minecraft server measured in kilobytes, not megabytes

UCraft exists because the usual way of running a Minecraft server does not fit on a small device. The repository describes itself as a Minecraft server implementation written in C for machines with limited resources, and the README puts numbers on that claim: a binary of about 46K bytes without authentication and about 70K bytes with it, plus roughly 50K bytes of memory on average for a single player. Those figures place it in a category far removed from a general-purpose server process. The audience is therefore not an operator who wants a public survival world with plugins and permissions. It is an embedded developer who wants the Minecraft wire protocol to work on a board with a few hundred kilobytes of RAM, and it is the author of this repository, who has already ported it to three such devices.

## Only the bare essentials of the protocol are implemented

The scope is stated without ambiguity. The README says UCraft implements just the bare essentials of the Minecraft protocol: clients can join, explore a procedurally generated world, chat, and break and place blocks. The world is generated on demand as players move around it, so an explorable terrain appears without the whole world being stored or generated up front. The README is equally direct about what this does not amount to, calling it the foundation for very primitive Minecraft gameplay and explicitly not a full server replacement. The repository layout matches that framing, with a src directory, an include directory, a 3rdparty directory for vendored dependencies, config.h and config_adv.h for compile-time options, and a CMakeLists.txt at the root. One switch changes both the binary size and the trust model: online-mode encryption is described as authenticated logins through mbedTLS, with offline mode available without it. The two size figures in the README differ by about 24K bytes, which is a large slice of the whole program on a microcontroller.

## Three ports show the server is meant to leave the desktop

The README lists implementations of UCraft beyond the reference build: Lightbulb on a BL602 MCU, a Samsung C410W printer on an ARM big-endian MCU, and an Italian ISP router based on a Broadcom BCM63138, the router work being credited to ZioCook. The printer port is the striking one, since a printer has no display and no general-purpose operating system in the usual sense. The repository also invites other implementations by asking people to open an issue. This is the practical answer to the question of what UCraft is for: it is a protocol core that gets cross-compiled and dropped onto hardware, with the desktop build acting as the development reference rather than the product. Offline mode matters in that context, since a device on a home network has no use for account authentication.

## Building the server from a fresh clone and starting it

The build is a standard CMake flow and the README is explicit about the toolchains. The server was built and tested on Linux, MSVC is required on Windows, and on macOS the Xcode Command Line Tools and CMake are required. On a Debian-style Linux machine the sequence is short. The first line installs the build dependencies, the clone fetches the sources, and the last three lines configure and compile, producing an executable named UCraft in build/src.

```bash
sudo apt install git build-essential cmake make
git clone https://github.com/vimpop/UCraft/
cd UCraft && mkdir build && cd build
cmake ..
make
```

Pre-built binaries are also available as artifacts of the GitHub Actions workflow runs, which is the faster path for a reader who only wants to see the server running. With the executable built, running it produces two informational lines, one saying it is listening on port 25565 and one announcing that the server started. A Minecraft 26.1.2 client then connects to localhost:25565. Because the world is generated on demand, there is no world directory to prepare and no configuration file to author before the first connection, which suits a device port where a filesystem may not even exist.

```bash
./src/UCraft
[INFO]: Listening on *:25565
[INFO]: UCraft server started!
```

## The regression suite compiles the real gameplay code

Testing a server that normally needs a Minecraft client and an account is unusual, and UCraft handles it by using fixed fixtures and recorded messages, so the suite needs no client and no account. The tests compile the real gameplay, inventory and block-storage code rather than a stub, and the portable suite runs on Linux, macOS and Windows. Enabling BUILD_TESTING and pointing CTest at the build directory is all it takes.

```bash
git submodule update --init --recursive
cmake -S . -B build/test -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=ON
cmake --build build/test --config Release --parallel
ctest --test-dir build/test -C Release --output-on-failure --no-tests=error
```

The submodule step matters because the vendored dependency has to be present before the fixtures compile. On Linux, adding UCRAFT_TCP_TESTS=ON brings in a Python TCP smoke test that checks status, ping, malformed frames, concurrent clients and graceful shutdown. It uses port 25565 by default and does not contact Mojang, so it can run on a machine with no network access to the game servers.

## Sanitizer builds catch the memory errors an embedded target cannot

For code that will run on a device with no debugger attached, the sanitizer configuration is the more interesting half of the test story. On Linux, the compiler is switched to clang and the sanitizer option is enabled, then the suite runs with AddressSanitizer and UndefinedBehaviorSanitizer options set to stop on the first fault and print a stack trace. Leak detection is on, which matters because a server that leaks over a long uptime is a failure mode that never shows up during a five minute session.

```bash
cmake -S . -B build/sanitizers -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
  -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON -DUCRAFT_TCP_TESTS=ON -DUCRAFT_SANITIZERS=ON
cmake --build build/sanitizers --parallel
ASAN_OPTIONS=detect_leaks=1:halt_on_error=1 UBSAN_OPTIONS=halt_on_error=1:print_stacktrace=1 \
  ctest --test-dir build/sanitizers --output-on-failure --no-tests=error
```

New gameplay cases go into tests/game_tests.c and their names are registered in tests/CMakeLists.txt. Building only the server is done with BUILD_TESTING=OFF, which is what an embedded integrator wants for a production image. The GitHub Actions matrix runs the suite with GCC, Clang and MSVC, plus the Linux sanitizers, and uploads JUnit results and logs as artifacts.

## Version tracking is narrow and the tags show it

The release history is short and instructive. v1.0.0 was published as the initial release on 2025-09-22, v1.0.1 on 2025-10-05 as an update to 1.21.9, and v1.0.2 on 2025-11-29 as an update to 1.21.10. The README, meanwhile, states that the server currently supports Minecraft 26.1.2 clients. A mismatch between the wording of the latest tag and the wording of the README is exactly the kind of detail a team should resolve before it pins a client version, since neither source states how versions map to each other in general. The repository is not archived and the last push was on 2026-10-01, so the work is recent, but three tags in a year means the project is young and the protocol surface it covers is narrow.

## Where UCraft is the wrong tool, and what MIT permits

The alternative is not a competing project but a different operating mode for the same protocol, and the choice is explicit in the README. A full-featured server is the alternative for a player-facing world, and UCraft is not attempting to be one. Its own implementation list shows the other direction of travel, where the server is shrunk onto a lightbulb, a printer or a router and the feature set is trimmed to match the hardware. The README documents no configuration surface for gameplay rules, no plugin mechanism and no description of how a world is persisted between restarts, so a project that needs world persistence, permissions or administrative controls sits outside what is described here. On a machine with memory to spare, picking UCraft buys a smaller binary and gives up the rest of the game. Licensing is the MIT license, with the text in LICENSE.txt at the root, so porting the server to a proprietary device is not blocked by a copyleft obligation. The credits list names Bixilon for help with major parts of the Minecraft protocol and wiki.vg for documenting the protocol itself, which is worth knowing before building on top of the implementation, since the protocol documentation is community maintained and the server targets a moving target.

## Conclusion

Adopt UCraft if your constraint is memory, processor or a device that cannot host a JVM, or if you are porting the protocol to embedded hardware, and if a world with chat, block edits and generated terrain is enough. Do not adopt it as a drop-in replacement for a full server, since the README positions it as the foundation for very primitive Minecraft gameplay, and do not expect broad client compatibility while the README states support for Minecraft 26.1.2 clients only. Before building, check the release tags against the client version you intend to use, because v1.0.2 is described as an update to 1.21.10 while the README names 26.1.2, and note that the last push was on 2026-10-01.

## FAQ

### Which Minecraft client versions does UCraft support?

The README states that UCraft currently supports Minecraft 26.1.2 clients. The release notes are worded differently, with v1.0.2 described as an update to 1.21.10, so the mapping between tag names and client versions is not spelled out.

### How much memory and disk space does UCraft need?

The README puts the binary at about 46K bytes without authentication and about 70K bytes with it, with around 50K bytes of memory used on average for a single player.

### Does UCraft support authenticated Minecraft logins?

Yes. The README lists online-mode encryption with authenticated logins through mbedTLS, and also allows offline mode without it.

### How do I run the UCraft regression tests without a Minecraft account?

The CTest suite uses fixed fixtures and recorded messages, so no Minecraft client or account is needed. Configure a build directory with BUILD_TESTING=ON and then run CTest against it; gameplay cases live in tests/game_tests.c and their names are registered in tests/CMakeLists.txt.

### Can UCraft run on embedded hardware such as a microcontroller or printer?

The README lists implementations for a Lightbulb on a BL602 MCU, a Samsung C410W printer on an ARM big-endian MCU and a Broadcom BCM63138 ISP router, with implementation details in separate repositories. The README also invites others to open an issue with their own implementation.

## Sources

- [Issues](https://github.com/vimpop/UCraft/issues)
- [License: MIT](https://github.com/vimpop/UCraft/blob/main/LICENSE)
- [README](https://github.com/vimpop/UCraft/blob/main/README.md)
- [Releases](https://github.com/vimpop/UCraft/releases)
- [vimpop/UCraft on GitHub](https://github.com/vimpop/UCraft)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vimpop-ucraft