# CobolCraft runs a Minecraft server written in COBOL > CobolCraft is a Minecraft server implemented in COBOL, compiled with GnuCOBOL and linked against C++ for sockets and timing, with a code generator that writes COBOL from Minecraft's own data files. It supports Minecraft 1.21.4 and plays well, but many block behaviours are still missing and the project ships no tagged release. **meyfa/CobolCraft** — A Minecraft server written in COBOL - Repository: https://github.com/meyfa/CobolCraft - Website: https://hub.docker.com/r/meyfa/cobolcraft - Stars: 705 · Forks: 63 - Language: COBOL - License: MIT - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/meyfa-cobolcraft ## A Minecraft server written in COBOL CobolCraft implements the server side of Minecraft in COBOL, targeting version 1.21.4. The feature list is long enough to be surprising. Infinite terrain generation with dynamic chunk loading, world and player data persisted to disk, support for Minecraft's own file formats so you can import an existing world, multiplayer with a configurable number of concurrent players, the ping and server status that makes a server show up as online in the list, block breaking and placing with auto-generated loot table code, block interaction such as opening doors, a player inventory, crafting in both 2x2 and 3x3 grids, item entities with pickup, chat, commands both in game and through an interactive console, configuration through server.properties, a persistent whitelist stored in whitelist.json, and basic block and player collision with entity physics, fall damage, void damage, dying and respawning. The author's stated motivation is educational. The project started as a way to learn a language with a reputation for being unfashionable, and the author notes that translating an inherently object-oriented system into a procedural language is the steepest part of the exercise. ## A code generator that writes COBOL from Minecraft's data The interesting engineering is in the codegen directory. There is a code generator, written in COBOL itself, that produces additional COBOL source from JSON data such as Minecraft's default datapack. That is a striking piece of design: the language being demonstrated is also the language of the toolchain. The inputs come from the official server jar, which contains the block, item and entity types, the biomes, the protocol IDs for packets, tags such as which blocks are mineable with a pickaxe, recipes, and loot tables describing what a block drops and under which conditions. The Makefile has a target that downloads the jar and extracts this data as JSON, and the JSON is then used in two distinct ways. At compile time it drives code generation, for example the loot table code for blocks. At runtime it is loaded into memory as the server's data set. A custom generic JSON parser, written in COBOL and fully unit tested, serves both jobs, which removes any dependency on a JSON library that does not exist in COBOL. ## C++ handles what COBOL cannot do well The division of labour between src and cpp is explicit in the project overview. The COBOL source lives in src/, with src/main.cob as the entrypoint and src/server.cob holding the startup code and the game logic. The cpp directory holds C++ sources used to interface with the operating system in ways that are not feasible in COBOL, and the project names three of them: low level TCP socket management, precise timing, and process signal handling. All sources, COBOL and C++, are compiled into a single cobolcraft binary, so the end user sees one executable rather than a multi-process stack. This is a sensible engineering decision rather than a stylistic flourish. Real time multiplayer networking needs direct control over sockets, latency budgets need a clock finer than the one a high level language hands you, and a server that must shut down cleanly needs signal handling. The cost is that CobolCraft is not pure COBOL, and a reader who came for a language demonstration will find the parts most worth reading are in a different language. ## Building on Linux and running the container CobolCraft was developed with GnuCOBOL and is meant to run on Linux on x86_64 or arm64, and the documentation is explicit that other systems such as Windows are untested, while Docker offers a platform independent route. The Linux prerequisites are listed in full: GnuCOBOL 3.1.2 or later, with 3.2 or later highly recommended for performance, plus make, gcc, g++, zlib, curl for downloading the server jar, and Java 21 or later for extracting data from that jar. With those in place, two commands build and start the server. ```sh make --jobs=$(nproc) make run ``` The container route is the one to use if your platform is not Linux, and the image is published on Docker Hub. ```sh # pull the image from Docker Hub docker pull meyfa/cobolcraft:latest # or build it yourself git clone https://github.com/meyfa/CobolCraft.git cobolcraft && cd cobolcraft docker build --tag meyfa/cobolcraft . docker run --rm --interactive --tty \ --publish 25565:25565 \ --volume "$(pwd)/server.properties:/app/server.properties" \ --volume "$(pwd)/whitelist.json:/app/whitelist.json" \ --volume "$(pwd)/world:/app/world" \ meyfa/cobolcraft ``` The Dockerfile behind the image splits into a build stage and a deploy stage on an Ubuntu base, runs the data extraction early so the layer caches, compiles with make and a GCVERSION=32 flag, and finishes with the server running under tini so that signals are handled properly. ## server.properties and the localhost default Configuration is done in server.properties, which is generated automatically on first run with default values for every supported option. The documented set is short: server-port, defaulting to 25565, level-name defaulting to world, white-list defaulting to false, motd defaulting to CobolCraft, and max-players defaulting to 10 with a documented maximum of 100. The whitelist itself lives in whitelist.json and is persistent, which is what lets the server restrict who joins without regenerating the file on every start. One default is worth understanding before you hand anyone an address. By default the server is only accessible via localhost, meaning only on your own system through localhost:25565. To expose it to a local network, over a VPN, through port forwarding or on a rented server, you need a different port mapping. ```sh docker run --rm -it -p 0.0.0.0:25565:25565 meyfa/cobolcraft ``` That single change from 25565 to 0.0.0.0 in the port mapping is the difference between a private world and one that anyone who learns the address can join. ## Where the block behaviour stops The documentation is candid about the gap, and it is a specific gap rather than a vague one. Blocks with multiple states, orientations, or interactive blocks require large amounts of specialized code to behave properly, and many of these are not yet supported. The list of working blocks gives the shape of what that means: torches, slabs, stairs, rotated pillars such as logs, non-interactive buttons, doors, trapdoors, beds and signs. Non-interactive is doing real work in that sentence, since a button that cannot be pressed is a different object from a working one. Beyond that, the physics is described as extremely basic, and the collision handling is basic in the same way. This is the point where CobolCraft stops being a drop-in server and becomes a partial reimplementation. A player who builds with redstone, or expects comparators, pistons, observers or a redstone clock to behave as in the real game, will hit the wall quickly, because the underlying engine is not simulating those mechanics. The other constraint is version lock. The project targets Minecraft 1.21.4, and a client on a different version will not interoperate with a server built for that protocol. ## Tests, tooling and the missing release history The test story is unusually deliberate for an experiment. Unit tests live in the tests directory and use a custom copybook based testing framework that tracks test suites, units and assertions and prints a summary at the end of the run, invoked with make test. The stated priority is telling: the main goal should be to test encoding and decoding of JSON and binary data and other things that are hard to debug, while testing the game logic itself is not so critical. That is a defensible split, because the generated code covers the mechanical behaviour and the hand written parsers are where a silent bug would corrupt a world. The repository also carries separate build and test CI workflows, a renovate.json for dependency updates, an Updating.md guide for moving to a new Minecraft version, and a Makefile whose variables for the codegen binary dependencies are spelled out to avoid redoing codegen on every source change. What is missing is release history. The repository has no GitHub releases, the last push was on 2026-06-28, and the licence is MIT with a LICENSE file at the root. For a project whose whole appeal is running a server, that means you build from source and track the branch yourself. ## Conclusion Adopt CobolCraft if you want to run a Minecraft server for friends on Linux and you are more interested in the experiment than in feature parity, because the crafting, inventory, chat, commands and persistence basics are there while much of the block behaviour is not. Skip it if your players expect the full game, since blocks with multiple states and interactive blocks are explicitly listed as unsupported, and skip it if you need a versioned artifact, because the repository publishes no GitHub releases. Before you deploy, read Updating.md, pin your clients to Minecraft 1.21.4, and remember that by default the server only listens on localhost, so publishing it needs the explicit 0.0.0.0 port mapping. ## FAQ ### How do I build and run CobolCraft on Linux? Install GnuCOBOL 3.1.2 or later (3.2 recommended), make, gcc, g++, zlib, curl and Java 21, then run make --jobs=$(nproc) and make run. The server listens on port 25565 by default and is only reachable from localhost unless you change the port mapping. ### Can I run CobolCraft with Docker instead of installing GnuCOBOL? Yes. Pull meyfa/cobolcraft:latest from Docker Hub, or clone the repository and build it yourself with docker build --tag meyfa/cobolcraft . The container publishes port 25565 and mounts server.properties, whitelist.json and the world directory. ### Which Minecraft version does CobolCraft support? The project supports Minecraft 1.21.4, the latest version at the time of writing. The server jar for that version is the source of the block, item, recipe and protocol data the build extracts. ### What features are still missing in CobolCraft? Blocks with multiple states, orientations and interactive blocks are not yet supported, so only a limited set of blocks such as torches, slabs, stairs, doors, trapdoors, beds and signs behaves properly. The collision and entity physics are described as extremely basic. ### How do I run the CobolCraft test suite? Run make test. The tests live in the tests directory and use a custom copybook based framework that tracks suites, units and assertions, and the project states the priority is testing JSON and binary encoding rather than the game logic itself. ## Sources - [Issues](https://github.com/meyfa/CobolCraft/issues) - [License: MIT](https://github.com/meyfa/CobolCraft/blob/main/LICENSE) - [meyfa/CobolCraft on GitHub](https://github.com/meyfa/CobolCraft) - [Project website](https://hub.docker.com/r/meyfa/cobolcraft) - [README](https://github.com/meyfa/CobolCraft/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/meyfa-cobolcraft