{"id":17095601,"url":"https://github.com/meyfa/cobolcraft","last_synced_at":"2025-04-06T19:10:37.413Z","repository":{"id":231295552,"uuid":"780602851","full_name":"meyfa/CobolCraft","owner":"meyfa","description":"A Minecraft server written in COBOL","archived":false,"fork":false,"pushed_at":"2025-03-27T20:52:37.000Z","size":1398,"stargazers_count":577,"open_issues_count":11,"forks_count":23,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-30T18:07:31.586Z","etag":null,"topics":["cobol","minecraft","minecraft-server"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/meyfa/cobolcraft","language":"COBOL","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/meyfa.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},"funding":{"github":"meyfa"}},"created_at":"2024-04-01T20:16:08.000Z","updated_at":"2025-03-29T21:30:44.000Z","dependencies_parsed_at":"2024-04-03T11:25:38.174Z","dependency_job_id":"5240aa2a-59bf-4eb0-bed2-98868d0db567","html_url":"https://github.com/meyfa/CobolCraft","commit_stats":null,"previous_names":["meyfa/cobolcraft"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meyfa%2FCobolCraft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meyfa%2FCobolCraft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meyfa%2FCobolCraft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meyfa%2FCobolCraft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meyfa","download_url":"https://codeload.github.com/meyfa/CobolCraft/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247535516,"owners_count":20954576,"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":["cobol","minecraft","minecraft-server"],"created_at":"2024-10-14T14:43:16.152Z","updated_at":"2025-04-06T19:10:37.389Z","avatar_url":"https://github.com/meyfa.png","language":"COBOL","funding_links":["https://github.com/sponsors/meyfa"],"categories":[],"sub_categories":[],"readme":"# CobolCraft\n\n[![Build](https://github.com/meyfa/CobolCraft/actions/workflows/build.yml/badge.svg)](https://github.com/meyfa/CobolCraft/actions/workflows/build.yml)\n[![Test](https://github.com/meyfa/CobolCraft/actions/workflows/test.yml/badge.svg)](https://github.com/meyfa/CobolCraft/actions/workflows/test.yml)\n\nA Minecraft server written in COBOL. It supports Minecraft 1.21.4 (the latest version at time of writing).\n\n## Features\n\nThe following features are already implemented:\n\n- [X] infinite terrain generation and dynamic chunk loading\n- [X] persisting world and player data to disk\n- [X] support for Minecraft's file formats (import existing worlds)\n- [X] multiplayer (configurable number of concurrent players)\n- [X] ping/server status (i.e., show as online in the server list)\n- [X] breaking and placing blocks, with auto-generated loot table code\n- [X] block interaction (right-clicking, e.g., to open doors)\n- [X] player inventory\n- [X] crafting, both 2x2 and 3x3\n- [X] item entities and item pickup\n- [X] chat\n- [X] commands (in-game and via an interactive console)\n- [X] configuration via server.properties\n- [X] whitelist (persistent; stored in whitelist.json)\n- [X] extremely basic block/player collision and entity physics\n- [X] fall damage and void damage, dying, and respawning\n\nNote that blocks with multiple states, orientations, or interactive blocks require large amounts of specialized code\nto make them behave properly, and many of these are not yet supported.\n\nWorking blocks include: torches, slabs, stairs, rotated pillars (e.g. logs), buttons (non-interactive), doors,\ntrapdoors, beds, and signs.\n\n## Getting Started\n\nCobolCraft was developed using GnuCOBOL and is meant to be run on Linux (x86_64 or arm64 architectures).\nSupport for other operating systems such as Windows has not been tested.\nHowever, it is possible to use Docker for a platform-independent deployment.\n\nTo deploy on Linux, make sure all prerequisites are installed:\n\n* GnuCOBOL 3.1.2 or later (e.g., from the `gnucobol` package on Debian/Ubuntu)\n    - 3.2 or later is highly recommended for performance reasons - check `cobc -version`\n* `make`\n* `gcc`, `g++`\n* `zlib` (e.g. `zlib1g-dev` on Debian/Ubuntu)\n* `curl` (needed to download the official server .jar)\n* Java 21 or later (needed to extract data from the server .jar)\n\nRun the following commands to build and run CobolCraft:\n\n```sh\nmake --jobs=$(nproc)\nmake run\n```\n\nOr, run CobolCraft using Docker:\n\n```sh\n# pull the image from Docker Hub\ndocker pull meyfa/cobolcraft:latest\n\n# or build it yourself\ngit clone https://github.com/meyfa/CobolCraft.git cobolcraft \u0026\u0026 cd cobolcraft\ndocker build --tag meyfa/cobolcraft .\n\ndocker run --rm --interactive --tty \\\n     --publish 25565:25565 \\\n     --volume \"$(pwd)/server.properties:/app/server.properties\" \\\n     --volume \"$(pwd)/whitelist.json:/app/whitelist.json\" \\\n     --volume \"$(pwd)/world:/app/world\" \\\n    meyfa/cobolcraft\n```\n\nTo configure the server, edit the `server.properties` file.\nThis file is generated automatically on first run with default values for all supported options:\n\n* `server-port` (default: 25565)\n* `level-name` (default: \"world\")\n* `white-list` (default: false)\n* `motd` (default: \"CobolCraft\")\n* `max-players` (default: 10; maximum: 100)\n\nNote: By default, the server is only accessible via localhost (i.e., only on your own system via `localhost:25565`).\nTo make it accessible from the outside (your local network, via VPN, port forwarding, on a rented server, ...), you\ncan start the Docker container like this:\n\n```sh\ndocker run --rm -it -p 0.0.0.0:25565:25565 meyfa/cobolcraft\n```\n\n## Why?\n\nWhile I had zero prior COBOL experience, I had heard a lot of rumors and noticed a stigma surrounding COBOL.\nThis intrigued me to find out more about this language - and the best way to learn a language is to write something\nwith it.\n\nIn retrospect, due to the sheer complexity and scale of Minecraft's code, choosing to write a Minecraft server\nin COBOL was both the best and worst idea I could have had.\nFor one, it is necessary to invent a lot of things from scratch that are quite easy in other languages.\nThis includes parsing and encoding JSON and all kinds of binary data, implementing real-time multiplayer networking,\nand translating large amounts of an inherently object-oriented system (Minecraft) to a procedural language.\nHowever, adapting to such a steep learning curve forces me to research and understand the language and its concepts\nin-depth, which is very rewarding.\n\nIf you too have never written COBOL before but are interested in CobolCraft, I recommend reading the GnuCOBOL\nProgrammer's Guide:\nhttps://gnucobol.sourceforge.io/HTML/gnucobpg.html\n\nTo learn more about the Minecraft protocol, you can refer to the wiki.vg documentation:\nhttps://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Protocol\n\nIn some cases, it may also be helpful to look at real server traffic (e.g., using Wireguard) to better understand the\nflow of information.\n\n## Program Overview\n\nThis section provides a high-level overview of CobolCraft from a software design viewpoint.\n\n### Source Components\n\nCOBOL source code is primarily located in the `src/` directory, with `src/main.cob` being the entrypoint.\n`src/server.cob` contains the server startup code and the game logic.\n\nIn true COBOL fashion, there is also a code generator (itself written in COBOL) that generates additional source code\nfrom JSON data like Minecraft's default datapack.\nThis can be found in the `codegen/` directory.\n\nThe `cpp/` directory contains C++ sources that are used to interface with the operating system in ways that are not\nfeasible in COBOL, such as low-level TCP socket management, precise timing, or process signal handling.\n\nAll sources (COBOL and C++) are compiled into a single `cobolcraft` binary.\n\n### Data Extraction\n\nThe official Minecraft (Java Edition) server and client applications contain large amounts of data such as:\n\n* block, item, and entity types\n* biomes\n* protocol IDs for packets\n* tags (e.g., which blocks are mineable with a pickaxe)\n* recipes\n* loot tables (e.g., what items a block drops when broken, and under which conditions)\n\nThe CobolCraft `Makefile` has a target to download the .jar and extract this data as JSON, which is used in two ways:\n\n* at compile-time to automatically generate COBOL code, such as for block loot tables\n* at runtime to load the data into memory.\n\nA custom-built generic JSON parser (written in COBOL and fully unit-tested) is used for both tasks.\n\n### Tests\n\nUnit tests are available in the `tests/` directory, using a custom copybook-based testing framework that tracks test\nsuites, units, and assertions and provides a summary at the end of the run.\nCall `make test` to run the tests.\n\nThe main goal here should be to test encoding and decoding of JSON and binary data and other things that are hard to\ndebug, while testing the game logic itself is not so critical.\n\nAlso see Updating.md for a guide regarding updating the server to a new Minecraft version and the steps to test it.\n\n## Legal Notices\n\nThis project is licensed under the MIT License; see LICENSE for further information.\n\n\"Minecraft\" is a trademark of Mojang Synergies AB.\nCobolCraft is neither affiliated with nor endorsed by Mojang.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeyfa%2Fcobolcraft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeyfa%2Fcobolcraft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeyfa%2Fcobolcraft/lists"}