{"id":21971441,"url":"https://github.com/macmv/bamboo","last_synced_at":"2026-04-02T00:31:47.481Z","repository":{"id":41234144,"uuid":"473842555","full_name":"macmv/bamboo","owner":"macmv","description":"A safe, fast, and secure Minecraft server optimized for minigames. This is a mirror of the Gitlab repo: https://gitlab.com/macmv/bamboo","archived":false,"fork":false,"pushed_at":"2024-01-21T16:52:09.000Z","size":4832,"stargazers_count":25,"open_issues_count":5,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-11-29T14:55:09.635Z","etag":null,"topics":["minecraft","minecraft-server","rust","wasm"],"latest_commit_sha":null,"homepage":"https://gitlab.com/macmv/bamboo","language":"Rust","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/macmv.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}},"created_at":"2022-03-25T02:30:36.000Z","updated_at":"2024-09-16T08:35:47.000Z","dependencies_parsed_at":"2024-11-29T14:50:52.532Z","dependency_job_id":"289f599d-3a2a-4ec9-a6f6-798209171ea6","html_url":"https://github.com/macmv/bamboo","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/macmv/bamboo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macmv%2Fbamboo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macmv%2Fbamboo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macmv%2Fbamboo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macmv%2Fbamboo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/macmv","download_url":"https://codeload.github.com/macmv/bamboo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macmv%2Fbamboo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31293383,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["minecraft","minecraft-server","rust","wasm"],"created_at":"2024-11-29T14:50:26.931Z","updated_at":"2026-04-02T00:31:47.466Z","avatar_url":"https://github.com/macmv.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e\n    \u003cimg src=\"https://gitlab.com/macmv/bamboo/-/raw/main/icon.png\" width=35\u003e\n    Bamboo\n    \u003cimg src=\"https://gitlab.com/macmv/bamboo/-/raw/main/icon.png\" width=35\u003e\n  \u003c/h1\u003e\n\n  [![pipeline status](https://gitlab.com/macmv/bamboo/badges/main/pipeline.svg)](https://gitlab.com/macmv/bamboo/-/pipelines)\n  [![coverage report](https://gitlab.com/macmv/bamboo/badges/main/coverage.svg)](https://app.codecov.io/gl/macmv/bamboo)\n  [![Discord](https://badgen.net/badge/icon/discord?icon=discord\u0026label)](https://discord.gg/8CTr3N9yzU)\n\n  A safe, fast, and secure Minecraft server optimized for minigames.\n\u003c/div\u003e\n\n### How to run\n\nInstall [rust](https://www.rust-lang.org/learn/get-started), and then clone\nthis repository:\n\n```\ngit clone https://gitlab.com/macmv/bamboo.git\ncd bamboo\n```\n\nNow you need to run the server and proxy. Run the server with this command:\n\n```\ncargo run --bin bb_server --release\n```\n\nAnd run the proxy with this command:\n\n```\ncargo run --bin bb_proxy --release\n```\n\nYou need the server and proxy to be running at the same time in order to connect.\nThe proxy will listen for Minecraft clients on port `25565`, and then it will\nconnect to the server on port `8483`. If you get errors when starting the server,\nmake sure nothing else is using that port.\n\nThe `--release` flag will make the server/proxy faster at runtime, but take\nlonger to compile. I recommend using the flag for both, unless you are developing\nthe server or proxy.\n\nAfter running the server or proxy, a file named `server.toml` and `proxy.toml`\nwill be created. These files will have the default configuration for the server\nand proxy. Here you can do things like change the world generation, enable/disable\nplugins, and change online mode for the proxy.\n\nFeel free to ask questions in the [discord](https://discord.gg/8CTr3N9yzU)!\n\n### Writing a Minigame\n\nPanda is the language used for plugins in this server. See the\n[examples](https://gitlab.com/macmv/bamboo/-/tree/main/examples) directory\nfor some examples.\n\nThe [docs](https://macmv.gitlab.io/bamboo/doc/panda/index.html) are\nkept up to date by pipelines, and those should be helpful when writing plugins.\n\nThis language is mostly complete, but the actual interface with the server from\nPanda is not complete at all. These plugins are mostly there to test the\nAPI that I'm writing, and they should contain examples of the newest features\nas I develop them.\n\n### Features\n\nAll of these are planned. I have no time frame for doing these things, but here\nis what I would like to see in a 1.0 release:\n\n- [ ] Minigame lobbies\n  - [ ] The 'default chunk' concept\n    - In a minigame lobby, most chunks are the same. The void chunks that are in\n      render distance, but all empty are still stored in a vanilla server. A\n      default chunk fixes this, and uses a single chunk to send data about all\n      of the empty chunks in the world. This can also be used to optimize things\n      like superflat worlds. This is also why the `Chunk` type does not know\n      it's own position.\n  - [ ] Unbreakable world\n    - This needs to be a flag, for both placing and breaking blocks. It should\n      be very easy to toggle with an admin command.\n  - [ ] Ability to switch worlds\n    - This is a server-only task. It involves clearing all the loaded chunks of\n      the client, sending them a dimension change packet, loading all the new chunks,\n      and spawning them into the new world. This will not be very difficult.\n  - [ ] Ability to switch servers\n    - This is a proxy-based task. It involves a new custom packet that the\n      server sends to the 'client', that the proxy will intercept. This is a\n      more difficult task than switching worlds, but is more valuable for\n      scalability.\n- [ ] Some form of terrain generation\n  - Default chunks are good, and fast, but having terrain generation is very\n    fun. I don't want this to be a minigame-only server, and I really like\n    watching my own terrain generate at very fast speeds.\n  - [ ] Default chunk/Terrain generation should be easily toggleable with an\n        admin command.\n- [ ] (Maybe) support 1000 players on one server\n  - Everything is very multithreaded. This is a very general goal, and is put\n    here as a reminder that things like tick loops are separate for each player.\n- [x] Plugin loading in Panda (custom language)\n  - I really tried to use another language for plugins. It would have been so\n    much simpler to just deal with Python or JavaScript, but I couldn't stand\n    the awful API. So I wrote an entire language for plugins. It's called Panda,\n    and it's specific to this server. You can check it out\n    [here](https://gitlab.com/macmv/panda).\n- [ ] (Unlikely) Plugin loading in Rust\n  - This is a dynamic linking problem. It shouldn't be very difficult, and will\n    allow pluggable functionality from multiple plugins, all without\n    re-compiling the server. This would act very similar to something like\n    Spigot.\n  - This is not a feature I am very interested in. Panda is turning out to\n    be very powerful, and I would like to focus on that. If anyone wants to implement\n    this, feel free to do so. Just note that it must be compatible with Panda\n    plugins. You need to be able to load both Rust and Panda plugins at the\n    same time.\n- [ ] Plugin loading via sockets\n  - Sending messages over a unix socket is fast, and would work pretty well for\n    loading a plugin. At the time of writing, there is a simple python plugin,\n    which can send chat messages and get blocks over a socket. This interface is\n    far more annoying to work with (I need to deal with json), and is very\n    incomplete. PRs are welcome to improve this interface!\n\n### Progress\n\nAt the time of writing, you can join on 1.8, 1.12, and 1.14+. You can interact\nwith the world, send chat messages, run commands, and interact with other players.\nCore concepts like chunk data work well, and are heavily tested.\n\nThis is constantly changing, as I don't update this README that much. To see which\nversions work, I recommend cloning the project and running it yourself. I may also\nhost a public demo server in the future, which will be open for anyone to join.\n\n### Architecture\n\nBamboo uses a proxy-server model. The proxy talks to a Minecraft client over\nthe TCP based Minecraft protocol, and talks to the server over a custom TCP based\nprotocol at the same time. This has a number of benefits, such as performance,\nscalability, and most importantly, cross-versioning. The Minecraft client changes\nits packet definition quite a bit for every version, and supporting all the way\nback to 1.8 means that almost everything is different. Having my own proxy in place\nmeans the server works entirely with latest versioned data, and the proxy handles\nall the older versions.\n\nAs for the server itself, it does a lot of things differently from the vanilla\nserver. For one, there are very few global locks. This server is designed to be\nheavily multithreaded, and to do so, it has a separate tick loop for every\nplayer. Things like redstone, entities moving, and water flowing will be\nimplemented on a region basis. I do not know how large each of these regions\nwill be, but they will be small enough that large redstone machines will run on\nmany different threads at once.\n\nThe main goal for speed on the server is for players. I really want to see 1000\nplayers in one server. I was getting there with the previous implementation:\nwith just a dual-core machine, I was able to support around 150 bots. This is an\nexponentially difficult problem, but it mostly comes down to data transfer. So\nif all of the proxies are running on separate machines, and if the main server\nis on a fast enough machine, it should be possible.\n\n### Modules\n\nAny module on this list depends on at least one of the modules before it in the\nlist.\n\n - `bb_macros`: Contains some small utilities used in bb_server.\n - `bb_transfer`: The server-proxy communication protocol. These\n   packets describe nothing about there format, so it is up the\n   other side to know the protocol spec.\n - `bb_data`: The code generator. This takes prismarine data and\n   generates Rust source.\n - `bb_generated`: The output of `bb_data`. This is a separate\n   crate to improve rebuild times.\n - `bb_common`: Common utilities. These are things like item\n   parsers, UUIDs, etc. This is changed often, so `bb_generated`\n   copies some of the code from here.\n - `bb_server`: The Minecraft server. This is the first binary\n   target.\n - `bb_proxy`: The proxy. This is required for any clients to\n   connection to the server.\n - `bb_cli`: A cli tool, used to connect to a Minecraft server and\n   validate that it is sending good data (things like making sure\n   the client won't leak chunks, checks for keep alive packets, etc).\n\n### For Rust developers\n\nIf you would like to contribute to this project, I welcome your changes! Anything\nin the features list above are all good tasks to work on, and would be very appreciated.\n\nIf you are looking for the generated protocol code, you can go from this project\ndirectory into the generated code directory using this command:\n```bash\n# For the proxy in debug mode:\ncd $(find target/debug/build/bb_proxy*/out | head -n 1)\n# For the proxy in release mode:\ncd $(find target/release/build/bb_proxy*/out | head -n 1)\n# For the server in debug mode:\ncd $(find target/debug/build/bb_server*/out | head -n 1)\n# For the server in release mode:\ncd $(find target/release/build/bb_server*/out | head -n 1)\n```\n\nIf you have run the server/proxy in debug/release mode, then the appropriate command\nshould work. Note that these will all bring you to a directory containing the same\nfolders.\n\nInside this output directory, there will be a folder called `protocol`, which has\n`cb.rs` and `sb.rs` stored. These are the generated protocol files for clientbound\nand serverbound packets.\n\nBecause of some compiler flags I have setup in `Cargo.toml`, I recommend setting\nyour IDE to use a different profile. Any time my IDE builds, I pass the flag\n`--profile rust-analyzer` to cargo. This makes code validation much faster, as\nthe dev profile uses opt-level 2 (instead of the default 0). This is because\nterrain generation is terribly slow with opt-level set to 0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacmv%2Fbamboo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmacmv%2Fbamboo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacmv%2Fbamboo/lists"}