{"id":13775459,"url":"https://github.com/MultiPaper/MultiPaper","last_synced_at":"2025-05-11T07:32:45.620Z","repository":{"id":37022061,"uuid":"330314740","full_name":"MultiPaper/MultiPaper","owner":"MultiPaper","description":"Multi-server, single-world papermc implementation","archived":false,"fork":false,"pushed_at":"2025-05-01T13:34:17.000Z","size":3817,"stargazers_count":1314,"open_issues_count":52,"forks_count":95,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-05-01T14:38:16.528Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://multipaper.io/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MultiPaper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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,"zenodo":null}},"created_at":"2021-01-17T04:36:02.000Z","updated_at":"2025-05-01T13:34:22.000Z","dependencies_parsed_at":"2022-07-12T16:13:20.870Z","dependency_job_id":"7f7eac0f-5c9e-4f90-9adb-d61c2fb32ff0","html_url":"https://github.com/MultiPaper/MultiPaper","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MultiPaper%2FMultiPaper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MultiPaper%2FMultiPaper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MultiPaper%2FMultiPaper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MultiPaper%2FMultiPaper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MultiPaper","download_url":"https://codeload.github.com/MultiPaper/MultiPaper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253534084,"owners_count":21923515,"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":[],"created_at":"2024-08-03T17:01:39.053Z","updated_at":"2025-05-11T07:32:40.599Z","avatar_url":"https://github.com/MultiPaper.png","language":"Java","funding_links":[],"categories":["Server Software"],"sub_categories":["Velocity"],"readme":"# MultiPaper\n\n[![Discord](https://img.shields.io/discord/937309618743427113.svg?color=738ad6\u0026label=Join%20the%20Discord%20server\u0026logo=discord\u0026logoColor=ffffff)](https://discord.gg/dN3WCZkSRV)\n\n**MultiPaper is in public beta.** Most features work for most players most of\nthe time, however things can occasionally break.\n\n1.20.1 [Purpur](https://github.com/PurpurMC/Purpur) fork that enables a server admin\nto scale a single world across multiple servers. Multiple MultiPaper servers run\nthe same world and use a MultiPaper-Master to coordinate with each other and\nstore server data. While the MultiPaper-Master is usually run as a standalone\nserver, it can also be run as a BungeeCord or Velocity plugin, which has some benefits\nincluding being able to send players to the least busy server when they\njoin.\n\nMultiPaper 2.0:\n\n- Works like a CDN\n    - Each server caches chunks that are needed by the players it's serving\n    - The servers keep each others' caches in sync with each other\n    - The servers work together to ensure every chunk gets ticked\n    - Does not require BungeeCord or Velocity, just some load balancing method to evenly\n      distribute players across the servers\n\n- MultiPaper-Master\n    - Stores the world files and data\n    - Coordinates the servers\n        - Decides who gets to tick the chunk (first in first served basis)\n    - Runs as a standalone process\n        - For your convenience, it can also run as a BungeeCord or Velocity plugin\n\n![MultiPaper diagram](assets/multipaper-diagram.jpg)\n\nHow chunk syncing works:\n\n- When a server reads a chunk, it asks the Master to load the chunk from the\n  region file. If another server has ownership of the chunk, the Master will\n  notify the server to request the chunk from that server instead, so that it\n  gets the most up-to-date copy.\n- When the server wants to tick an unowned chunk, it won't, but will instead\n  send a request to the Master to take ownership of it. If ownership is\n  granted, the chunk will be ticked on next tick. If ownership is denied since\n  another server owns it, the server will keep the chunk in sync with that\n  server.\n- A chunk may be loaded on a server but have no owner if it's outside the\n  simulation distance. This is because the chunk won't be ticked by any server.\n- When a server has a chunk loaded into memory, it will subscribe to any\n  changes made within that chunk. This means if any server changes a block\n  inside the chunk, it will be updated on all servers subscribed to that chunk.\n\n## The use case\n\nFor servers that wish to maintain all vanilla mechanics while scaling up,\nMultiPaper is for you. Usually when a Minecraft server chooses to scale their\nplayer count up, they have to sacrifice various mechanics such as render\ndistance, mob spawning, and redstone.\n\nWith MultiPaper, there is no need to ruin the vanilla experience. All you need\nare new servers when you wish to scale. Instead of having 1 server handling\n100 players, you can have 10 servers handling 10 players each. This allows you\nto keep expensive vanilla mechanics like a large render distance, mob farms,\nand massive redstone contraptions.\n\n### It can scale\n\nPerhaps 100 players isn't enough for you. You want to push the limits of your\nMinecraft server to the extreme with upwards of 1000 players online at once.\nWell, MultiPaper is also for you. With its ability to horizontally scale,\nthe hardware's the limit.\n\n## Commands\nMultiPaper includes a few commands mainly for debug purposes:\n\n`/servers`  \nList all servers running on this MultiPaper cluster. Includes performance\nindicators such as TPS, tick duration, and player count.\n\n`/slist`  \nList all online players and what server they're on.\n\n`/mpdebug`  \nToggle a debug visualisation showing chunks that your server is ticking (aqua)\nand chunks being ticked by another server (red). The server ticking the chunk\nyou are standing in is displayed above the action bar.\n\n`/mpmap`  \nShow a map of nearby chunks and which server owns them. Up represents north. If\nyour server owns the chunk, the chunk is shown as aqua. If another server owns\nthe chunk, it's shown as red. If the chunk is in memory but not within\nsimulation range on your server, it's shown as white. Chunks not loaded on your\nserver are shown as grey.\n\n## Setting up MultiPaper\n  * Download MultiPaper and MultiPaper-Master from\n    [multipaper.io](https://multipaper.io/download.html)\n  * Place your worlds inside the directory being used for MultiPaper-Master\n  * Start the MultiPaper-Master by either:\n    * Standalone: `java -jar multipaper-master.jar \u003cport\u003e [optionalProxyPort]`\n    * BungeeCord plugin: Set the port in `plugins/MultiPaperProxy/config.yml`\n    * Velocity plugin: Set the port in `plugins/multipaper-velocity/config.toml`\n  * In each MultiPaper server:\n    * Run the server once the generate the config file `multipaper.yml`\n    * Put the name of the server used in the BungeeCord or Velocity config into `bungeecordName`\n      * If you're not using BungeeCord or Velocity, just make it some unique identifier\n      * eg. `survival1`\n    * Put the address and port of the MultiPaper-Master in `multipaperMasterAddress`\n      * eg. `localhost:35353`\n\n### Command line options\n\nCommand line options are provided that allow the config files server.properties,\nspigot.yml, paper.yml, and multipaper.yml to be overridden for easier\nscalability. For example:\n\n```bash\njava\n  -DbungeecordName=server1\n  -DmultipaperMasterAddress=127.0.0.1:35353\n  -Dproperties.view-distance=16\n  -Dpaper.global.proxies.proxy-protocol=true\n  -Dspigot.world-settings.default.entity-tracking-range.players=128\n  -Dmultipaper.sync-settings.files.files-to-sync-on-startup=\"myconfigfile.yml;plugins/MyPlugin.jar\"\n  -jar multipaper.jar\n```\n\n## The built-in proxy\nMultiPaper provides a proxy (like Bungeecord or Velocity) that can be used to\nhide the multipaper servers behind a single address. The proxy automatically\nselects the multipaper server with the lowest load and forwards the player\nto it. The proxy provides no extra features and is designed to be as fast and\nlight-weight as possible. When using the proxy, you will need to set\n`bungeecord` to `true` in the multipapers' `spigot.yml`.\n\nThis proxy is only available when running a standalone MultiPaper-Master\ninstallation and can be started by specifying a port for it to listen on:\n\n`java -jar multipaper-master.jar \u003cport\u003e [proxy port]`\n\nFor example, to run the MultiPaper-Master on port 35353 and the proxy on port\n25565, you'd run:\n\n`java -jar multipaper-master.jar 35353 25565`\n  \n## Using MultiPaper with plugins\nFor a plugin to work with MultiPaper, it needs to support multiple servers. A\ngood indication of this, but not a guarantee, is if a plugin uses a MySQL\ndatabase.\n\n### Developing a plugin for MultiPaper\nTo make a plugin compatible with MultiPaper, no data must be stored on the\nserver itself and must instead be stored on an external server such as a MySQL\ndatabase.\n\nSome other things to look out for:\n\n  * Caches can prevent the plugin from getting the most up-to-date data.\n  * `PlayerJoinEvent` and `PlayerQuitEvent` will only be called on one server,\n    however other events for the player could be called on any server.\n  * `Bukkit.broadcastMessage` will send the message to all players on all\n    MultiPaper servers.\n  * `Bukkit.getOnlinePlayers` will return the players only on your server. Use\n    `Bukkit.getAllOnlinePlayers` to get the players across all servers.\n  * You can use `Player.isLocalPlayer`, `Chunk.isLocalChunk`, \n    `Location.isChunkLocal`, `Entity.isInLocalChunk`, `Block.isInLocalChunk`\n    to check if its being managed by your server.\n\n### Using the MultiPaper API as a dependency\n\n[![Clojars Project](https://img.shields.io/clojars/v/com.github.puregero/multipaper-api.svg)](https://clojars.org/com.github.puregero/multipaper-api)\n\nIf you want your plugin to still support regular Spigot and Paper servers, we\nrecommend using [MultiLib](https://github.com/MultiPaper/MultiLib) instead.\n\nAdd the following into your build.gradle:\n\n```\nrepositories {\n  maven {\n    url \"https://repo.clojars.org/\"\n  }\n}\n\ndependencies {\n  compile \"com.github.puregero:multipaper-api:1.20.1-R0.1-SNAPSHOT\"\n}\n```\n\nOr in your pom.xml:\n\n```\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003eclojars\u003c/id\u003e\n        \u003curl\u003ehttps://repo.clojars.org/\u003c/url\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecom.github.puregero\u003c/groupId\u003e\n        \u003cartifactId\u003emultipaper-api\u003c/artifactId\u003e\n        \u003cversion\u003e1.20.1-R0.1-SNAPSHOT\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n## Building\nRequirements:\n- You need `git` installed, with a configured user name and email. \n   On windows you need to run from git bash.\n- You need `jdk` 17+ installed to compile (and `jre` 17+ to run)\n\nBuild instructions:\n1. Patch paper with: `./gradlew applyPatches`\n2. Build the multipaper jars with: `./gradlew shadowjar createReobfPaperclipJar`\n3. Get the multipaper jar from `build/libs`\n4. Get the multipaper-master jar from `MultiPaper-Master/build/libs`\n\n## Publishing to maven local\nPublish to your local maven repository with: `./gradlew publishToMavenLocal`\n\nNote for mac users: The latest macOS version includes an incompatible version of\ndiff and you'll need to install a compatible one. Use `brew install diffutils`\nto install it, and then reopen the terminal window.\n\nIf `diff --version` returns the following, it is incompatible and will not work:\n```\nApple diff (based on FreeBSD diff)\n```\n\n### Licensing\n\nAll code is licensed under [GPLv3](LICENSE.txt) excluding MultiPaper-Master\nwhich is licensed under [MIT](MultiPaper-Master/LICENSE.txt).\n\n### Acknowledgements\n\nMultiPaper includes optimisations from both\n[Airplane](https://github.com/TECHNOVE/Airplane) and\n[Pufferfish](https://github.com/pufferfish-gg/Pufferfish).\n\nMultiPaper uses PaperMC's paperweight framework found\n[here](https://github.com/PaperMC/paperweight).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMultiPaper%2FMultiPaper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMultiPaper%2FMultiPaper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMultiPaper%2FMultiPaper/lists"}