commit 59aa8365306970f6a2d556f93efc4ad2a0188605 from: espejo got date: Thu Oct 9 13:37:58 2025 UTC README legible (generado automáticamente desde README.md; no está en el repo original) commit - 756d84a1e28c61c40f90e1b5309c0717aa26e89e commit + 59aa8365306970f6a2d556f93efc4ad2a0188605 blob - /dev/null blob + 4c6d8e25afb883e862e6431fb5a3b8753d31b6a4 (mode 644) --- /dev/null +++ README.txt @@ -0,0 +1,135 @@ +bareiron + +Minimalist Minecraft server for memory-restrictive embedded systems. + +The goal of this project is to enable hosting Minecraft servers on very +weak devices, such as the ESP32. The projects priorities are, in order: +memory usage, performance, and features. Because of this, compliance with +vanilla Minecraft is not guaranteed, nor is it a goal of the project. + + Minecraft version: 1.21.8 + Protocol version: 772 + + [!WARNING] Currently, only the vanilla client is officially supported. + Issues have been reported when using Fabric or similar. + +Quick start +----------- + +For PC x86_64 platforms, grab the latest build binary +https://github.com/p2r3/bareiron/releases/download/latest/bareiron.exe and +run it. The file is a Cosmopolitan polyglot +https://github.com/jart/cosmopolitan, which means itll run on Windows, +Linux, and possibly Mac, despite the file extension. Note that the servers +default settings cannot be reconfigured without compiling from source. + +For microcontrollers, see the section on compilation below. + +Compilation +----------- + +Before compiling, youll need to dump registry data from a vanilla +Minecraft server. On Linux, this can be done automatically using the +extract_registries.sh script. Otherwise, the manual process is as follows: +create a folder called notchian here, and put a Minecraft server JAR in it. +Then, follow this guide +https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Data_Generators +to dump all of the registries (use the second command with the --all flag). +Finally, run build_registries.js with either bun https://bun.sh/, node +https://nodejs.org/en/download, or deno +https://docs.deno.com/runtime/getting_started/installation/. + + To compile on Linux, install gcc and run ./build.sh. + For compiling on Windows, there are a few options: + To compile a native Windows binary: install MSYS2 + https://www.msys2.org/ and open the MSYS2 MINGW64 shell. From + there, run pacman -Sy mingw-w64-x86_64-gcc, navigate to this + projects directory, and run ./build.sh. + To compile a native 32-bit binary (compatible with Windows 95/98, + but why would you ever want that), use the same steps above, except + with pacman -Sy mingw-w64-cross-gcc and ./build.sh --9x. + To compile a MSYS2-linked binary: install MSYS2 + https://www.msys2.org/, and open the MSYS2 MSYS shell. From + there, install gcc (run pacman -Sy gcc), navigate to this projects + directory and run ./build.sh. + To compile and run a Linux binary from Windows: install WSL, and + from there install gcc and run ./build.sh in this projects + directory. + To target an ESP variant, set up a PlatformIO project (select the + ESP-IDF framework, not Arduino) and clone this repository on top of it. + See Configuration below for further steps. For better performance, + consider changing the clock speed and enabling compiler optimizations. + If you dont know how to do this, there are plenty of resources + online. + +Configuration +------------- + +Configuring the server requires compiling it from its source code as +described in the section above. + +Most user-friendly configuration options are available in include/globals.h, +including WiFi credentials for embedded setups. Some other details, like +the MOTD or starting time of day, can be found in src/globals.c. For +everything else, youll have to dig through the code. + +Heres a summary of some of the more important yet less trivial options +for those who plan to use this on a real microcontroller with real players: + + Depending on the player count, the performance of the MCU, and the + bandwidth of your network, player position broadcasting could + potentially throttle your connection. If you find this to be the case, + try commenting out BROADCAST_ALL_MOVEMENT and + SCALE_MOVEMENT_UPDATES_TO_PLAYER_COUNT. This will tie movement to the + tickrate. If this change makes movement too choppy, you can decrease + TIME_BETWEEN_TICKS at the cost of more compute. + If you experience crashes or instability related to chests or water, + those features can be disabled with ALLOW_CHESTS and DO_FLUID_FLOW, + respectively. + If you find frequent repeated chunk generation to choke the server, + increasing VISITED_HISTORY might help. There isnt that much of a + memory footprint for this - increasing it to 64 for example would only + take up 240 extra bytes per allocated player. + +Non-volatile storage (optional) +------------------------------- + +This section applies to those who target ESP variants and wish to persist +world data after a shutdown. This is not necessary on PC platforms, as +world and player data is written to world.bin by default. + +The simplest way to accomplish this is to set up LittleFS in PlatformIO and +comment out the #ifndef surrounding SYNC_WORLD_TO_DISK in globals.h. Since +flash writes are typically slow and blocking, youll likely want to +uncomment DISK_SYNC_BLOCKS_ON_INTERVAL. Depending on the flash size of your +board, you may also have to decrease MAX_BLOCK_CHANGES, so that the world +data fits in your LittleFS partition. + +If using an SD card module or other virtual file system, youll have to +implement the filesystem setup routine on your own. The built-in serializer +should still work though, as it uses POSIX filesystem calls. + +Alternatively, if you cant set up a file system, you can dump and upload +world data over TCP. This can be enabled by uncommenting +DEV_ENABLE_BEEF_DUMPS in globals.h. Note: this system implements no +security or authentication. With this option enabled, anyone with access to +the server can upload arbitrary world data. + +Contribution +------------ + + Create issues and discuss with the maintainer(s) before making pull + requests. Even for small changes. + Follow the existing code style. Ensure that your changes fit in with + the surrounding code, even if you disagree with the style. Pull + requests with inconsistent style will be nitpicked. + Test your code before creating a pull request or requesting a review, + regardless of how simple your change is. Its a basic form of + respect towards the maintainer and reviewer. + Development tooling and compilation improvements are not welcome, + unless youve worked with the codebase long enough to have noticed + practical shortcomings in that area. Adding a single compiler flag is + not a meaningful first contribution. + For information on the Minecraft server protocol, refer to the wiki + https://minecraft.wiki/w/Java_Edition_protocol/Packets. For everything + else, use a search engine https://google.com.